sfos/ledger
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

doc update

Browse source
This commit is contained in:
John Wiegley 2005-02-12 07:40:26 +00:00
parent e0a4109856
commit 76f0d00f40
1 changed files with 151 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

153
ledger.texi
View file

@ -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
<?xml version="1.0"?>
<ledger>
<entry>...</entry>
<entry>...</entry>
<entry>...</entry>...
</ledger>
@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
<entry>
<en:date>2004/03/01</en:date>
<en:cleared/>
<en:code>100</en:code>
<en:payee>John Wiegley</en:payee>
<en:transactions>
<transaction>...</transaction>
<transaction>...</transaction>
<transaction>...</transaction>...
</en:transactions>
</entry>
@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
<transaction>
<tr:account>Expenses:Computer:Hardware</tr:account>
<tr:amount>
<value type="amount">
<amount>
<commodity flags="PT">$</commodity>
<quantity>90.00</quantity>
</amount>
</value>
</tr:amount>
</transaction>
@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
<boolean>true</boolean>
@end smallexample
The format of an integer value is the numerical value surrounded by an
@samp{integer} tag, for example:
@smallexample
<integer>12036</integer>
@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
<value type="amount">
<amount>
<commodity flags="PT">$</commodity>
<quantity>90.00</quantity>
</amount>
</value>
@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
<value type="balance">
<balance>
<amount>
<commodity flags="PT">$</commodity>
<quantity>90.00</quantity>
</amount>
<amount>
<commodity flags="TE">DM</commodity>
<quantity>200.00</quantity>
</amount>
</balance>
</value>
@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