diff --git a/ledger.texi b/ledger.texi index a5fc7b3e..3d5300a9 100644 --- a/ledger.texi +++ b/ledger.texi @@ -58,6 +58,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * Introduction:: * Running Ledger:: * Keeping a ledger:: +* Using XML:: * Extending with Python:: @end menu @@ -2549,7 +2550,7 @@ only, and not against the running total: ledger --forecast "d<[2010]" bal ^assets ^liabilities @end example -@node Keeping a ledger, Extending with Python, Running Ledger, Top +@node Keeping a ledger, Using XML, Running Ledger, Top @chapter Keeping a ledger The most important part of accounting is keeping a good ledger. If @@ -3560,7 +3561,155 @@ accounting ledger, with the attached prefix @samp{Billable}: Receivable:ClientOne @end smallexample -@node Extending with Python, , Keeping a ledger, Top +@node Using XML, Extending with Python, Keeping a ledger, Top +@chapter Using XML + +By default, Ledger uses a human-readable data format, and displays its +reports in a manner meant to be read on screen. For the purpose of +writing tools which use Ledger, however, it is possible to read and +display data using XML. This chapter documents that format. + +The general format used for Ledger data is: + +@smallexample + + + ... + ... + ...... + +@end smallexample + +The data stream is enclosed in a @samp{ledger} tag, which contains a +series of one or more entries. Each @samp{entry} describes the entry +and contains a series of one or more transactions: + +@smallexample + + 2004/03/01 + + 100 + John Wiegley + + ... + ... + ...... + + +@end smallexample + +The date format for @samp{en:date} is always @samp{YYYY/MM/DD}. The +@samp{en:cleared} tag is optional, and indicates whether the +transaction has been cleared or not. There is also an +@samp{en:pending} tag, for marking pending transactions. The +@samp{en:code} and @samp{en:payee} tags both contain whatever text the +user wishes. + +After the initial entry data, there must follow a set of transactions +marked with @samp{en:transactions}. Within this tag is a series of +one or more @samp{transaction}'s, which have the following form: + +@smallexample + + Expenses:Computer:Hardware + + + + $ + 90.00 + + + + +@end smallexample + +This is a basic transaction. It may also be begin with +@samp{tr:virtual} and/or @samp{tr:generated} tags, to indicate virtual +and auto-generated transactions. Then follows the @samp{tr:account} +tag, which contains the full name of the account the transaction is +related to. Colons separate parent from child in an account name. + +Lastly follows the amount of the transaction, indicated by +@samp{tr:amount}. Within this tag is a @samp{value} tag, of which +there are four different kinds, each with its own format: + +@enumerate +@item boolean +@item integer +@item amount +@item balance +@end enumerate + +The format of a boolean value is @samp{true} or @samp{false} +surrounded by a @samp{boolean} tag, for example: + +@smallexample +true +@end smallexample + +The format of an integer value is the numerical value surrounded by an +@samp{integer} tag, for example: + +@smallexample +12036 +@end smallexample + +The format of an amount contains two members, the commodity and the +quantity. The commodity can have a set of flags that indicate how to +display it. The meaning of the flags (all of which are optional) are: + +@table @strong +@item P +The commodity is prefixed to the value. +@item S +The commodity is separated from the value by a space. +@item T +Thousands markers are used to display the amount. +@item E +The format of the amount is European, with period used as a thousands +marker, and comma used as the decimal point. +@end table + +The actual quantity for an amount is an integer of arbitrary size. +Ledger uses the GNU multi-precision math library to handle such +values. The XML format assumes the reader to be equally capable. +Here is an example amount: + +@smallexample + + + $ + 90.00 + + +@end smallexample + +Lastly, a balance value contains a series of amounts, each with a +different commodity. Unlike the name, such a value does need to +balance. It is called a balance because it sums several amounts. For +example: + +@smallexample + + + + $ + 90.00 + + + DM + 200.00 + + + +@end smallexample + +That is the extent of the XML data format used by Ledger. It will +output such data if the @command{xml} command is used, and it can read +such data as long as the @file{xmlparse} library was available at the +time Ledger was built. + +@node Extending with Python, , Using XML, Top @chapter Extending with Python Ledger fully supports Python as an extension language. It may be used