more-file-format-details.pny

# This file contains more details on the Penny file format. Read it if
# you are interested, or if you are getting error messages you don't
# understand when you use penny on your file.

########################################
## - DIGIT GROUPING

# People in different countries use different characters for the radix
# point (decimal point) and to separate digits into groups.  You can
# choose how you wish to represent quantities in your ledger file.
# Penny will remember the way you format each individual quantity and
# the same formatting will be displayed in your reports.

# If you want to use the period as a radix, you can use a comma or a
# space as a grouping character.  If you use a space as a grouping
# character, you have to surround your quantity with curly braces.
# Here's an example:

2012-12-16 The Period Radixland
    Expenses:Periods                                    < $1,284.40
    Expenses:Periods                                    < $ {2 200.99}
    Liabilities:Amex

# To use commas as your radix point, you have to surround your
# quantities with square braces.  Then you can use a period or a space
# as a grouping character.  For example:

2012-12-16 The Comma Radixland
    Expenses:Commas                                     < $ [1.284,40]
    Expenses:Periods                                    < $ [2 200,99]
    Liabilities:Amex

# You can also group digits using the Unicode thin space
# character. This is Unicode code point 2009. Most editors will render
# it the same way they render a space, but it's not the same
# character. Different editors will have different ways to enter this
# character; in Emacs, press C-x 8 <ret> 2009. In Vim, in insert mode
# press Ctrl-V, then u2009.

# If you use a thin space as a grouping character and you use a period
# as a radix point, you don't have to surround your quantity with
# curly braces (though you can if you want.)  However, if you use a
# thin space to group and a comma as a radix, you still have to
# surround your quantity with square braces.  For example:

2012-12-16 The Thin Space
    {Expenses:Thin Spaces}                              < $1 000.00
    {Expenses:Thin Spaces}                              < $[1 000,00]
    Liabilities:Amex

# When you use reports such as the postings report, all values that
# you entered in your ledger will be displayed as you entered them.
# However, some values such as balances have to be calculated, so
# Penny has to decide how to format these quantities.  Generally Penny
# will examine all the quantities you have entered in your ledger for
# a partcular commodity and will format calcualted quantities in the
# same way that you have most often formatted the quantities for that
# commodity.  So, if you are consistent in how you write quantities in
# your ledger file, Penny will use the same formatting for calculated
# quantities.

########################################
## - USE UTF-8

# Use a the UTF-8 Unicode file format when you save your data. UTF-8
# which is the de-facto standard Unicode encoding on Unix systems. If
# you do not want to bother with Unicode, it's best to use just the
# ASCII subset of Unicode.  Since a valid ASCII file is also a valid
# UTF-8 file, you will be fine.  Using a non-Unicode encoding might
# work, but I have not tested that.  Also, using a non-UTF8 Unicode
# encoding might work too, but I have not tested that either.  The
# best thing to do is use UTF-8.

# If you have no idea what all this encoding stuff is about, the first
# thing to remember is that there is no such thing as plain text. Read
# this:

# http://www.joelonsoftware.com/articles/Unicode.html

# Since you can use Unicode, feel free to use whatever currency
# symbols you want:

2012-12-20 Euroworks
    Income:Salary                                       > 2100 €
    Assets:Bank

########################################
## - DATES

# Dates are written in the format YYYY-MM-DD. If the month or the day
# has only one digit, you must use leading zeroes. In addition, dates
# can include a time. Times are written in 24-hour format, either as
# HH:MM or as HH:MM:SS; again, if any component has only one digit,
# you must use a leading zero.

# You can use either a dash or a slash to separate YYYY and the MM and
# the DD.

# All dates and times are considered to be UTC. If you provide a time,
# you may optionally specify the time zone offset by using a leading
# plus or a leading minus.

# Here are some sample postings with various dates and times.

2012-12-17 02:23 Transfer from savings
    Assets:Savings                                      > $200.00
    Assets:Checking                                     < $200.00

2012-12-17 12:23:35 Transfer from savings
    Assets:Savings                                      > $200.00
    Assets:Checking                                     < $200.00

# Eastern time
2012-12-17 14:56:00 -0500 Transfer from savings
    Assets:Savings                                      > $200.00
    Assets:Checking                                     < $200.00

########################################
## - QUOTING

# Usually you can write information in your ledger file without using
# characters to indicate which field is which. However, sometimes if
# you want to use slightly more unusual characters, you have to
# surround that field with characters. Right now all the exact rules
# are available only by examining the source code (sorry).  Here are
# the highlights:

# Accounts can be unquoted if the very first character of the account
# is a letter (capital or lower-case, A-Z or a-z) or any character
# above Unicode code point 127 (e.g. ñ, or é, or í.). In
# addition every other character may be nearly any character except a
# space or an asterisk. Otherwise, you must surround your account with
# curly braces. Example:

2012-12-18 CVS
    {Expenses:Personal Care}                            < $52.35
        'Earplugs
    Liabilities:Amex

# You can assign payees to individual postings as well as to the
# entire transaction. Payees assigned to individual postings must be
# surrounded with tildes. You do not usually have to quote payees that
# are assigned to the whole transaction; however, you do have to quote
# them if the first character is not a letter. Examples:

2012-12-18 ~7-Eleven~
    Expenses:Food                                       < $12.99
    Liabilities:Amex

2012-12-19 Spacely Sprockets
    Income:Salary                                       > $2000.00
    ~State of Maryland~ Expenses:Taxes:State            < $200.00
    ~Healthco~ Expenses:Insurance:Health                < $75.00
    Assets:Checking

# Whether or not you have to quote commodities is complicated.
# Currently this is documented only in the source code (sorry).  The
# full rule set depends on whether the commodity appears on the left
# side or the right side of the quantity. (Whether there is a space
# between the commodity and the quantity is not relevant.)

# However, here is a simple rule that is always true. If your
# commodity name consists ONLY of letters, the dollar sign, and
# non-ASCII characters, you never need to quote it. Since most stock
# ticker symbols are only letters, and because this means that you
# never have to quote lone commodity symbols like $, €, ¥, etc, you
# should not usually have to quote commodities.