summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Doxyfile1406
-rw-r--r--doc/INSTALL234
-rw-r--r--doc/LICENSE28
-rw-r--r--doc/NEWS842
-rw-r--r--doc/README73
-rw-r--r--doc/ledger.texi3961
-rw-r--r--doc/sample.dat26
7 files changed, 6570 insertions, 0 deletions
diff --git a/doc/Doxyfile b/doc/Doxyfile
new file mode 100644
index 00000000..b69be81e
--- /dev/null
+++ b/doc/Doxyfile
@@ -0,0 +1,1406 @@
+# Doxyfile 1.5.5
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project
+#
+# All text after a hash (#) is considered a comment and will be ignored
+# The format is:
+# TAG = value [value, ...]
+# For lists items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (" ")
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+# This tag specifies the encoding used for all characters in the config file
+# that follow. The default is UTF-8 which is also the encoding used for all
+# text before the first occurrence of this tag. Doxygen uses libiconv (or the
+# iconv built into libc) for the transcoding. See
+# http://www.gnu.org/software/libiconv for the list of possible encodings.
+
+DOXYFILE_ENCODING = UTF-8
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
+# by quotes) that should identify the project.
+
+PROJECT_NAME = Ledger
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number.
+# This could be handy for archiving the generated documentation or
+# if some version control system is used.
+
+PROJECT_NUMBER = 3.0
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+# If a relative path is entered, it will be relative to the location
+# where doxygen was started. If left blank the current directory will be used.
+
+OUTPUT_DIRECTORY = %builddir%/doc
+
+# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
+# 4096 sub-directories (in 2 levels) under the output directory of each output
+# format and will distribute the generated files over these directories.
+# Enabling this option can be useful when feeding doxygen a huge amount of
+# source files, where putting all generated files in the same directory would
+# otherwise cause performance problems for the file system.
+
+CREATE_SUBDIRS = NO
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all
+# documentation generated by doxygen is written. Doxygen will use this
+# information to generate all constant output in the proper language.
+# The default language is English, other supported languages are:
+# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional,
+# Croatian, Czech, Danish, Dutch, Farsi, Finnish, French, German, Greek,
+# Hungarian, Italian, Japanese, Japanese-en (Japanese with English messages),
+# Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, Polish,
+# Portuguese, Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish,
+# and Ukrainian.
+
+OUTPUT_LANGUAGE = English
+
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
+# include brief member descriptions after the members that are listed in
+# the file and class documentation (similar to JavaDoc).
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC = YES
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
+# the brief description of a member or function before the detailed description.
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF = YES
+
+# This tag implements a quasi-intelligent brief description abbreviator
+# that is used to form the text in various listings. Each string
+# in this list, if found as the leading text of the brief description, will be
+# stripped from the text and the result after processing the whole list, is
+# used as the annotated text. Otherwise, the brief description is used as-is.
+# If left blank, the following values are used ("$name" is automatically
+# replaced with the name of the entity): "The $name class" "The $name widget"
+# "The $name file" "is" "provides" "specifies" "contains"
+# "represents" "a" "an" "the"
+
+ABBREVIATE_BRIEF = "The $name class" \
+ "The $name widget" \
+ "The $name file" \
+ is \
+ provides \
+ specifies \
+ contains \
+ represents \
+ a \
+ an \
+ the
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC = NO
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
+# inherited members of a class in the documentation of that class as if those
+# members were ordinary class members. Constructors, destructors and assignment
+# operators of the base classes will not be shown.
+
+INLINE_INHERITED_MEMB = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
+# path before files name in the file list and in the header files. If set
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES = YES
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
+# can be used to strip a user-defined part of the path. Stripping is
+# only done if one of the specified strings matches the left-hand part of
+# the path. The tag can be used to show relative paths in the file list.
+# If left blank the directory from which doxygen is run is used as the
+# path to strip.
+
+STRIP_FROM_PATH = /Applications/
+
+# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of
+# the path mentioned in the documentation of a class, which tells
+# the reader which header file to include in order to use a class.
+# If left blank only the name of the header file containing the class
+# definition is used. Otherwise one should specify the include paths that
+# are normally passed to the compiler using the -I flag.
+
+STRIP_FROM_INC_PATH =
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
+# (but less readable) file names. This can be useful is your file systems
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES = NO
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
+# will interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description. If set to NO, the JavaDoc
+# comments will behave just like regular Qt-style comments
+# (thus requiring an explicit @brief command for a brief description.)
+
+JAVADOC_AUTOBRIEF = NO
+
+# If the QT_AUTOBRIEF tag is set to YES then Doxygen will
+# interpret the first line (until the first dot) of a Qt-style
+# comment as the brief description. If set to NO, the comments
+# will behave just like regular Qt-style comments (thus requiring
+# an explicit \brief command for a brief description.)
+
+QT_AUTOBRIEF = NO
+
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
+# treat a multi-line C++ special comment block (i.e. a block of //! or ///
+# comments) as a brief description. This used to be the default behaviour.
+# The new default is to treat a multi-line C++ comment block as a detailed
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = NO
+
+# If the DETAILS_AT_TOP tag is set to YES then Doxygen
+# will output the detailed description near the top, like JavaDoc.
+# If set to NO, the detailed description appears after the member
+# documentation.
+
+DETAILS_AT_TOP = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
+# member inherits the documentation from any documented member that it
+# re-implements.
+
+INHERIT_DOCS = YES
+
+# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
+# a new page for each member. If set to NO, the documentation of a member will
+# be part of the file/class/namespace that contains it.
+
+SEPARATE_MEMBER_PAGES = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE = 8
+
+# This tag can be used to specify a number of aliases that acts
+# as commands in the documentation. An alias has the form "name=value".
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to
+# put the command \sideeffect (or @sideeffect) in the documentation, which
+# will result in a user-defined paragraph with heading "Side Effects:".
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES =
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
+# sources only. Doxygen will then generate output that is more tailored for C.
+# For instance, some of the names that are used will be different. The list
+# of all members will be omitted, etc.
+
+OPTIMIZE_OUTPUT_FOR_C = NO
+
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
+# sources only. Doxygen will then generate output that is more tailored for
+# Java. For instance, namespaces will be presented as packages, qualified
+# scopes will look different, etc.
+
+OPTIMIZE_OUTPUT_JAVA = NO
+
+# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran
+# sources only. Doxygen will then generate output that is more tailored for
+# Fortran.
+
+OPTIMIZE_FOR_FORTRAN = NO
+
+# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL
+# sources. Doxygen will then generate output that is tailored for
+# VHDL.
+
+OPTIMIZE_OUTPUT_VHDL = NO
+
+# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
+# to include (a tag file for) the STL sources as input, then you should
+# set this tag to YES in order to let doxygen match functions declarations and
+# definitions whose arguments contain STL classes (e.g. func(std::string); v.s.
+# func(std::string) {}). This also make the inheritance and collaboration
+# diagrams that involve STL classes more complete and accurate.
+
+BUILTIN_STL_SUPPORT = YES
+
+# If you use Microsoft's C++/CLI language, you should set this option to YES to
+# enable parsing support.
+
+CPP_CLI_SUPPORT = NO
+
+# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only.
+# Doxygen will parse them like normal C++ but will assume all classes use public
+# instead of private inheritance when no explicit protection keyword is present.
+
+SIP_SUPPORT = NO
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
+# tag is set to YES, then doxygen will reuse the documentation of the first
+# member in the group (if any) for the other members of the group. By default
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC = NO
+
+# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
+# the same type (for instance a group of public functions) to be put as a
+# subgroup of that type (e.g. under the Public Functions section). Set it to
+# NO to prevent subgrouping. Alternatively, this can be done per class using
+# the \nosubgrouping command.
+
+SUBGROUPING = YES
+
+# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum
+# is documented as struct, union, or enum with the name of the typedef. So
+# typedef struct TypeS {} TypeT, will appear in the documentation as a struct
+# with name TypeT. When disabled the typedef will appear as a member of a file,
+# namespace, or class. And the struct will be named TypeS. This can typically
+# be useful for C code in case the coding convention dictates that all compound
+# types are typedef'ed and only the typedef is referenced, never the tag name.
+
+TYPEDEF_HIDES_STRUCT = NO
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
+# documentation are documented, even if no documentation was available.
+# Private class members and static file members will be hidden unless
+# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
+
+EXTRACT_ALL = NO
+
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
+# will be included in the documentation.
+
+EXTRACT_PRIVATE = NO
+
+# If the EXTRACT_STATIC tag is set to YES all static members of a file
+# will be included in the documentation.
+
+EXTRACT_STATIC = NO
+
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
+# defined locally in source files will be included in the documentation.
+# If set to NO only classes defined in header files are included.
+
+EXTRACT_LOCAL_CLASSES = YES
+
+# This flag is only useful for Objective-C code. When set to YES local
+# methods, which are defined in the implementation section but not in
+# the interface are included in the documentation.
+# If set to NO (the default) only methods in the interface are included.
+
+EXTRACT_LOCAL_METHODS = NO
+
+# If this flag is set to YES, the members of anonymous namespaces will be
+# extracted and appear in the documentation as a namespace called
+# 'anonymous_namespace{file}', where file will be replaced with the base
+# name of the file that contains the anonymous namespace. By default
+# anonymous namespace are hidden.
+
+EXTRACT_ANON_NSPACES = NO
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
+# undocumented members of documented classes, files or namespaces.
+# If set to NO (the default) these members will be included in the
+# various overviews, but no documentation section is generated.
+# This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_MEMBERS = YES
+
+# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
+# undocumented classes that are normally visible in the class hierarchy.
+# If set to NO (the default) these classes will be included in the various
+# overviews. This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_CLASSES = YES
+
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
+# friend (class|struct|union) declarations.
+# If set to NO (the default) these declarations will be included in the
+# documentation.
+
+HIDE_FRIEND_COMPOUNDS = NO
+
+# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
+# documentation blocks found inside the body of a function.
+# If set to NO (the default) these blocks will be appended to the
+# function's detailed documentation block.
+
+HIDE_IN_BODY_DOCS = NO
+
+# The INTERNAL_DOCS tag determines if documentation
+# that is typed after a \internal command is included. If the tag is set
+# to NO (the default) then the documentation will be excluded.
+# Set it to YES to include the internal documentation.
+
+INTERNAL_DOCS = NO
+
+# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
+# file names in lower-case letters. If set to YES upper-case letters are also
+# allowed. This is useful if you have classes or files whose names only differ
+# in case and if your file system supports case sensitive file names. Windows
+# and Mac users are advised to set this option to NO.
+
+CASE_SENSE_NAMES = NO
+
+# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
+# will show members with their full class and namespace scopes in the
+# documentation. If set to YES the scope will be hidden.
+
+HIDE_SCOPE_NAMES = NO
+
+# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
+# will put a list of the files that are included by a file in the documentation
+# of that file.
+
+SHOW_INCLUDE_FILES = YES
+
+# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
+# is inserted in the documentation for inline members.
+
+INLINE_INFO = YES
+
+# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
+# will sort the (detailed) documentation of file and class members
+# alphabetically by member name. If set to NO the members will appear in
+# declaration order.
+
+SORT_MEMBER_DOCS = YES
+
+# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
+# brief documentation of file, namespace and class members alphabetically
+# by member name. If set to NO (the default) the members will appear in
+# declaration order.
+
+SORT_BRIEF_DOCS = NO
+
+# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the
+# hierarchy of group names into alphabetical order. If set to NO (the default)
+# the group names will appear in their defined order.
+
+SORT_GROUP_NAMES = NO
+
+# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be
+# sorted by fully-qualified names, including namespaces. If set to
+# NO (the default), the class list will be sorted only by class name,
+# not including the namespace part.
+# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
+# Note: This option applies only to the class list, not to the
+# alphabetical list.
+
+SORT_BY_SCOPE_NAME = NO
+
+# The GENERATE_TODOLIST tag can be used to enable (YES) or
+# disable (NO) the todo list. This list is created by putting \todo
+# commands in the documentation.
+
+GENERATE_TODOLIST = YES
+
+# The GENERATE_TESTLIST tag can be used to enable (YES) or
+# disable (NO) the test list. This list is created by putting \test
+# commands in the documentation.
+
+GENERATE_TESTLIST = YES
+
+# The GENERATE_BUGLIST tag can be used to enable (YES) or
+# disable (NO) the bug list. This list is created by putting \bug
+# commands in the documentation.
+
+GENERATE_BUGLIST = YES
+
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
+# disable (NO) the deprecated list. This list is created by putting
+# \deprecated commands in the documentation.
+
+GENERATE_DEPRECATEDLIST= YES
+
+# The ENABLED_SECTIONS tag can be used to enable conditional
+# documentation sections, marked by \if sectionname ... \endif.
+
+ENABLED_SECTIONS =
+
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
+# the initial value of a variable or define consists of for it to appear in
+# the documentation. If the initializer consists of more lines than specified
+# here it will be hidden. Use a value of 0 to hide initializers completely.
+# The appearance of the initializer of individual variables and defines in the
+# documentation can be controlled using \showinitializer or \hideinitializer
+# command in the documentation regardless of this setting.
+
+MAX_INITIALIZER_LINES = 30
+
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
+# at the bottom of the documentation of classes and structs. If set to YES the
+# list will mention the files that were used to generate the documentation.
+
+SHOW_USED_FILES = YES
+
+# If the sources in your project are distributed over multiple directories
+# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
+# in the documentation. The default is NO.
+
+SHOW_DIRECTORIES = NO
+
+# The FILE_VERSION_FILTER tag can be used to specify a program or script that
+# doxygen should invoke to get the current version for each file (typically from
+# the version control system). Doxygen will invoke the program by executing (via
+# popen()) the command <command> <input-file>, where <command> is the value of
+# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file
+# provided by doxygen. Whatever the program writes to standard output
+# is used as the file version. See the manual for examples.
+
+FILE_VERSION_FILTER =
+
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+# The QUIET tag can be used to turn on/off the messages that are generated
+# by doxygen. Possible values are YES and NO. If left blank NO is used.
+
+QUIET = NO
+
+# The WARNINGS tag can be used to turn on/off the warning messages that are
+# generated by doxygen. Possible values are YES and NO. If left blank
+# NO is used.
+
+WARNINGS = YES
+
+# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
+# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
+# automatically be disabled.
+
+WARN_IF_UNDOCUMENTED = YES
+
+# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
+# potential errors in the documentation, such as not documenting some
+# parameters in a documented function, or documenting parameters that
+# don't exist or using markup commands wrongly.
+
+WARN_IF_DOC_ERROR = YES
+
+# This WARN_NO_PARAMDOC option can be abled to get warnings for
+# functions that are documented, but have no documentation for their parameters
+# or return value. If set to NO (the default) doxygen will only warn about
+# wrong or incomplete parameter documentation, but not about the absence of
+# documentation.
+
+WARN_NO_PARAMDOC = NO
+
+# The WARN_FORMAT tag determines the format of the warning messages that
+# doxygen can produce. The string should contain the $file, $line, and $text
+# tags, which will be replaced by the file and line number from which the
+# warning originated and the warning text. Optionally the format may contain
+# $version, which will be replaced by the version of the file (if it could
+# be obtained via FILE_VERSION_FILTER)
+
+WARN_FORMAT = "$file:$line: $text"
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning
+# and error messages should be written. If left blank the output is written
+# to stderr.
+
+WARN_LOGFILE =
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# The INPUT tag can be used to specify the files and/or directories that contain
+# documented source files. You may enter file names like "myfile.cpp" or
+# directories like "/usr/src/myproject". Separate the files or directories
+# with spaces.
+
+INPUT = %srcdir%/src %srcdir%/test/unit
+
+# This tag can be used to specify the character encoding of the source files
+# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
+# also the default input encoding. Doxygen uses libiconv (or the iconv built
+# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for
+# the list of possible encodings.
+
+INPUT_ENCODING = UTF-8
+
+# If the value of the INPUT tag contains directories, you can use the
+# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank the following patterns are tested:
+# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx
+# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90
+
+FILE_PATTERNS = *.c \
+ *.cc \
+ *.cxx \
+ *.cpp \
+ *.c++ \
+ *.d \
+ *.java \
+ *.ii \
+ *.ixx \
+ *.ipp \
+ *.i++ \
+ *.inl \
+ *.h \
+ *.hh \
+ *.hxx \
+ *.hpp \
+ *.h++ \
+ *.idl \
+ *.odl \
+ *.cs \
+ *.php \
+ *.php3 \
+ *.inc \
+ *.m \
+ *.mm \
+ *.dox \
+ *.py \
+ *.C \
+ *.CC \
+ *.C++ \
+ *.II \
+ *.I++ \
+ *.H \
+ *.HH \
+ *.H++ \
+ *.CS \
+ *.PHP \
+ *.PHP3 \
+ *.M \
+ *.MM \
+ *.PY
+
+# The RECURSIVE tag can be used to turn specify whether or not subdirectories
+# should be searched for input files as well. Possible values are YES and NO.
+# If left blank NO is used.
+
+RECURSIVE = NO
+
+# The EXCLUDE tag can be used to specify files and/or directories that should
+# excluded from the INPUT source files. This way you can easily exclude a
+# subdirectory from a directory tree whose root is specified with the INPUT tag.
+
+EXCLUDE =
+
+# The EXCLUDE_SYMLINKS tag can be used select whether or not files or
+# directories that are symbolic links (a Unix filesystem feature) are excluded
+# from the input.
+
+EXCLUDE_SYMLINKS = NO
+
+# If the value of the INPUT tag contains directories, you can use the
+# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
+# certain files from those directories. Note that the wildcards are matched
+# against the file with absolute path, so to exclude all test directories
+# for example use the pattern */test/*
+
+EXCLUDE_PATTERNS =
+
+# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
+# (namespaces, classes, functions, etc.) that should be excluded from the
+# output. The symbol name can be a fully qualified name, a word, or if the
+# wildcard * is used, a substring. Examples: ANamespace, AClass,
+# AClass::ANamespace, ANamespace::*Test
+
+EXCLUDE_SYMBOLS =
+
+# The EXAMPLE_PATH tag can be used to specify one or more files or
+# directories that contain example code fragments that are included (see
+# the \include command).
+
+EXAMPLE_PATH =
+
+# If the value of the EXAMPLE_PATH tag contains directories, you can use the
+# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank all files are included.
+
+EXAMPLE_PATTERNS = *
+
+# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
+# searched for input files to be used with the \include or \dontinclude
+# commands irrespective of the value of the RECURSIVE tag.
+# Possible values are YES and NO. If left blank NO is used.
+
+EXAMPLE_RECURSIVE = NO
+
+# The IMAGE_PATH tag can be used to specify one or more files or
+# directories that contain image that are included in the documentation (see
+# the \image command).
+
+IMAGE_PATH =
+
+# The INPUT_FILTER tag can be used to specify a program that doxygen should
+# invoke to filter for each input file. Doxygen will invoke the filter program
+# by executing (via popen()) the command <filter> <input-file>, where <filter>
+# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
+# input file. Doxygen will then use the output that the filter program writes
+# to standard output. If FILTER_PATTERNS is specified, this tag will be
+# ignored.
+
+INPUT_FILTER =
+
+# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
+# basis. Doxygen will compare the file name with each pattern and apply the
+# filter if there is a match. The filters are a list of the form:
+# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further
+# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER
+# is applied to all files.
+
+FILTER_PATTERNS =
+
+# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
+# INPUT_FILTER) will be used to filter the input files when producing source
+# files to browse (i.e. when SOURCE_BROWSER is set to YES).
+
+FILTER_SOURCE_FILES = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+# If the SOURCE_BROWSER tag is set to YES then a list of source files will
+# be generated. Documented entities will be cross-referenced with these sources.
+# Note: To get rid of all source code in the generated output, make sure also
+# VERBATIM_HEADERS is set to NO.
+
+SOURCE_BROWSER = YES
+
+# Setting the INLINE_SOURCES tag to YES will include the body
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES = NO
+
+# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
+# doxygen to hide any special comment blocks from generated source code
+# fragments. Normal C and C++ comments will always remain visible.
+
+STRIP_CODE_COMMENTS = YES
+
+# If the REFERENCED_BY_RELATION tag is set to YES (the default)
+# then for each documented function all documented
+# functions referencing it will be listed.
+
+REFERENCED_BY_RELATION = YES
+
+# If the REFERENCES_RELATION tag is set to YES (the default)
+# then for each documented function all documented entities
+# called/used by that function will be listed.
+
+REFERENCES_RELATION = YES
+
+# If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
+# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
+# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
+# link to the source code. Otherwise they will link to the documentstion.
+
+REFERENCES_LINK_SOURCE = YES
+
+# If the USE_HTAGS tag is set to YES then the references to source code
+# will point to the HTML generated by the htags(1) tool instead of doxygen
+# built-in source browser. The htags tool is part of GNU's global source
+# tagging system (see http://www.gnu.org/software/global/global.html). You
+# will need version 4.8.6 or higher.
+
+USE_HTAGS = NO
+
+# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
+# will generate a verbatim copy of the header file for each class for
+# which an include is specified. Set to NO to disable this.
+
+VERBATIM_HEADERS = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
+# of all compounds will be generated. Enable this if the project
+# contains a lot of classes, structs, unions or interfaces.
+
+ALPHABETICAL_INDEX = NO
+
+# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
+# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
+# in which this list will be split (can be a number in the range [1..20])
+
+COLS_IN_ALPHA_INDEX = 5
+
+# In case all classes in a project start with a common prefix, all
+# classes will be put under the same header in the alphabetical index.
+# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
+# should be ignored while generating the index headers.
+
+IGNORE_PREFIX =
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
+# generate HTML output.
+
+GENERATE_HTML = YES
+
+# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `html' will be used as the default path.
+
+HTML_OUTPUT = html
+
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
+# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
+# doxygen will generate files with .html extension.
+
+HTML_FILE_EXTENSION = .html
+
+# The HTML_HEADER tag can be used to specify a personal HTML header for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard header.
+
+HTML_HEADER =
+
+# The HTML_FOOTER tag can be used to specify a personal HTML footer for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard footer.
+
+HTML_FOOTER =
+
+# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
+# style sheet that is used by each HTML page. It can be used to
+# fine-tune the look of the HTML output. If the tag is left blank doxygen
+# will generate a default style sheet. Note that doxygen will try to copy
+# the style sheet file to the HTML output directory, so don't put your own
+# stylesheet in the HTML output directory as well, or it will be erased!
+
+HTML_STYLESHEET =
+
+# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
+# files or namespaces will be aligned in HTML using tables. If set to
+# NO a bullet list will be used.
+
+HTML_ALIGN_MEMBERS = YES
+
+# If the GENERATE_HTMLHELP tag is set to YES, additional index files
+# will be generated that can be used as input for tools like the
+# Microsoft HTML help workshop to generate a compiled HTML help file (.chm)
+# of the generated HTML documentation.
+
+GENERATE_HTMLHELP = NO
+
+# If the GENERATE_DOCSET tag is set to YES, additional index files
+# will be generated that can be used as input for Apple's Xcode 3
+# integrated development environment, introduced with OSX 10.5 (Leopard).
+# To create a documentation set, doxygen will generate a Makefile in the
+# HTML output directory. Running make will produce the docset in that
+# directory and running "make install" will install the docset in
+# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find
+# it at startup.
+
+GENERATE_DOCSET = NO
+
+# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the
+# feed. A documentation feed provides an umbrella under which multiple
+# documentation sets from a single provider (such as a company or product suite)
+# can be grouped.
+
+DOCSET_FEEDNAME = "Doxygen generated docs"
+
+# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that
+# should uniquely identify the documentation set bundle. This should be a
+# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen
+# will append .docset to the name.
+
+DOCSET_BUNDLE_ID = org.doxygen.Project
+
+# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
+# documentation will contain sections that can be hidden and shown after the
+# page has loaded. For this to work a browser that supports
+# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox
+# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari).
+
+HTML_DYNAMIC_SECTIONS = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
+# be used to specify the file name of the resulting .chm file. You
+# can add a path in front of the file if the result should not be
+# written to the html output directory.
+
+CHM_FILE =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can
+# be used to specify the location (absolute path including file name) of
+# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run
+# the HTML help compiler on the generated index.hhp.
+
+HHC_LOCATION =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
+# controls if a separate .chi index file is generated (YES) or that
+# it should be included in the master .chm file (NO).
+
+GENERATE_CHI = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
+# controls whether a binary table of contents is generated (YES) or a
+# normal table of contents (NO) in the .chm file.
+
+BINARY_TOC = NO
+
+# The TOC_EXPAND flag can be set to YES to add extra items for group members
+# to the contents of the HTML help documentation and to the tree view.
+
+TOC_EXPAND = NO
+
+# The DISABLE_INDEX tag can be used to turn on/off the condensed index at
+# top of each HTML page. The value NO (the default) enables the index and
+# the value YES disables it.
+
+DISABLE_INDEX = NO
+
+# This tag can be used to set the number of enum values (range [1..20])
+# that doxygen will group on one line in the generated HTML documentation.
+
+ENUM_VALUES_PER_LINE = 4
+
+# If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
+# generated containing a tree-like index structure (just like the one that
+# is generated for HTML Help). For this to work a browser that supports
+# JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+,
+# Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are
+# probably better off using the HTML help feature.
+
+GENERATE_TREEVIEW = YES
+
+# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
+# used to set the initial width (in pixels) of the frame in which the tree
+# is shown.
+
+TREEVIEW_WIDTH = 250
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
+# generate Latex output.
+
+GENERATE_LATEX = YES
+
+# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `latex' will be used as the default path.
+
+LATEX_OUTPUT = latex
+
+# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
+# invoked. If left blank `latex' will be used as the default command name.
+
+LATEX_CMD_NAME = latex
+
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
+# generate index for LaTeX. If left blank `makeindex' will be used as the
+# default command name.
+
+MAKEINDEX_CMD_NAME = makeindex
+
+# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
+# LaTeX documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_LATEX = NO
+
+# The PAPER_TYPE tag can be used to set the paper type that is used
+# by the printer. Possible values are: a4, a4wide, letter, legal and
+# executive. If left blank a4wide will be used.
+
+PAPER_TYPE = usletter
+
+# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
+# packages that should be included in the LaTeX output.
+
+EXTRA_PACKAGES =
+
+# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
+# the generated latex document. The header should contain everything until
+# the first chapter. If it is left blank doxygen will generate a
+# standard header. Notice: only use this tag if you know what you are doing!
+
+LATEX_HEADER =
+
+# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
+# is prepared for conversion to pdf (using ps2pdf). The pdf file will
+# contain links (just like the HTML output) instead of page references
+# This makes the output suitable for online browsing using a pdf viewer.
+
+PDF_HYPERLINKS = YES
+
+# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
+# plain latex in the generated Makefile. Set this option to YES to get a
+# higher quality PDF documentation.
+
+USE_PDFLATEX = YES
+
+# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
+# command to the generated LaTeX files. This will instruct LaTeX to keep
+# running if errors occur, instead of asking the user for help.
+# This option is also used when generating formulas in HTML.
+
+LATEX_BATCHMODE = NO
+
+# If LATEX_HIDE_INDICES is set to YES then doxygen will not
+# include the index chapters (such as File Index, Compound Index, etc.)
+# in the output.
+
+LATEX_HIDE_INDICES = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
+# The RTF output is optimized for Word 97 and may not look very pretty with
+# other RTF readers or editors.
+
+GENERATE_RTF = NO
+
+# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `rtf' will be used as the default path.
+
+RTF_OUTPUT = rtf
+
+# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
+# RTF documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_RTF = NO
+
+# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
+# will contain hyperlink fields. The RTF file will
+# contain links (just like the HTML output) instead of page references.
+# This makes the output suitable for online browsing using WORD or other
+# programs which support those fields.
+# Note: wordpad (write) and others do not support links.
+
+RTF_HYPERLINKS = NO
+
+# Load stylesheet definitions from file. Syntax is similar to doxygen's
+# config file, i.e. a series of assignments. You only have to provide
+# replacements, missing definitions are set to their default value.
+
+RTF_STYLESHEET_FILE =
+
+# Set optional variables used in the generation of an rtf document.
+# Syntax is similar to doxygen's config file.
+
+RTF_EXTENSIONS_FILE =
+
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
+# generate man pages
+
+GENERATE_MAN = NO
+
+# The MAN_OUTPUT tag is used to specify where the man pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `man' will be used as the default path.
+
+MAN_OUTPUT = man
+
+# The MAN_EXTENSION tag determines the extension that is added to
+# the generated man pages (default is the subroutine's section .3)
+
+MAN_EXTENSION = .3
+
+# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
+# then it will generate one additional man file for each entity
+# documented in the real man page(s). These additional files
+# only source the real man page, but without them the man command
+# would be unable to find the correct page. The default is NO.
+
+MAN_LINKS = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_XML tag is set to YES Doxygen will
+# generate an XML file that captures the structure of
+# the code including all documentation.
+
+GENERATE_XML = NO
+
+# The XML_OUTPUT tag is used to specify where the XML pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `xml' will be used as the default path.
+
+XML_OUTPUT = xml
+
+# The XML_SCHEMA tag can be used to specify an XML schema,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_SCHEMA =
+
+# The XML_DTD tag can be used to specify an XML DTD,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_DTD =
+
+# If the XML_PROGRAMLISTING tag is set to YES Doxygen will
+# dump the program listings (including syntax highlighting
+# and cross-referencing information) to the XML output. Note that
+# enabling this will significantly increase the size of the XML output.
+
+XML_PROGRAMLISTING = YES
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
+# generate an AutoGen Definitions (see autogen.sf.net) file
+# that captures the structure of the code including all
+# documentation. Note that this feature is still experimental
+# and incomplete at the moment.
+
+GENERATE_AUTOGEN_DEF = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_PERLMOD tag is set to YES Doxygen will
+# generate a Perl module file that captures the structure of
+# the code including all documentation. Note that this
+# feature is still experimental and incomplete at the
+# moment.
+
+GENERATE_PERLMOD = NO
+
+# If the PERLMOD_LATEX tag is set to YES Doxygen will generate
+# the necessary Makefile rules, Perl scripts and LaTeX code to be able
+# to generate PDF and DVI output from the Perl module output.
+
+PERLMOD_LATEX = NO
+
+# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be
+# nicely formatted so it can be parsed by a human reader. This is useful
+# if you want to understand what is going on. On the other hand, if this
+# tag is set to NO the size of the Perl module output will be much smaller
+# and Perl will parse it just the same.
+
+PERLMOD_PRETTY = YES
+
+# The names of the make variables in the generated doxyrules.make file
+# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX.
+# This is useful so different doxyrules.make files included by the same
+# Makefile don't overwrite each other's variables.
+
+PERLMOD_MAKEVAR_PREFIX =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
+# evaluate all C-preprocessor directives found in the sources and include
+# files.
+
+ENABLE_PREPROCESSING = YES
+
+# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
+# names in the source code. If set to NO (the default) only conditional
+# compilation will be performed. Macro expansion can be done in a controlled
+# way by setting EXPAND_ONLY_PREDEF to YES.
+
+MACRO_EXPANSION = NO
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
+# then the macro expansion is limited to the macros specified with the
+# PREDEFINED and EXPAND_AS_DEFINED tags.
+
+EXPAND_ONLY_PREDEF = NO
+
+# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
+# in the INCLUDE_PATH (see below) will be search if a #include is found.
+
+SEARCH_INCLUDES = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by
+# the preprocessor.
+
+INCLUDE_PATH =
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will
+# be used.
+
+INCLUDE_FILE_PATTERNS =
+
+# The PREDEFINED tag can be used to specify one or more macro names that
+# are defined before the preprocessor is started (similar to the -D option of
+# gcc). The argument of the tag is a list of macros of the form: name
+# or name=definition (no spaces). If the definition and the = are
+# omitted =1 is assumed. To prevent a macro definition from being
+# undefined via #undef or recursively expanded use the := operator
+# instead of the = operator.
+
+PREDEFINED =
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
+# this tag can be used to specify a list of macro names that should be expanded.
+# The macro definition that is found in the sources will be used.
+# Use the PREDEFINED tag if you want to use a different macro definition.
+
+EXPAND_AS_DEFINED =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
+# doxygen's preprocessor will remove all function-like macros that are alone
+# on a line, have an all uppercase name, and do not end with a semicolon. Such
+# function macros are typically used for boiler-plate code, and will confuse
+# the parser if not removed.
+
+SKIP_FUNCTION_MACROS = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+
+# The TAGFILES option can be used to specify one or more tagfiles.
+# Optionally an initial location of the external documentation
+# can be added for each tagfile. The format of a tag file without
+# this location is as follows:
+# TAGFILES = file1 file2 ...
+# Adding location for the tag files is done as follows:
+# TAGFILES = file1=loc1 "file2 = loc2" ...
+# where "loc1" and "loc2" can be relative or absolute paths or
+# URLs. If a location is present for each tag, the installdox tool
+# does not have to be run to correct the links.
+# Note that each tag file must have a unique name
+# (where the name does NOT include the path)
+# If a tag file is not located in the directory in which doxygen
+# is run, you must also specify the path to the tagfile here.
+
+TAGFILES =
+
+# When a file name is specified after GENERATE_TAGFILE, doxygen will create
+# a tag file that is based on the input files it reads.
+
+GENERATE_TAGFILE =
+
+# If the ALLEXTERNALS tag is set to YES all external classes will be listed
+# in the class index. If set to NO only the inherited external classes
+# will be listed.
+
+ALLEXTERNALS = NO
+
+# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will
+# be listed.
+
+EXTERNAL_GROUPS = YES
+
+# The PERL_PATH should be the absolute path and name of the perl script
+# interpreter (i.e. the result of `which perl').
+
+PERL_PATH = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
+# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base
+# or super classes. Setting the tag to NO turns the diagrams off. Note that
+# this option is superseded by the HAVE_DOT option below. This is only a
+# fallback. It is recommended to install and use dot, since it yields more
+# powerful graphs.
+
+CLASS_DIAGRAMS = YES
+
+# You can define message sequence charts within doxygen comments using the \msc
+# command. Doxygen will then run the mscgen tool (see
+# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the
+# documentation. The MSCGEN_PATH tag allows you to specify the directory where
+# the mscgen tool resides. If left empty the tool is assumed to be found in the
+# default search path.
+
+MSCGEN_PATH =
+
+# If set to YES, the inheritance and collaboration graphs will hide
+# inheritance and usage relations if the target is undocumented
+# or is not a class.
+
+HIDE_UNDOC_RELATIONS = YES
+
+# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
+# available from the path. This tool is part of Graphviz, a graph visualization
+# toolkit from AT&T and Lucent Bell Labs. The other options in this section
+# have no effect if this option is set to NO (the default)
+
+HAVE_DOT = YES
+
+# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect inheritance relations. Setting this tag to YES will force the
+# the CLASS_DIAGRAMS tag to NO.
+
+CLASS_GRAPH = YES
+
+# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect implementation dependencies (inheritance, containment, and
+# class references variables) of the class with other documented classes.
+
+COLLABORATION_GRAPH = YES
+
+# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for groups, showing the direct groups dependencies
+
+GROUP_GRAPHS = YES
+
+# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
+# collaboration diagrams in a style similar to the OMG's Unified Modeling
+# Language.
+
+UML_LOOK = YES
+
+# If set to YES, the inheritance and collaboration graphs will show the
+# relations between templates and their instances.
+
+TEMPLATE_RELATIONS = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
+# tags are set to YES then doxygen will generate a graph for each documented
+# file showing the direct and indirect include dependencies of the file with
+# other documented files.
+
+INCLUDE_GRAPH = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
+# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
+# documented header file showing the documented files that directly or
+# indirectly include this file.
+
+INCLUDED_BY_GRAPH = YES
+
+# If the CALL_GRAPH and HAVE_DOT options are set to YES then
+# doxygen will generate a call dependency graph for every global function
+# or class method. Note that enabling this option will significantly increase
+# the time of a run. So in most cases it will be better to enable call graphs
+# for selected functions only using the \callgraph command.
+
+CALL_GRAPH = YES
+
+# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then
+# doxygen will generate a caller dependency graph for every global function
+# or class method. Note that enabling this option will significantly increase
+# the time of a run. So in most cases it will be better to enable caller
+# graphs for selected functions only using the \callergraph command.
+
+CALLER_GRAPH = YES
+
+# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
+# will graphical hierarchy of all classes instead of a textual one.
+
+GRAPHICAL_HIERARCHY = YES
+
+# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES
+# then doxygen will show the dependencies a directory has on other directories
+# in a graphical way. The dependency relations are determined by the #include
+# relations between the files in the directories.
+
+DIRECTORY_GRAPH = YES
+
+# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
+# generated by dot. Possible values are png, jpg, or gif
+# If left blank png will be used.
+
+DOT_IMAGE_FORMAT = png
+
+# The tag DOT_PATH can be used to specify the path where the dot tool can be
+# found. If left blank, it is assumed the dot tool can be found in the path.
+
+DOT_PATH =
+
+# The DOTFILE_DIRS tag can be used to specify one or more directories that
+# contain dot files that are included in the documentation (see the
+# \dotfile command).
+
+DOTFILE_DIRS =
+
+# The MAX_DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of
+# nodes that will be shown in the graph. If the number of nodes in a graph
+# becomes larger than this value, doxygen will truncate the graph, which is
+# visualized by representing a node as a red box. Note that doxygen if the
+# number of direct children of the root node in a graph is already larger than
+# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note
+# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH.
+
+DOT_GRAPH_MAX_NODES = 50
+
+# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the
+# graphs generated by dot. A depth value of 3 means that only nodes reachable
+# from the root by following a path via at most 3 edges will be shown. Nodes
+# that lay further from the root node will be omitted. Note that setting this
+# option to 1 or 2 may greatly reduce the computation time needed for large
+# code bases. Also note that the size of a graph can be further restricted by
+# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction.
+
+MAX_DOT_GRAPH_DEPTH = 1000
+
+# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
+# background. This is enabled by default, which results in a transparent
+# background. Warning: Depending on the platform used, enabling this option
+# may lead to badly anti-aliased labels on the edges of a graph (i.e. they
+# become hard to read).
+
+DOT_TRANSPARENT = NO
+
+# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
+# files in one run (i.e. multiple -o and -T options on the command line). This
+# makes dot run faster, but since only newer versions of dot (>1.8.10)
+# support this, this feature is disabled by default.
+
+DOT_MULTI_TARGETS = NO
+
+# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
+# generate a legend page explaining the meaning of the various boxes and
+# arrows in the dot generated graphs.
+
+GENERATE_LEGEND = YES
+
+# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
+# remove the intermediate dot files that are used to generate
+# the various graphs.
+
+DOT_CLEANUP = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine
+#---------------------------------------------------------------------------
+
+# The SEARCHENGINE tag specifies whether or not a search engine should be
+# used. If set to NO the values of all tags below this one will be ignored.
+
+SEARCHENGINE = NO
diff --git a/doc/INSTALL b/doc/INSTALL
new file mode 100644
index 00000000..5458714e
--- /dev/null
+++ b/doc/INSTALL
@@ -0,0 +1,234 @@
+Installation Instructions
+*************************
+
+Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005,
+2006 Free Software Foundation, Inc.
+
+This file is free documentation; the Free Software Foundation gives
+unlimited permission to copy, distribute and modify it.
+
+Basic Installation
+==================
+
+Briefly, the shell commands `./configure; make; make install' should
+configure, build, and install this package. The following
+more-detailed instructions are generic; see the `README' file for
+instructions specific to this package.
+
+ The `configure' shell script attempts to guess correct values for
+various system-dependent variables used during compilation. It uses
+those values to create a `Makefile' in each directory of the package.
+It may also create one or more `.h' files containing system-dependent
+definitions. Finally, it creates a shell script `config.status' that
+you can run in the future to recreate the current configuration, and a
+file `config.log' containing compiler output (useful mainly for
+debugging `configure').
+
+ It can also use an optional file (typically called `config.cache'
+and enabled with `--cache-file=config.cache' or simply `-C') that saves
+the results of its tests to speed up reconfiguring. Caching is
+disabled by default to prevent problems with accidental use of stale
+cache files.
+
+ If you need to do unusual things to compile the package, please try
+to figure out how `configure' could check whether to do them, and mail
+diffs or instructions to the address given in the `README' so they can
+be considered for the next release. If you are using the cache, and at
+some point `config.cache' contains results you don't want to keep, you
+may remove or edit it.
+
+ The file `configure.ac' (or `configure.in') is used to create
+`configure' by a program called `autoconf'. You need `configure.ac' if
+you want to change it or regenerate `configure' using a newer version
+of `autoconf'.
+
+The simplest way to compile this package is:
+
+ 1. `cd' to the directory containing the package's source code and type
+ `./configure' to configure the package for your system.
+
+ Running `configure' might take a while. While running, it prints
+ some messages telling which features it is checking for.
+
+ 2. Type `make' to compile the package.
+
+ 3. Optionally, type `make check' to run any self-tests that come with
+ the package.
+
+ 4. Type `make install' to install the programs and any data files and
+ documentation.
+
+ 5. You can remove the program binaries and object files from the
+ source code directory by typing `make clean'. To also remove the
+ files that `configure' created (so you can compile the package for
+ a different kind of computer), type `make distclean'. There is
+ also a `make maintainer-clean' target, but that is intended mainly
+ for the package's developers. If you use it, you may have to get
+ all sorts of other programs in order to regenerate files that came
+ with the distribution.
+
+Compilers and Options
+=====================
+
+Some systems require unusual options for compilation or linking that the
+`configure' script does not know about. Run `./configure --help' for
+details on some of the pertinent environment variables.
+
+ You can give `configure' initial values for configuration parameters
+by setting variables in the command line or in the environment. Here
+is an example:
+
+ ./configure CC=c99 CFLAGS=-g LIBS=-lposix
+
+ *Note Defining Variables::, for more details.
+
+Compiling For Multiple Architectures
+====================================
+
+You can compile the package for more than one kind of computer at the
+same time, by placing the object files for each architecture in their
+own directory. To do this, you can use GNU `make'. `cd' to the
+directory where you want the object files and executables to go and run
+the `configure' script. `configure' automatically checks for the
+source code in the directory that `configure' is in and in `..'.
+
+ With a non-GNU `make', it is safer to compile the package for one
+architecture at a time in the source code directory. After you have
+installed the package for one architecture, use `make distclean' before
+reconfiguring for another architecture.
+
+Installation Names
+==================
+
+By default, `make install' installs the package's commands under
+`/usr/local/bin', include files under `/usr/local/include', etc. You
+can specify an installation prefix other than `/usr/local' by giving
+`configure' the option `--prefix=PREFIX'.
+
+ You can specify separate installation prefixes for
+architecture-specific files and architecture-independent files. If you
+pass the option `--exec-prefix=PREFIX' to `configure', the package uses
+PREFIX as the prefix for installing programs and libraries.
+Documentation and other data files still use the regular prefix.
+
+ In addition, if you use an unusual directory layout you can give
+options like `--bindir=DIR' to specify different values for particular
+kinds of files. Run `configure --help' for a list of the directories
+you can set and what kinds of files go in them.
+
+ If the package supports it, you can cause programs to be installed
+with an extra prefix or suffix on their names by giving `configure' the
+option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
+
+Optional Features
+=================
+
+Some packages pay attention to `--enable-FEATURE' options to
+`configure', where FEATURE indicates an optional part of the package.
+They may also pay attention to `--with-PACKAGE' options, where PACKAGE
+is something like `gnu-as' or `x' (for the X Window System). The
+`README' should mention any `--enable-' and `--with-' options that the
+package recognizes.
+
+ For packages that use the X Window System, `configure' can usually
+find the X include and library files automatically, but if it doesn't,
+you can use the `configure' options `--x-includes=DIR' and
+`--x-libraries=DIR' to specify their locations.
+
+Specifying the System Type
+==========================
+
+There may be some features `configure' cannot figure out automatically,
+but needs to determine by the type of machine the package will run on.
+Usually, assuming the package is built to be run on the _same_
+architectures, `configure' can figure that out, but if it prints a
+message saying it cannot guess the machine type, give it the
+`--build=TYPE' option. TYPE can either be a short name for the system
+type, such as `sun4', or a canonical name which has the form:
+
+ CPU-COMPANY-SYSTEM
+
+where SYSTEM can have one of these forms:
+
+ OS KERNEL-OS
+
+ See the file `config.sub' for the possible values of each field. If
+`config.sub' isn't included in this package, then this package doesn't
+need to know the machine type.
+
+ If you are _building_ compiler tools for cross-compiling, you should
+use the option `--target=TYPE' to select the type of system they will
+produce code for.
+
+ If you want to _use_ a cross compiler, that generates code for a
+platform different from the build platform, you should specify the
+"host" platform (i.e., that on which the generated programs will
+eventually be run) with `--host=TYPE'.
+
+Sharing Defaults
+================
+
+If you want to set default values for `configure' scripts to share, you
+can create a site shell script called `config.site' that gives default
+values for variables like `CC', `cache_file', and `prefix'.
+`configure' looks for `PREFIX/share/config.site' if it exists, then
+`PREFIX/etc/config.site' if it exists. Or, you can set the
+`CONFIG_SITE' environment variable to the location of the site script.
+A warning: not all `configure' scripts look for a site script.
+
+Defining Variables
+==================
+
+Variables not defined in a site shell script can be set in the
+environment passed to `configure'. However, some packages may run
+configure again during the build, and the customized values of these
+variables may be lost. In order to avoid this problem, you should set
+them in the `configure' command line, using `VAR=value'. For example:
+
+ ./configure CC=/usr/local2/bin/gcc
+
+causes the specified `gcc' to be used as the C compiler (unless it is
+overridden in the site shell script).
+
+Unfortunately, this technique does not work for `CONFIG_SHELL' due to
+an Autoconf bug. Until the bug is fixed you can use this workaround:
+
+ CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash
+
+`configure' Invocation
+======================
+
+`configure' recognizes the following options to control how it operates.
+
+`--help'
+`-h'
+ Print a summary of the options to `configure', and exit.
+
+`--version'
+`-V'
+ Print the version of Autoconf used to generate the `configure'
+ script, and exit.
+
+`--cache-file=FILE'
+ Enable the cache: use and save the results of the tests in FILE,
+ traditionally `config.cache'. FILE defaults to `/dev/null' to
+ disable caching.
+
+`--config-cache'
+`-C'
+ Alias for `--cache-file=config.cache'.
+
+`--quiet'
+`--silent'
+`-q'
+ Do not print messages saying which checks are being made. To
+ suppress all normal output, redirect it to `/dev/null' (any error
+ messages will still be shown).
+
+`--srcdir=DIR'
+ Look for the package's source code in directory DIR. Usually
+ `configure' can determine that directory automatically.
+
+`configure' also accepts some other, not widely useful, options. Run
+`configure --help' for more details.
+
diff --git a/doc/LICENSE b/doc/LICENSE
new file mode 100644
index 00000000..f4b7f221
--- /dev/null
+++ b/doc/LICENSE
@@ -0,0 +1,28 @@
+Copyright (c) 2003-2008, John Wiegley. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+- Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+- Neither the name of New Artisans LLC nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/doc/NEWS b/doc/NEWS
new file mode 100644
index 00000000..cd95ed87
--- /dev/null
+++ b/doc/NEWS
@@ -0,0 +1,842 @@
+ Ledger NEWS
+
+* 2.6.1
+
+- Added the concept of "balance setting transactions":
+
+ # Setting an account's balance
+
+ You can now manually set an account's balance to whatever you want, at
+ any time. Here's how it might look at the beginning of your Ledger
+ file:
+
+ 2008/07/27 Starting fresh
+ Assets:Checking = $1,000.00
+ Equity:Opening Balances
+
+ If Assets:Checking is empty, this is no different from omitting the
+ "=". However, if Assets:Checking did have a prior balance, the amount
+ of the transaction will be auto-calculated so that the final balance
+ of Assets:Checking is now $1,000.00.
+
+ Let me give an example of this. Say you have this:
+
+ 2008/07/27 Starting fresh
+ Assets:Checking $750.00
+ Equity:Opening Balances
+
+ 2008/07/27 Starting fresh
+ Assets:Checking = $1,000.00
+ Equity:Adjustments
+
+ These two entries are exactly equivalent to these two:
+
+ 2008/07/27 Starting fresh
+ Assets:Checking $750.00
+ Equity:Opening Balances
+
+ 2008/07/27 Starting fresh
+ Assets:Checking $250.00
+ Equity:Adjustments
+
+ The use of the "=" sign here is that it sets the transaction's amount
+ to whatever is required to satisfy the assignment. This is the
+ behavior if the transaction's amount is left empty.
+
+ # Multiple commodities
+
+ As far as commodities go, the = sign only works if the account
+ balance's commodity matches the commodity of the amount after the
+ equals sign. However, if the account has multiple commodities, only
+ the matching commodity is affected. Here's what I mean:
+
+ 2008/07/24 Opening Balance
+ Assets:Checking = $250.00 ; we force set it
+ Equity:Opening Balances
+
+ 2008/07/24 Opening Balance
+ Assets:Checking = EC 250.00 ; we force set it again
+ Equity:Opening Balances
+
+ This is an error, because $250.00 cannot be auto-balanced to match EC
+ 250.00. However:
+
+ 2008/07/24 Opening Balance
+ Assets:Checking = $250.00 ; we force set it again
+ Assets:Checking EC 100.00 ; and add some EC's
+ Equity:Opening Balances
+
+ 2008/07/24 Opening Balance
+ Assets:Checking = EC 250.00 ; we force set the EC's
+ Equity:Opening Balances
+
+ This is *not* an error, because the latter auto-balancing transaction
+ only affects the EC 100.00 part of the account's balance; the $250.00
+ part is left alone.
+
+ # Checking statement balances
+
+ When you reconcile a statement, there are typically one or more
+ transactions which result in a known balance. Here's how you specify
+ that in your Ledger data:
+
+ 2008/07/24 Opening Balance
+ Assets:Checking = $100.00
+ Equity:Opening Balances
+
+ 2008/07/30 We spend money, with a known balance afterward
+ Expenses:Food $20.00
+ Assets:Checking = $80.00
+
+ 2008/07/30 Again we spend money, but this time with all the info
+ Expenses:Food $20.00
+ Assets:Checking $-20.00 = $60.00
+
+ 2008/07/30 This entry yield an 'unbalanced' error
+ Expenses:Food $20.00
+ Assets:Checking $-20.00 = $30.00
+
+ The last entry in this set fails to balance with an unbalanced
+ remainder of $-10.00. Either the entry must be corrected, or you can
+ have Ledger deal with the remainder automatically:
+
+ 2008/07/30 The fixed entry
+ Expenses:Food $20.00
+ Assets:Checking $-20.00 = $30.00
+ Equity:Adjustments
+
+ # Conclusion
+
+ This simple feature has all the utility of @check, plus auto-balancing
+ to match known target balances, plus the ability to guarantee that an
+ account which uses only one commodity does contain only that
+ commodity.
+
+ This feature slows down textual parsing slightly, does not affect
+ speed when loading from the binary cache.
+
+- The rest of the changes in the version is all bug fixes (around 45 of
+ them).
+
+* 2.6.0.90
+
+- Gnucash parser is fixed.
+
+- Fix a memory leak bug in the amount parser.
+
+- (This feature is from 2.6, but was not documented anywhere):
+
+ Commodities may now specify lot details, to assign in managing set
+ groups of items, like buying and selling shares of stock.
+
+ For example, let's say you buy 50 shares of AAPL at $10 a share:
+
+ 2007/01/14 Stock purchase
+ Assets:Brokerage 50 AAPL @ $10
+ Assets:Brokerage
+
+ Three months later, you sell this "lot". Based on the original
+ purchase information, Ledger remembers how much each share was
+ purchased for, and the date on which it was purchased. This means
+ you can sell this specific lot by price, by date, or by both. Let's
+ sell it by price, this time for $20 a share.
+
+ 2007/04/14 Stock purchase
+ Assets:Brokerage $1000.00
+ Assets:Brokerage -50 AAPL {$10} @ $20
+ Income:Capital Gains $-500.00
+
+ Note that the Income:Capital Gains line is now required to balance
+ the transaction. Because you sold 50 AAPL at $20/share, and because
+ you are selling shares that were originally valued at $10/share,
+ Ledger needs to know how you will "balance" this difference. An
+ equivalent Expenses:Capital Loss would be needed if the selling
+ price were less than the buying price.
+
+ Here's the same example, this time selling by date and price:
+
+ 2007/04/14 Stock purchase
+ Assets:Brokerage $1000.00
+ Assets:Brokerage -50 AAPL {$10} [2007/01/14] @ $20
+ Income:Capital Gains $-500.00
+
+ If you attempt to sell shares for a date you did not buy them, note
+ that Ledger will not complain (as it never complains about the
+ movement of commodities between accounts). In this case, it will
+ simply create a negative balance for such shares within your
+ Brokerage account; it's up to you to determine whether you have them
+ or not.
+
+- To facilitate lot pricing reports, there are some new reporting
+ options:
+
+ --lot-prices Report commodities with different lot prices as if
+ they were different commodities. Otherwise, Ledger
+ just gloms all the AAPL shares together.
+
+ --lot-dates Separate commodities by lot date. Every
+ transaction that uses the '@' cost specifier will
+ have an implicit lot date and lot price.
+
+ --lot-tags Separate commodities by their arbitrary note tag.
+ Note tags may be specified using (note) after the
+ commodity.
+
+ --lots Separate commodities using all lot information.
+
+* 2.6
+
+- The style for eliding long account names (for example, in the
+ register report) has been changed. Previously Ledger would elide
+ the end of long names, replacing the excess length with "..".
+ However, in some cases this caused the base account name to be
+ missing from the report!
+
+ What Ledger now does is that if an account name is too long, it will
+ start abbreviating the first parts of the account name down to two
+ letters in length. If this results in a string that is still too
+ long, the front will be elided -- not the end. For example:
+
+ Expenses:Cash ; OK, not too long
+ Ex:Wednesday:Cash ; "Expenses" was abbreviated to fit
+ Ex:We:Afternoon:Cash ; "Expenses" and "Wednesday" abbreviated
+ ; Expenses:Wednesday:Afternoon:Lunch:Snack:Candy:Chocolate:Cash
+ ..:Af:Lu:Sn:Ca:Ch:Cash ; Abbreviated and elided!
+
+ As you can see, it now takes a very deep account name before any
+ elision will occur, whereas in 2.x elisions were fairly common.
+
+- In addition to the new elision change mentioned above, the style is
+ also configurable:
+
+ --truncate leading ; elide at the beginning
+ --truncate middle ; elide in the middle
+ --truncate trailing ; elide at end (Ledger 2.x's behavior)
+ --truncate abbrev ; the new behavior
+
+ --abbrev-len 2 ; set length of abbreviations
+
+ These elision styles affect all format strings which have a maximum
+ width, so they will also affect the payee in a register report, for
+ example. In the case of non-account names, "abbrev" is equivalent
+ to "trailing", even though it elides at the beginning for long
+ account names.
+
+- Error reporting has been greatly improving, now showing full
+ contextual information for most error messages.
+
+- Added --base reporting option, for reporting convertible commodities
+ in their most basic form. For example, if you read a timeclock file
+ with Ledger, the time values are reported as hour and minutes --
+ whichever is the most compact form. But with --base, Ledger reports
+ only in seconds.
+
+ NOTE: Setting up convertible commodities is easy; here's how to use
+ Ledger for tracking quantities of data, where the most compact form
+ is reported (unless --base is specified):
+
+ C 1.00 Kb = 1024 b
+ C 1.00 Mb = 1024 Kb
+ C 1.00 Gb = 1024 Mb
+ C 1.00 Tb = 1024 Gb
+
+- Added --ansi reporting option, which shows negative values in the
+ running total column of the register report as red, using ANSI
+ terminal codes; --ansi-invert makes non-negative values red (which
+ makes more sense for the income and budget reports).
+
+ The --ansi functionality is triggered by the format modifier "!",
+ for example the register reports uses the following for the total
+ (last) column:
+
+ %!12.80T
+
+ At the moment neither the balance report nor any of the other
+ reports make use of the ! modifier, and so will not change color
+ even if --ansi is used. However, you can modify these report format
+ strings yourself in ~/.ledgerrc if you wish to see red coloring of
+ negative sums in other places.
+
+- Added --only predicate, which occurs during transaction processing
+ between --limit and --display. Here is a summary of how the three
+ supported predicates are used:
+
+ --limit "a>100"
+
+ This flag limits computation to *only transactions whose amount
+ is greater than 100 of a given commodity*. It means that if you
+ scan your dining expenses, for example, only individual bills
+ greater than $100 would be caculated by the report.
+
+ --only "a>100"
+
+ This flag happens much later than --limit, and corresponding
+ more directly to what one normally expects. If --limit isn't
+ used, then ALL your dining expenses contribute to the report,
+ *but only those calculated transactions whose value is greater
+ than $100 are used*. This becomes important when doing a
+ monthly costs report, for example, because it makes the
+ following command possible:
+
+ ledger -M --only "a>100" reg ^Expenses:Food
+
+ This shows only *months* whose amount is greater than 100. If
+ --limit had been used, it would have been a monthly summary of
+ all individual dinner bills greater than 100 -- which is a very
+ different thing.
+
+ --display "a>100"
+
+ This predicate does not constrain calculation, but only display.
+ Consider the same command as above:
+
+ ledger -M --display "a>100" reg ^Expenses:Food
+
+ This displays only lines whose amount is greater than 100, *yet
+ the running total still includes amounts from all transactions*.
+ This command has more particular application, such as showing
+ the current month's checking register while still giving a
+ correct ending balance:
+
+ ledger --display "d>[this month]" reg Checking
+
+ Note that these predicates can be combined. Here is a report that
+ considers only food bills whose individual cost is greater than
+ $20, but shows the monthly total only if it is greater than $500.
+ Finally, we only display the months of the last year, but we
+ retain an accurate running total with respect to the entire ledger
+ file:
+
+ ledger -M --limit "a>20" --only "a>200" \
+ --display "year == yearof([last year])" reg ^Expenses:Food
+
+- Added new "--descend AMOUNT" and "--descend-if VALEXPR" reporting
+ options. For any reports that display valued transactions (i.e.,
+ register, print, etc), you can now descend into the component
+ transactions that made up any of the values you see.
+
+ For example, say you request a --monthly expenses report:
+
+ $ ledger --monthly register ^Expenses
+
+ Now, in one of the reported months you see $500.00 spent on
+ Expenses:Food. You can ask Ledger to "descend" into, and show the
+ component transactions of, that $500.00 by respecifying the query
+ with the --descend option:
+
+ $ ledger --monthly --descend "\$500.00" register ^Expenses
+
+ The --descend-if option has the same effect, but takes a value
+ expression which is evaluated as a boolean to locate the desired
+ reported transaction.
+
+- Added a "dump" command for creating binary files, which load much
+ faster than their textual originals. For example:
+
+ ledger -f huge.dat -o huge.cache dump
+ ledger -f huge.cache bal
+
+ The second command will load significantly faster (usually about six
+ times on my machine).
+
+- There have a few changes to value expression syntax. The most
+ significant incompatibilities being:
+
+ * Equality is now ==, not =
+ * The U, A, and S functions now requires parens around the argument.
+ Whereas before At was acceptable, now it must be specified as
+ A(t).
+ * The P function now always requires two arguments. The old
+ one-argument version P(x) is now the same as P(x,m).
+
+ The following value expression features are new:
+
+ * A C-like comma operator is supported, where all but the last term
+ are ignored. The is significant for the next feature:
+ * Function definitions are now supported. Scoping is governed
+ by parentheses. For example:
+ (x=100, x+10) ; yields 110 as the result
+ (f(x)=x*2,f(100)) ; yields 200 as the result
+ * Identifier names may be any length. Along with this support comes
+ alternate, longer names for all of the current one-letter value
+ expression variables:
+
+ Old New
+ --- ---
+ m now
+ a amount
+ a amount
+ b cost
+ i price
+ d date
+ X cleared
+ Y pending
+ R real
+ L actual
+ n index
+ N count
+ l depth
+ O total
+ B cost_total
+ I price_total
+ v market
+ V market_total
+ g gain
+ G gain_total
+ U(x) abs(x)
+ S(x) quant(x), quantity(x)
+ comm(x), commodity(x)
+ setcomm(x,y), set_commodity(x,y)
+ A(x) mean(x), avg(x), average(x)
+ P(x,y) val(x,y), value(x,y)
+ min(x,y)
+ max(x,y)
+
+- There are new "parse" and "expr" commands, whose argument is a
+ single value expression. Ledger will simply print out the result of
+ evaluating it. "parse" happens before parsing your ledger file,
+ while "expr" happens afterward. Although "expr" is slower as a
+ result, any commodities you use will be formatted based on patterns
+ of usage seen in your ledger file.
+
+ These commands can be used to test value expressions, or for doing
+ calculation of commoditized amounts from a script.
+
+ A new "--debug" will also dump the resulting parse tree, useful for
+ submitting bug reports.
+
+- Added new min(x,y) and max(x,y) value expression functions.
+
+- Value expression function may now be defined within your ledger file
+ (or initialization file) using the following syntax:
+
+ @def foo(x)=x*1000
+
+ This line makes the function "foo" available to all subsequent value
+ expressions, to all command-line options taking a value expression,
+ and to the new "expr" command (see above).
+
+* 2.5
+
+- Added a new value expression regexp command:
+ C// compare against a transaction amount's commodity symbol
+
+- Added a new "csv" command, for outputting results in CSV format.
+
+- Ledger now expands ~ in file pathnames specified in environment
+ variables, initialization files and journal files.
+
+- Effective dates may now be specified for entries:
+
+ 2004/10/03=2004/09/30 Credit card company
+ Liabilities:MasterCard $100.00
+ Assets:Checking
+
+ This entry says that although the actual transactions occurred on
+ October 3rd, their effective date was September 30th. This is
+ especially useful for budgeting, in case you want the transactions
+ to show up in September instead of October.
+
+ To report using effective dates, use the --effective option.
+
+- Actual and effective dates may now be specified for individual
+ transactions:
+
+ 2004/10/03=2004/09/30 Credit card company
+ Liabilities:MasterCard $100.00
+ Assets:Checking ; [2004/10/10=2004/09/15]
+
+ This states that although the actual date of the entry is
+ 2004/10/03, and the effective date of the entry is 2004/09/30, the
+ actual date of the Checking transaction itself is 2004/10/10, and
+ its effective date is 2004/09/15. The effective date is optional
+ (just specifying the actual date would have read "[2004/10/10]").
+
+ If no effective date is given for a transaction, the effective date
+ of the entry is assumed. If no actual date is given, the actual
+ date of the entry is assumed. The syntax of the latter is simply
+ [=2004/09/15].
+
+- To support the above, there is a new formatting option: "%d". This
+ outputs only the date (like "%D") if there is no effective date, but
+ outputs "ADATE=EDATE" if there is one. The "print" report now uses
+ this.
+
+- To support the above, the register report may now split up entries
+ whose component transactions have different dates. For example,
+ given the following entry:
+
+ 2005/10/15=2005/09/01 iTunes
+ Expenses:Music $1.08 ; [2005/10/20=2005/08/01]
+ Liabilities:MasterCard
+
+ The command "ledger register" on this data file reports:
+
+ 2005/10/20 iTunes Expenses:Music $1.08 $1.08
+ 2005/10/15 iTunes Liabilities:MasterCard $-1.08 0
+
+ While the command "ledger --effective register" reports:
+
+ 2005/08/01 iTunes Expenses:Music $1.08 $1.08
+ 2005/09/01 iTunes Liabilities:MasterCard $-1.08 0
+
+ Although it appears as though two entries are being reported, both
+ transactions belong to the same entry.
+
+- Individual transactions may now be cleared separately. The old
+ syntax, which is still supported, clears all transactions in an
+ entry:
+
+ 2004/05/27 * Book Store
+ Expenses:Dining $20.00
+ Liabilities:MasterCard
+
+ The new syntax allows clearing of just the MasterCard transaction:
+
+ 2004/05/27 Book Store
+ Expenses:Dining $20.00
+ * Liabilities:MasterCard
+
+ NOTE: This changes the output format of both the "emacs" and "xml"
+ reports. ledger.el uses the new syntax unless the Lisp variable
+ `ledger-clear-whole-entries' is set to t.
+
+- Removed Python integration support.
+
+- Did much internal restructuring to allow the use of libledger.so in
+ non-command-line environments (such as GUI tools).
+
+* 2.4.1
+
+- Corrected an issue that had inadvertantly disabled Gnucash support.
+
+* 2.4
+
+- Both "-$100.00" and "$-100.00" are now equivalent amounts.
+
+- Simple, inline math (using the operators +-/*, and/or parentheses)
+ is supported in transactions. For example:
+
+ 2004/05/27 Book Store
+ Expenses:Dining $20.00 + $2.50
+ Liabilities:MasterCard
+
+ This won't register the tax/tip in its own account, but might make
+ later reading of the ledger file easier.
+
+- Use of a "catch all" account is now possible, which auto-balances
+ entries that contain _only one transaction_. For sanity's sake this
+ is not used to balance all entries, as that would make locating
+ unbalanced entries a nightmare. Example:
+
+ A Liabilities:MasterCard
+
+ 2004/05/27 Book Store
+ Expenses:Dining $20.00 + $2.50
+
+ This is equivalent to the entry in the previous bullet.
+
+- Entries that contain a single transaction with no amount now always
+ balance, even if multiple commodities are involved. This means that
+ the following is now supported, which wasn't previously:
+
+ 2004/06/21 Adjustment
+ Retirement 100 FUNDA
+ Retirement 200 FUNDB
+ Retirement 300 FUNDC
+ Equity:Adjustments
+
+- Fixed several bugs relating to QIF parsing, budgeting and
+ forecasting.
+
+- The configure process now looks for libexpat in addition to
+ searching for libxmlparse+libxmltok (how expat used to be packaged).
+
+* 2.3
+
+- The directive "!alias ALIAS = ACCOUNT" makes it possible to use
+ "ALIAS" as an alternative name for ACCOUNT in a textual ledger file.
+ You might use this to associate the single word "Bank" with the
+ checking account you use most, for example.
+
+- The --version page shows the optional modules ledger was built with.
+
+- Fixed several minor problems, plus a few major ones dealing with
+ imprecise date parsing.
+
+* 2.2
+
+- Ledger now compiles under gcc 2.95.
+
+- Fixed several core engine bugs, and problems with Ledger's XML data
+ format.
+
+- Erros in XML or Gnucash data now report the correct line number for
+ the error, instead of always showing line 1.
+
+- 'configure' has been changed to always use a combination of both
+ compile and link tests for every feature, in order to identify
+ environment problems right away.
+
+- The "D <COMM>" command, released in 2.1, now requires a commoditized
+ amount, such as "D $1,000.00". This sets not only the default
+ commodity, but several flags to be used with all such commodities
+ (such as whether numbering should be American or European by
+ default). This entry may be used be many times; the most recent
+ seen specifies the default for entries that follow.
+
+- The binary cache now remembers the price history database that was
+ used, so that if LEDGER_PRICE_DB is silently changed, the cache will
+ be thrown away and rebuilt.
+
+- OFX data importing is now supported, using libofx
+ (http://libofx.sourceforge.net). configure will check if the
+ library is available. You may need to add CPPFLAGS or LDFLAGS to
+ the command-line for the appropriate headers and library to be
+ found. This support is preliminary, and as such is not documented
+ yet.
+
+- All journal entries now remember where they were read from. New
+ format codes to access this information are: %S for source path, %B
+ for beginning character position, and %E for ending character
+ position.
+
+- Added "pricesdb" command, which is identical to "prices" except that
+ it uses the same format as Ledger's usual price history database.
+
+- Added "output FILE" command, which attempts to reproduce the input
+ journal FILE exactly. Meant for future GUI usage. This command
+ relies on --write-hdr-format and --write-xact-format, instead of
+ --print-format.
+
+- Added "--reconcile BALANCE" option, which attempts to reconcile all
+ matching transactions to the given BALANCE, outputting those that
+ would need to be "cleared" to match it. Using by the
+ auto-reconciling feature of ledger.el (see below).
+
+ "--reconcile-date DATE" ignores any uncleared transactions after
+ DATE in the reconciling algorithm. Since the algorithm is O(n^2)
+ (where 'n' is the number of uncleared transactions to consider),
+ this could have a substantial impact.
+
+- In ledger.el's *Reconcile* mode ('C-c C-r' from a ledger-mode file):
+ . 'a' adds a missing transaction
+ . 'd' deletes the current transaction
+ . 'r' attempts to auto-reconcile (same as 'C-u C-c C-r')
+ . 's' or 'C-x C-s' will save the ledger data file and show the
+ currently cleared balance
+ . 'C-c C-c' commits the pending transactions, marking them cleared.
+ This feature now works with Emacs 21.3.
+ Also, the reconciler no longer needs to ask "how far back" to go.
+
+- To support the reconciler, textual entries may now have a "!" flag
+ (pending) after the date, instead of a "*" flag (cleared).
+
+- There are a new set of value expression regexp commands:
+ c// entry code
+ p// payee
+ w// short account name
+ W// full account name
+ e// transaction note
+
+ This makes it possible to display transactions whose comment field
+ matches a particular text string. For example:
+
+ ledger -l e/{tax}/ reg
+
+ prints out all the transactions with the comment "{tax}", which
+ might be used to identify items related to a tax report.
+
+* 2.1
+
+- Improved the autoconf system to be smarter about finding XML libs
+
+- Added --no-cache option, to always ignore any binary cache file
+
+- `ledger-reconcile' (in ledger.el) no longer asks for a number of days
+
+- Fixed %.XY format, where X is shorter than the string generated by Y
+
+- New directive for text files: "D <COMM>" specifies the default commodity
+ used by the entry command
+
+* 2.0
+
+This version represents a full rewrite, while preserving much of the
+original data format and command-line syntax. There are too many new
+features to describe in full, but a quick list: value expressions,
+complex date masks, binary caching of ledger data, several new
+reporting options, a simple way to specify payee regexps, calculation
+and display predicates, and two-way Python integration. Ledger also
+uses autoconf now, and builds as a library in addition to a
+command-line driver.
+
+** Differences from 1.7
+
+- changes in option syntax:
+
+ -d now specifies the display predicate. To give a date mask similar
+ to 1.7, use the -p (period) option.
+
+ -P now generates the "by payee" report. To specify a price database
+ to use, use --price-db.
+
+ -G now generates a net gain report. To print totals in a format
+ consumable by gnuplot, use -J.
+
+ -l now specifies the calculation predicate. To emulate the old
+ usage of "-l \$100", use: -d "AT>100".
+
+ -N is gone. Instead of "-N REGEX", use: -d "/REGEX/?T>0:T".
+
+ -F now specifies the report format string. The old meaning of -F
+ now has little use.
+
+ -S now takes a value expression as the sorting criterion. To get
+ the old meaning of "-S", use "-S d".
+
+ -n now means "collapse entries in the register report". The get the
+ old meaning of -n in the balance report, use "-T a".
+
+ -p now specifies the reporting period. You can convert commodities
+ in a report using value expressions. For example, to display hours
+ at $10 per hour:
+ -T "O>={0.01h}?{\$10.00}*O:O"
+ Or, to reduce totals, so that every $417 becomes 1.0 AU:
+ -T "O>={\$0.01}?{1.0 AU}*(O/{\$417}):O"
+
+- The use of "+" and "-" in ledger files to specify permanent regexps
+ has been removed.
+
+- The "-from" argument is no longer used by the "entry" command.
+ Simply remove it.
+
+** Features new to 2.0
+
+- The most significant feature to be added is "value expressions".
+ They are used in many places to indicate what to display, sorting
+ order, how to calculate totals, etc. Logic and math operators are
+ supported, as well as simple functions. See the manual.
+
+- If the environment variable LEDGER_FILE (or LEDGER) is used, a
+ binary cache of that ledger is kept in ~/.ledger-cache (or the file
+ given by LEDGER_CACHE). This greatly speeds up subsequent queries.
+ Happens only if "-f" or "--file" is not used.
+
+- New 'xml' report outputs an XML version of what "register" would
+ have displayed. This can be used to manipulate reported data in a
+ more scriptable way.
+
+ Ledger can also read as input the output from the "xml" report. If
+ the "xml" report did not contain balanced entries, they will be
+ balanced by the "<Unknown>" account. For example:
+ ledger reg rent
+ displays the same results as:
+ ledger xml rent | ledger -f - reg rent
+
+- Regexps given directly after the command name now apply only to
+ account names. To match on a payee, use "--" to separate the two
+ kinds of regexps. For example, to find a payee named "John" within
+ all Expenses accounts, use:
+ ledger register expenses -- john
+
+ Note: This command is identical (and internally converted) to:
+ ledger -l "/expenses/|//john/" register
+
+- To include entries from another file into a specific account, use:
+ !account ACCOUNT
+ !include FILE
+ !end
+
+- Register reports now show only matching account transactions. Use
+ "-r" to see "related accounts" -- the account the transfer came from
+ or went to (This was the old behavior in 1.x, but led to confusion).
+ "-r" also works with balance reports, where it will total all the
+ transactions related to your query.
+
+- Automated transactions now use value expressions for the predicate.
+ The new syntax is:
+ = VALUE-EXPR
+ TRANSACTIONS...
+
+ Only one VALUE-EXPR is supported (compared to multiple account
+ regexps before). However, since value expression allow for logic
+ chaining, there is no loss of functionality. Matching can also be
+ much more comprehensive.
+
+- If Boost.Python is installed (libboost_python.a), ledger can support
+ two-way Python integration. This feature is enabled by passing
+ --enable-python to the "configure" script before building. Ledger
+ can then be used as a module (ledger.so), as well as supporting
+ Python function calls directly from value expressions. See main.py
+ for an example of driving Ledger from Python. It implements nearly
+ all the functionality of the C++ driver, main.cc.
+
+ (This feature has yet to mature, and so is being offered as a beta
+ feature in this release. It is mostly functional, and those curious
+ are welcome to play with it.)
+
+- New reporting options:
+
+ "-o FILE" outputs data to FILE. If "-", output goes to stdout (the
+ default).
+
+ -O shows base commodity values (this is the old behavior)
+ -B shows basis cost of commodities
+ -V shows market value of commodities
+ -g reports gain/loss performance of each register item
+ -G reports net gain/loss over time
+ -A reports average transaction value (arithmetic mean)
+ -D reports each transaction's deviation from the average
+
+ -w uses 132 columns for the register report, rather than 80. Set
+ the environment variable LEDGER_WIDE for this to be the default.
+
+ "-p INTERVAL" allows for more flexible period reporting, such as:
+
+ monthly
+ every week
+ every 3 quarters
+ weekly from 12/20
+ monthly in 2003
+ weekly from last month until dec
+
+ "-y DATEFMT" changes the date format used in all reports. The
+ default is "%Y/%m/%d".
+
+ -Y and -W print yearly and weekly subtotals, just as -M prints
+ monthly subtotals.
+
+ --dow shows cumulative totals for each day of the week.
+
+ -P reports transactions grouped by payee
+
+ -x reports the payee as the commodity; useful in some cases
+
+ -j and -J replace the previous -G (gnuplot) option. -j reports the
+ amounts column in a way gnuplot can consume, and -J the totals
+ column. An example is in "scripts/report".
+
+ "--period-sort EXPR" sorts transactions within a reporting period.
+ The regular -S option sorts all reported transactions.
+
+* 1.7
+
+- Pricing histories are now supported, so that ledger remembers the
+ historical prices of all commodities, and can present register
+ reports based on past and present market values as well as original
+ cost basis. See the manual for more details on the new option
+ switches.
+
+* 1.6
+
+- Ledger can now parse timeclock files. These are simple timelogs
+ that track in/out events, which can be maintained using my timeclock
+ tool. By allowing ledger to parse these, it means that reporting
+ can be done on them in the same way as ledger files (the commodity
+ used is "h", for hours); it means that doing things like tracking
+ billable hours for clients, and invoicing those clients to transfer
+ hours into dollar values via a receivable account, is now trivial.
+ See the docs for more on how to do this.
+
+- Began keeping a NEWS file. :)
diff --git a/doc/README b/doc/README
new file mode 100644
index 00000000..8a2406d9
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,73 @@
+
+ Welcome to Ledger
+
+ the command-line accounting program
+
+Introduction
+============
+
+Ledger is an accounting program which is invoked from the command-line
+using a textual ledger file. To start using Ledger, you will need to
+create such a file containing your financial transactions. A sample
+has been provided in the file "sample.dat". See the documentation
+(ledger.pdf, or ledger.info) for full documentation on creating a
+ledger file and using Ledger to generate reports.
+
+Once you have such a file -- you might call it "ledger.dat" -- you can
+start looking at balances and account registers using commands like
+the following:
+
+ ledger -f ledger.dat balance assets:checking
+ ledger -f ledger.dat register expenses:food
+
+This assumes, of course, that like the sample file you use account
+names such as "Assets:Checking" and "Expenses:Food". If you use other
+account names, you will need to vary the reporting commands you use
+accordingly.
+
+
+Building
+========
+
+To build Ledger, you will need a fairly modern C++ compiler (gcc 2.95
+will not work), and at least these two libraries installed:
+
+ gmp GNU multi-precision library
+ pcre Perl regular expression library
+
+(On some GNU/Linux systems, the packages you need to install are
+called "gmp-dev" and "pcre-dev").
+
+If you wish to read Gnucash data files, you will also need two XML
+libraries, which may or may not be available in a single package (it
+depends on your distribution):
+
+ libexpat, or libxmlparse and libxmltok
+
+Once you have determined where the headers and libraries for the above
+packages are installed, run the script "configure", passing those
+paths. If you installed everything under /usr/local, you can probably
+just type "./configure". Otherwise, do this:
+
+ ./configure CPPFLAGS=-I<INCLUDE-PATH> LDFLAGS=-L<LIBRARY-PATH>
+
+If you need to specify multiple include or library paths, then do
+this:
+
+ ./configure CPPFLAGS="-I<PATH1> -I<PATH2>" LDFLAGS="-L<PATH1> -L<PATH2>"
+
+Once configure is done running, just type:
+
+ make install
+
+
+Mailing List and IRC
+====================
+
+If you need help on how to use Ledger, or run into problems, you can
+join the Ledger mailing list at the following Web address:
+
+ https://lists.sourceforge.net/lists/listinfo/ledger-discuss
+
+You can also find help at the #ledger channel on the IRC server
+irc.freenode.net.
diff --git a/doc/ledger.texi b/doc/ledger.texi
new file mode 100644
index 00000000..4b995e78
--- /dev/null
+++ b/doc/ledger.texi
@@ -0,0 +1,3961 @@
+\input texinfo @c -*-texinfo-*-
+
+@setfilename ledger.info
+@settitle Ledger: Command-Line Accounting
+
+@dircategory User Applications
+@copying
+Copyright (c) 2003-2008, John Wiegley. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+- Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+- Neither the name of New Artisans LLC nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+@end copying
+
+@documentencoding iso-8859-1
+
+@iftex
+@finalout
+@end iftex
+
+@titlepage
+@title Ledger: Command-Line Accounting
+@author John Wiegley
+@end titlepage
+
+@direntry
+* Ledger: (ledger). Command Line Accounting
+@end direntry
+
+@contents
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Overview
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction::
+* Running Ledger::
+* Keeping a ledger::
+* Using XML::
+@end menu
+
+@node Introduction, Running Ledger, Top, Top
+@chapter Introduction
+
+Ledger is an accounting tool with the moxie to exist. It provides no
+bells or whistles, and returns the user to the days before user
+interfaces were even a twinkling in their father's CRT.
+
+What it does offer is a double-entry accounting ledger with all the
+flexibility and muscle of its modern day cousins, without any of the
+fat. Think of it as the Bran Muffin of accounting tools.
+
+To use it, you need to start keeping a ledger. This is the basis of
+all accounting, and if you haven't started yet, now is the time to
+learn. The little booklet that comes with your checkbook is a ledger,
+so we'll describe double-entry accounting in terms of that.
+
+A checkbook ledger records debits (subtractions, or withdrawals) and
+credits (additions, or deposits) with reference to a single account:
+the checking account. Where the money comes from, and where it goes
+to, are described in the payee field, where you write the person or
+company's name. The ultimate aim of keeping a checkbook ledger is to
+know how much money is available to spend. That's really the aim of
+all ledgers.
+
+What computers add is the ability to walk through these transactions,
+and tell you things about your spending habits; to let you devise
+budgets and get control over your spending; to squirrel away money
+into virtual savings account without having to physically move money
+around; etc. As you keep your ledger, you are recording information
+about your life and habits, and sometimes that information can start
+telling you things you aren't aware of. Such is the aim of all good
+accounting tools.
+
+The next step up from a checkbook ledger, is a ledger that keeps track
+of all your accounts, not just checking. In such a ledger, you record
+not only who gets paid---in the case of a debit---but where the money
+came from. In a checkbook ledger, its assumed that all the money
+comes from your checking account. But in a general ledger, you write
+transaction two-lines: the source account and target account.
+@emph{There must always be a debit from at least one account for every
+credit made to another account}. This is what is meant by
+``double-entry'' accounting: the ledger must always balance to zero,
+with an equal number of debits and credits.
+
+For example, let's say you have a checking account and a brokerage
+account, and you can write checks from both of them. Rather than keep
+two checkbooks, you decide to use one ledger for both. In this
+general ledger you need to record a payment to Pacific Bell for your
+monthly phone bill. The cost is $23.00, let's say, and you want to
+pay it from your checking account. In the general ledger you need to
+say where the money came from, in addition to where it's going to.
+The entry might look like this:
+
+@smallexample
+9/29 BAL Pacific Bell $-200.00 $-200.00
+ Equity:Opening Balances $200.00
+9/29 BAL Checking $100.00 $100.00
+ Equity:Opening Balances $-100.00
+9/29 100 Pacific Bell $23.00 $223.00
+ Checking $-23.00 $77.00
+@end smallexample
+
+The first line shows a payment to Pacific Bell for $23.00. Because
+there is no ``balance'' in a general ledger---it's always zero---we
+write in the total balance of all payments to ``Pacific Bell'', which
+now is $223.00 (previously the balance was $200.00). This is done by
+looking at the last entry for ``Pacific Bell'' in the ledger, adding
+$23.00 to that amount, and writing the total in the balance column.
+And the money came from ``Checking''---a withdrawal of $23.00---which
+leaves the ending balance in ``Checking'' at $77.00. This is a very
+manual procedure; but that's where computers come in...
+
+The transaction must balance to $0: $23 went to Pacific Bell, $23 came
+from Checking. There is nothing left over to be accounted for, since
+the money has simply moved from one account to another. This is the
+basis of double-entry accounting: that money never pops in or out of
+existence; it is always a transaction from one account to another.
+
+Keeping a general ledger is the same as keeping two separate ledgers:
+One for Pacific Bell and one for Checking. In that case, each time a
+payment is written into one, you write a corresponding withdrawal into
+the other. This makes it easier to write in a ``running balance'',
+since you don't have to look back at the last time the account was
+referenced---but it also means having a lot of ledger books, if you
+deal with multiple accounts.
+
+Enter the beauty of computerized accounting. The purpose of the
+Ledger program is to make general ledger accounting simple, by keeping
+track of the balances for you. Your only job is to enter the
+transactions. If a transaction does not balance, Ledger displays an
+error and indicates the incorrect transaction.@footnote{In some
+special cases, it automatically balances this entry for you.}
+
+In summary, there are two aspects of Ledger use: updating the ledger
+data file, and using the Ledger tool to view the summarized result of
+your entries.
+
+And just for the sake of example---as a starting point for those who
+want to dive in head-first---here are the ledger entries from above,
+formatting as the ledger program wishes to see them:
+
+@smallexample
+2004/09/29 Pacific Bell
+ Payable:Pacific Bell $-200.00
+ Equity:Opening Balances
+
+2004/09/29 Checking
+ Accounts:Checking $100.00
+ Equity:Opening Balances
+
+2004/09/29 Pacific Bell
+ Payable:Pacific Bell $23.00
+ Accounts:Checking
+@end smallexample
+
+The account balances and registers in this file, if saved as
+@file{ledger.dat}, could be reported using:
+
+@example
+$ ledger -f ledger.dat balance
+$ ledger -f ledger.dat register checking
+$ ledger -f ledger.dat register bell
+@end example
+
+@menu
+* Building the program::
+* Getting help::
+@end menu
+
+@node Building the program, Getting help, Introduction, Introduction
+@section Building the program
+
+Ledger is written in ANSI C++, and should compile on any platform. It
+depends on the GNU multiprecision integer library (libgmp), and the
+Perl regular expression library (libpcre). It was developed using GNU
+make and gcc 3.3, on a PowerBook running OS/X.
+
+To build and install once you have these libraries on your system,
+enter these commands:
+
+@example
+./configure && make install
+@end example
+
+@node Getting help, , Building the program, Introduction
+@section Getting help
+
+If you need help on how to use Ledger, or run into problems, you can
+just the Ledger mailing list at the following Web address:
+
+@example
+https://lists.sourceforge.net/lists/listinfo/ledger-discuss
+@end example
+
+You can also find help at the @samp{#ledger} channel on the IRC server
+@samp{irc.freenode.net}.
+
+@node Running Ledger, Keeping a ledger, Introduction, Top
+@chapter Running Ledger
+
+Ledger has a very simple command-line interface, named---enticing
+enough---@command{ledger}. It supports a few reporting commands, and
+a large number of options for refining the output from those commands.
+The basic syntax of any ledger command is:
+
+@example
+ledger [OPTIONS...] COMMAND [ARGS...]
+@end example
+
+Command options must always precede the command word. After the
+command word there may appear any number of arguments. For most
+commands, these arguments are regular expressions that cause the
+output to relate only to transactions matching those regular
+expressions. For the @command{entry} command, the arguments have a
+special meaning, described below.
+
+The regular expressions arguments always match the account name that a
+transaction refers to. To match on the payee of the entry instead,
+precede the regular expression with @samp{--}. For example, the
+following balance command reports account totals for rent, food and
+movies, but only those whose payee matches Freddie:
+
+@example
+ledger bal rent food movies -- freddie
+@end example
+
+There are many, many command options available with the
+@command{ledger} command, and it takes a while to master them.
+However, none of them are required to use the basic reporting
+commands.
+
+@menu
+* Usage overview::
+* Commands::
+* Options::
+* Format strings::
+* Value expressions::
+* Period expressions::
+* File format::
+* Some typical queries::
+* Budgeting and forecasting::
+@end menu
+
+@node Usage overview, Commands, Running Ledger, Running Ledger
+@section Usage overview
+
+Before getting into the details of how to run Ledger, it will be
+easier to introduce the features in the context of their typical
+usage. To that end, this section presents a series of recipes,
+gradually introducing all of the command-line features of Ledger.
+
+For the purpose of these examples, assume the environment variable
+@var{LEDGER} is set to the file @file{sample.dat} (which is included
+in the distribution), and that the contents of that file are:
+
+@smallexample
+= /^Expenses:Books/
+ (Liabilities:Taxes) -0.10
+
+~ Monthly
+ Assets:Bank:Checking $500.00
+ Income:Salary
+
+2004/05/01 * Checking balance
+ Assets:Bank:Checking $1,000.00
+ Equity:Opening Balances
+
+2004/05/01 * Investment balance
+ Assets:Brokerage 50 AAPL @@ $30.00
+ Equity:Opening Balances
+
+2004/05/14 * Pay day
+ Assets:Bank:Checking $500.00
+ Income:Salary
+
+2004/05/27 Book Store
+ Expenses:Books $20.00
+ Liabilities:MasterCard
+
+2004/05/27 (100) Credit card company
+ Liabilities:MasterCard $20.00
+ Assets:Bank:Checking
+@end smallexample
+
+This sample file demonstrates a basic principle of accounting which it
+is recommended you follow: Keep all of your accounts under five parent
+Assets, Liabilities, Income, Expenses and Equity. It is important to
+do so in order to make sense out of the following examples.
+
+@subsection Checking balances
+
+Ledger has seven basic commands, but by far the most often used are
+@command{balance} and @command{register}. To see a summary balance of
+all accounts, use:
+
+@example
+ledger bal
+@end example
+
+@command{bal} is a short-hand for @command{balance}. This command
+prints out the summary totals of the five parent accounts used in
+@file{sample.dat}:
+
+@smallexample
+ $1,480.00
+ 50 AAPL Assets
+ $-2,500.00 Equity
+ $20.00 Expenses
+ $-500.00 Income
+ $-2.00 Liabilities
+--------------------
+ $-1,502.00
+ 50 AAPL
+@end smallexample
+
+None of the child accounts are shown, just the parent account totals.
+We can see that in @samp{Assets} there is $1,480.00, and 50 shares of
+Apple stock. There is also a negative grand total. Usually the grand
+total is zero, which means that all accounts balance@footnote{It is
+impossible for accounts not to balance in ledger; it reports an error
+if a transaction does not balance}. In this case, since the 50 shares
+of Apple stock cost $1,500.00 dollars, then these two amounts balance
+each other in the grand total. The extra $2.00 comes from a virtual
+transaction being added by the automatic entry at the top of the file.
+The entry is virtual because the account name was surrounded by
+parentheses in an automatic entry. Automatic entries will be
+discussed later, but first let's remove the virtual transaction from
+the balance report by using the @option{--real} option:
+
+@example
+ledger --real bal
+@end example
+
+Now the report is:
+
+@smallexample
+ $1,480.00
+ 50 AAPL Assets
+ $-2,500.00 Equity
+ $20.00 Expenses
+ $-500.00 Income
+--------------------
+ $-1,500.00
+ 50 AAPL
+@end smallexample
+
+Since the liability was a virtual transaction, it has dropped from the
+report and we see that final total is balanced.
+
+But we only know that it balances because @file{sample.dat} is quite
+simple, and we happen to know that the 50 shares of Apple stock cost
+$1,500.00. We can verify that things really balance by reporting the
+Apple shares in terms of their cost, instead of their quantity. To do
+this requires the @option{--basis}, or @option{-B}, option:
+
+@example
+ledger --real -B bal
+@end example
+
+This command reports:
+
+@smallexample
+ $2,980.00 Assets
+ $-2,500.00 Equity
+ $20.00 Expenses
+ $-500.00 Income
+@end smallexample
+
+With the basis cost option, the grand total has disappeared, as it is
+now zero. The confirms that the cost of everything balances to zero,
+@emph{which must always be true}. Reporting the real basis cost
+should never yield a remainder@footnote{If it ever does, then
+generated transactions are involved, which can be removed using
+@option{--actual}}.
+
+@subsubsection Sub-account balances
+
+The totals reported by the balance command are only the topmost parent
+accounts. To see the totals of all child accounts as well, use the
+@option{-s} option:
+
+@example
+ledger --real -B -s bal
+@end example
+
+This reports:
+
+@smallexample
+ $2,980.00 Assets
+ $1,480.00 Bank:Checking
+ $1,500.00 Brokerage
+ $-2,500.00 Equity:Opening Balances
+ $20.00 Expenses:Books
+ $-500.00 Income:Salary
+@end smallexample
+
+This shows that the @samp{Assets} total is made up from two child
+account, but that the total for each of the other accounts comes from
+one child account.
+
+Sometimes you may have a lot of children, nested very deeply, but only
+want to report the first two levels. This can be done with a display
+predicate, using a value expression. In the value expression,
+@code{T} represents the reported total, and @code{l} is the display
+level for the account:
+
+@example
+ledger --real -B -d "T&l<=2" bal
+@end example
+
+This reports:
+
+@smallexample
+ $2,980.00 Assets
+ $1,480.00 Bank
+ $1,500.00 Brokerage
+ $-2,500.00 Equity:Opening Balances
+ $20.00 Expenses:Books
+ $-500.00 Income:Salary
+@end smallexample
+
+Instead of reporting @samp{Bank:Checking} as a child of @samp{Assets},
+it report only @samp{Bank}, since that account is a nesting level of
+2, while @samp{Checking} is at level 3.
+
+To review the display predicate used---@code{T&l<=2}---this rather
+terse expression means: Display an account only if it has a non-zero
+total (@code{T}), and its nesting level is less than or equal to 2
+(@code{l<=2}).
+
+@subsubsection Specific account balances
+
+While reporting the totals for all accounts can be useful, most often
+you will want to check the balance of a specific account or accounts.
+To do this, put one or more account names after the balance command.
+Since these names are really regular expressions, you can use partial
+names if you wish:
+
+@example
+ledger bal checking
+@end example
+
+Reports:
+
+@smallexample
+ $1,480.00 Assets:Bank:Checking
+@end smallexample
+
+Any number of names may be used:
+
+@example
+ledger bal checking broker liab
+@end example
+
+Reports:
+
+@smallexample
+ $1,480.00 Assets:Bank:Checking
+ 50 AAPL Assets:Brokerage
+ $-2.00 Liabilities
+@end smallexample
+
+In this case no grand total is reported, because you are asking for
+specific account balances.
+
+For those comfortable with regular expressions, any Perl regexp is
+allowed:
+
+@example
+ledger bal ^assets.*checking ^liab
+@end example
+
+Reports:
+
+@smallexample
+ $1,480.00 Assets:Bank:Checking
+ $-2.00 Liabilities:Taxes
+@end smallexample
+
+@subsection The register report
+
+While the @command{balance} command can be very handy for checking
+account totals, by far the most powerful of Ledger's reporting tools
+is the @command{register} command. In fact, internally both commands
+use the same logic, but report the results differently:
+@command{balance} shows the summary totals, while @command{register}
+reports each transaction and how it contributes to that total.
+
+Paradoxically, the most basic form of @command{register} is almost
+never used, since it displays every transaction:
+
+@example
+ledger reg
+@end example
+
+@command{reg} is a short-hand for @command{register}. This command
+reports:
+
+@smallexample
+2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00
+ Equity:Opening Balan.. $-1,000.00 0
+2004/05/01 Investment balance Assets:Brokerage 50 AAPL 50 AAPL
+ Equity:Opening Balan.. $-1,500.00 $-1,500.00
+ 50 AAPL
+2004/05/14 Pay day Assets:Bank:Checking $500.00 $-1,000.00
+ 50 AAPL
+ Income:Salary $-500.00 $-1,500.00
+ 50 AAPL
+2004/05/27 Book Store Expenses:Books $20.00 $-1,480.00
+ 50 AAPL
+ Liabilities:MasterCard $-20.00 $-1,500.00
+ 50 AAPL
+ (Liabilities:Taxes) $-2.00 $-1,502.00
+ 50 AAPL
+2004/05/27 Credit card company Liabilities:MasterCard $20.00 $-1,482.00
+ 50 AAPL
+ Assets:Bank:Checking $-20.00 $-1,502.00
+ 50 AAPL
+@end smallexample
+
+This rather verbose output shows every account transaction in
+@file{sample.dat}, and how it affects the running total. The final
+total is identical to what we saw with the plain @command{balance}
+command. To see how things really balance, we can use @samp{--real
+-B}, just as we did with @command{balance}:
+
+@example
+ledger --real -B reg
+@end example
+
+Reports:
+
+@smallexample
+2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00
+ Equity:Opening Balan.. $-1,000.00 0
+2004/05/01 Investment balance Assets:Brokerage $1,500.00 $1,500.00
+ Equity:Opening Balan.. $-1,500.00 0
+2004/05/14 Pay day Assets:Bank:Checking $500.00 $500.00
+ Income:Salary $-500.00 0
+2004/05/27 Book Store Expenses:Books $20.00 $20.00
+ Liabilities:MasterCard $-20.00 0
+2004/05/27 Credit card company Liabilities:MasterCard $20.00 $20.00
+ Assets:Bank:Checking $-20.00 0
+@end smallexample
+
+Here we see that everything balances to zero in the end, as it must.
+
+@subsubsection Specific register queries
+
+The most common use of the register command is to summarize
+transactions based on the account(s) they affect. Using
+@file{sample.dat} as as example, we could look at all book purchases
+using:
+
+@example
+ledger reg books
+@end example
+
+Reports:
+
+@smallexample
+2004/05/29 Book Store Expenses:Books $20.00 $20.00
+@end smallexample
+
+If a double-dash (@samp{--}) occurs in the list of regular
+expressions, any following arguments are matched against payee names,
+instead of account names:
+
+@example
+ledger reg ^liab -- credit
+@end example
+
+Reports:
+
+@smallexample
+2004/05/29 Credit card company Liabilities:MasterCard $20.00 $20.00
+@end smallexample
+
+There are many reporting options for tailoring which transactions are
+found, and also how to summarize the various amounts and totals that
+result. These are plumbed in greater depth below.
+
+@subsection Selecting transactions
+
+Although the easiest way to use the register is to report all the
+transactions affecting a set of accounts, it can often result in more
+information than you want. To cope with an ever-growing amount of
+data, there are several options which can help you pinpoint your
+report to exactly the transactions that interest you most. This is
+called the ``calculation'' phase of Ledger. All of its related
+options are documented under @option{--help-calc}.
+
+@subsubsection By date
+
+@c -c, --current show only current and past entries (not future)
+
+@option{--current}(@option{-c}) displays entries occurring on or
+before the current date. Any entry recorded for a future date will be
+ignored, as if it had not been seen. This is useful if you happen to
+pre-record entries, but still wish to view your balances in terms of
+what is available today.
+
+@c -b, --begin DATE set report begin date
+@c -e, --end DATE set report end date
+
+@option{--begin DATE} (@option{-b DATE}) limits the report to only
+those entries occurring on or after @var{DATE}. The running total in
+the register will start at zero with the first transaction, even if
+there are earlier entries.
+
+To limit the display only, but still add earlier transactions to the
+running total, use the display expression @samp{-d 'd>=[DATE]'}):
+
+@example
+ledger --basis -b may -d 'd>=[5/14]' reg ^assets
+@end example
+
+Reports:
+
+@smallexample
+2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00
+2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00
+@end smallexample
+
+In this example, the displayed transactions start from @samp{5/14},
+but the calculated total starts from the beginning of @samp{may}.
+
+@option{--end DATE} (@option{-e DATE}) states when reporting should
+end, both calculation and display. The ending date is inclusive.
+
+The @var{DATE} argument to the @option{-b} and @option{-e} options can
+be rather flexible. Assuming the current date to be November 15,
+2004, then all of the following are equivalent:
+
+@example
+ledger -b oct bal
+ledger -b "this oct" bal
+ledger -b 2004/10 bal
+ledger -b 10 bal
+ledger -b last bal
+ledger -b "last month" bal
+@end example
+
+@c -p, --period STR report using the given period
+@c --period-sort EXPR sort each report period's entries by EXPR
+
+To constrain the report to a specific time period, use
+@option{--period} (@option{-p}). A time period may have both a
+beginning and an end, or neither, as well as a specified interval.
+Here are a few examples:
+
+@example
+ledger -p 2004 bal
+ledger -p august bal
+ledger -p "from aug to oct" bal
+ledger -p "daily from 8/1 to 8/15" bal
+ledger -p "weekly since august" bal
+ledger -p "monthly from feb to oct" bal
+ledger -p "quarterly in 2004" bal
+ledger -p yearly bal
+@end example
+
+See @ref{Period expressions} for more on syntax. Also, all of the
+options @option{-b}, @option{-e} and @option{-p} may be used together,
+but whatever information occurs last takes priority. An example of
+such usage (in a script, perhaps) would be:
+
+@example
+ledger -b 2004 -e 2005 -p monthly reg ^expenses
+@end example
+
+This command is identical to:
+
+@example
+ledger -p "monthly in 2004" reg ^expenses
+@end example
+
+The transactions within a period may be sorted using
+@option{--period-sort}, which takes a value expression. This is
+similar to the @option{--sort} option, except that it sorts within
+each period entry, rather than sorting all transactions in the report.
+See the documentation on @option{--sort} below for more details.
+
+@subsubsection By status
+
+By default, all regular transactions are included in each report. To
+limit the report to certain kinds of transactions, use one or more of
+the following options:
+
+@table @option
+@item -C, --cleared
+Consider only cleared transactions.
+@item -U, --uncleared
+Consider only uncleared and pending transactions.
+@item -R, --real
+Consider only real (non-virtual) transactions.
+@item -L, --actual
+Consider only actual (non-automated) transactions.
+@end table
+
+Cleared transactions are indicated by an asterix placed just before
+the payee name in a transaction. The meaning of this flag is up to
+the user, but typically it means that an entry has been seen on a
+financial statement. Pending transactions use an exclamation mark in
+the same position, but are mainly used only by reconciling software.
+Uncleared transactions are for things like uncashed checks, credit
+charges that haven't appeared on a statement yet, etc.
+
+Real transactions are all non-virtual transactions, where the account
+name is not surrounded by parentheses or square brackets. Virtual
+transactions are useful for showing a transfer of money that never
+really happened, like money set aside for savings without actually
+transferring it from the parent account.
+
+Actual transactions are those not generated, either as part of an
+automated entry, or a budget or forecast report. A useful of when you
+might like to filter out generated transactions is with a budget:
+
+@example
+ledger --budget --actual reg ^expenses
+@end example
+
+This command outputs all transactions affecting a budgeted account,
+but without subtracting the budget amount (because the generated
+transactions are suppressed with @option{--actual}). The report shows
+how much you actually spent on budgeted items.
+
+@subsubsection By relationship
+
+@c -r, --related calculate report using related transactions
+
+Normally, a register report includes only the transactions that match
+the regular expressions specified after the command word. For
+example, to report all expenses:
+
+@example
+ledger reg ^expenses
+@end example
+
+This reports:
+
+@smallexample
+2004/05/29 Book Store Expenses:Books $20.00 $20.00
+@end smallexample
+
+Using @option{--related} (@option{-r}) reports the transactions that
+did not match your query, but only in entries that otherwise would
+have matched. This has the effect of indicating where money came
+from, or when to:
+
+@example
+ledger -r reg ^expenses
+@end example
+
+Reports:
+
+@smallexample
+2004/05/29 Book Store Liabilities:MasterCard $20.00 $20.00
+@end smallexample
+
+@subsubsection By budget
+
+@c --budget generate budget entries based on FILE
+
+There is more information about budgeting and forecasting in
+@ref{Budgeting and forecasting}. Basically, if you have any period
+entries in your ledger file, you can use these options. A period
+entry looks like:
+
+@example
+~ Monthly
+ Assets:Bank:Checking $500.00
+ Income:Salary
+@end example
+
+The difference from a regular entry is that the first line begins with
+a tilde (~), and instead of a payee there's a period expression
+(@ref{Period expressions}). Otherwise, a period entry is in every
+other way the same as a regular entry.
+
+With such an entry in your ledger file, the @option{--budget} option
+will report only transactions that match a budgeted account. Using
+@file{sample.dat} from above:
+
+@example
+ledger --budget reg ^income
+@end example
+
+Reports:
+
+@smallexample
+2004/05/01 Budget entry Income:Salary $500.00 $500.00
+2004/05/14 Pay day Income:Salary $-500.00 0
+@end smallexample
+
+The final total is zero, indicating that the budget matched exactly
+for the reported period. Budgeting is most often helpful with period
+reporting; for example, to show monthly budget results use
+@option{--budget -p monthly}.
+
+@c --add-budget show all transactions plus the budget
+@c --unbudgeted show only unbudgeted transactions
+
+The @option{--add-budget} option reports all matching transactions in
+addition to budget transactions; while @option{--unbudgeted} shows
+only those that don't match a budgeted account. To summarize:
+
+@table @option
+@item --budget
+Show transactions matching budgeted accounts.
+@item --unbudgeted
+Show transactions matching unbudgeted accounts.
+@item --add-budget
+Show both budgeted and unbudgeted transactions together (i.e., add the
+generated budget transactions to the regular report).
+@end table
+
+@c --forecast EXPR generate forecast entries while EXPR is true
+
+A report with the @option{--forecast} option will add budgeted
+transactions while the specified value expression is true. For
+example:
+
+@example
+ledger --forecast 'd<[2005] reg ^income
+@end example
+
+Reports:
+
+@smallexample
+2004/05/14 Pay day Income:Salary $-500.00 $-500.00
+2004/12/01 Forecast entry Income:Salary $-500.00 $-1,000.00
+2005/01/01 Forecast entry Income:Salary $-500.00 $-1,500.00
+@end smallexample
+
+The date this report was made was November 5, 2004; the reason the
+first forecast entry is in december is that forecast entries are only
+added for the future, and they only stop after the value expression
+has matched at least once, which is why the January entry appears. A
+forecast report can be very useful for determining when money will run
+out in an account, or for projecting future cash flow:
+
+@example
+ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp
+@end example
+
+This reports balances projected income against projected expenses,
+showing the resulting total in yearly intervals until 2008. For the
+case of @file{sample.dat}, which has no budgeted expenses, the result
+of the above command (in November 2004) is:
+
+@smallexample
+2004/01/01 - 2004/12/31 Income:Salary $-1,000.00 $-1,000.00
+ Expenses:Books $20.00 $-980.00
+2005/01/01 - 2005/12/31 Income:Salary $-6,000.00 $-6,980.00
+2006/01/01 - 2006/12/31 Income:Salary $-6,000.00 $-12,980.00
+2007/01/01 - 2007/12/31 Income:Salary $-6,000.00 $-18,980.00
+2008/01/01 - 2008/01/01 Income:Salary $-500.00 $-19,480.00
+@end smallexample
+
+@subsubsection By value expression
+
+@c -l, --limit EXPR calculate only transactions matching EXPR
+
+Value expressions can be quite complex, and are treated more fully in
+@ref{Value expressions}. They can be used for limiting a report with
+@option{--limit} (@option{-l}). The following command report income
+since august, but expenses since october:
+
+@example
+ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg
+@end example
+
+The basic form of this value expression is @samp{(A&B)|(A&B)}. The
+@samp{A} in each part matches against an account name with
+@samp{/name/}, while each @samp{B} part compares the date of the
+transaction (@samp{d}) with a specified month. The resulting report
+will contain only transactions which match the value expression.
+
+@c -t, --amount EXPR use EXPR to calculate the displayed amount
+@c -T, --total EXPR use EXPR to calculate the displayed total
+
+Another use of value expressions is to calculate the amount reported
+for each line of a register report, or for computing the subtotal of
+each account shown in a balance report. This example divides each
+transaction amount by two:
+
+@example
+ledger -t 'a/2' reg ^exp
+@end example
+
+The @option{-t} option doesn't affect the running total, only how the
+transaction amount is displayed. To change the running total, use
+@option{-T}. In that case, you will likely want to use the total
+(@samp{O}) instead of the amount (@samp{a}):
+
+@example
+ledger -T 'O/2' reg ^exp
+@end example
+
+@subsection Massaging register output
+
+Even after filtering down your data to just the transactions you're
+interested in, the default reporting method of one transaction per
+line is often still too much. To combat this complexity, it is
+possible to ask Ledger to report the details to you in many different
+forms, summarized in various ways. This is the ``display'' phase of
+Ledger, and is documented under @option{--help-disp}.
+
+@subsubsection Summarizing
+
+@c -n, --collapse register: collapse entries with multiple transactions
+
+When multiple transactions relate to a single entry, they are reported
+as part of that entry. For example, in the case of @file{sample.dat}:
+
+@example
+ledger reg -- book
+@end example
+
+Reports:
+
+@smallexample
+2004/05/29 Book Store Expenses:Books $20.00 $20.00
+ Liabilities:MasterCard $-20.00 0
+ (Liabilities:Taxes) $-2.00 $-2.00
+@end smallexample
+
+All three transactions are part of one entry, and as such the entry
+details are printed only once. To report every entry on a single
+line, use @option{-n} to collapse entries with multiple transactions:
+
+@example
+ledger -n reg -- book
+@end example
+
+Reports:
+
+@smallexample
+2004/05/29 Book Store <Total> $-2.00 $-2.00
+@end smallexample
+
+In the balance report, @option{-n} causes the grand total not to be
+displayed at the bottom of the report.
+
+@c -s, --subtotal balance: show sub-accounts; other: show subtotals
+
+If an account occurs more than once in a report, it is possible to
+combine them all and report the total per-account, using @option{-s}.
+For example, this command:
+
+@example
+ledger -B reg ^assets
+@end example
+
+Reports:
+
+@smallexample
+2004/05/01 Checking balance Assets:Bank:Checking $1,000.00 $1,000.00
+2004/05/01 Investment balance Assets:Brokerage $1,500.00 $2,500.00
+2004/05/14 Pay day Assets:Bank:Checking $500.00 $3,000.00
+2004/05/27 Credit card company Assets:Bank:Checking $-20.00 $2,980.00
+@end smallexample
+
+But if the @option{-s} option is added, the result becomes:
+
+@smallexample
+2004/05/01 - 2004/05/29 Assets:Bank:Checking $1,480.00 $1,480.00
+ Assets:Brokerage $1,500.00 $2,980.00
+@end smallexample
+
+When account subtotaling is used, only one entry is printed, and the
+date and name reflect the range of the combined transactions.
+
+@c -P, --by-payee show summarized totals by payee
+
+With @option{-P}, transactions relating to the same payee are
+combined. In this case, the date of the combined entry is that of the
+latest transaction.
+
+@c -x, --comm-as-payee set commodity name as the payee, for reporting
+
+@option{-x} changes the payee name for each transaction to be the same
+as the commodity it uses. This can be especially useful combined with
+other options, like @option{-P}. For example:
+
+@example
+ledger -Px reg ^assets
+@end example
+
+Reports:
+
+@smallexample
+2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00
+2004/05/01 AAPL Assets:Brokerage 50 AAPL $1,480.00
+ 50 AAPL
+@end smallexample
+
+This reports shows the subtotal for each commodity held, and where it
+is located. To see the basis cost, or initial investment, add
+@option{-B}. Applied to the example above:
+
+@smallexample
+2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00
+2004/05/01 AAPL Assets:Brokerage $1,500.00 $2,980.00
+@end smallexample
+
+@c -E, --empty balance: show accounts with zero balance
+
+The only other options which affect summarized totals is @option{-E},
+which works only in the balance report. In this case, it shows
+matching accounts with a zero a balance, which are ordinarily
+excluded. This can be useful to see all the accounts involved in a
+report, even if some have no total.
+
+@subsubsection Quick periods
+
+Although the @option{-p} option (also @option{--period}) is much more
+versatile, there are other options to make the most common period
+reports easier:
+
+@table @option
+@item -W, --weekly
+Show weekly sub-totals. Same as @samp{-p weekly}.
+@item -M, --monthly
+Show monthly sub-totals. Same as @samp{-p monthly}.
+@item -Y, --yearly
+Show yearly sub-totals. Same as @samp{-p yearly}.
+@end table
+
+@c --dow show a days-of-the-week report
+
+There is one kind of period report cannot be done with @option{-p}.
+This is the @option{--dow}, or ``days of the week'' report, which
+shows summarized totals for each day of the week. The following
+examples shows a ``day of the week'' report of income and expenses:
+
+@example
+ledger --dow reg ^inc ^exp
+@end example
+
+Reports:
+
+@smallexample
+2004/05/27 Thursdays Expenses:Books $20.00 $20.00
+2004/05/14 Fridays Income:Salary $-500.00 $-480.00
+@end smallexample
+
+@subsubsection Ordering and width
+
+@c -S, --sort EXPR sort report according to the value expression EXPR
+
+The transactions displayed in a report are shown in the same order as
+they appear in the ledger file. To change the order and sort a
+report, use the @option{--sort} option. @option{--sort} takes a value
+expression to determine the value to sort against, making it possible
+to sort according to complex criteria. Here are some simple and
+useful examples:
+
+@example
+ledger --sort d reg ^exp # sort by date
+ledger --sort t reg ^exp # sort by amount total
+ledger --sort -t reg ^exp # reverse sort by amount total
+ledger --sort Ut reg ^exp # sort by abs amount total
+@end example
+
+For the balance report, you will want to use @samp{T} instead of
+@samp{t}:
+
+@example
+ledger --sort T reg ^exp # sort by amount total
+ledger --sort -T reg ^exp # reverse sort by amount total
+ledger --sort UT reg ^exp # sort by abs amount total
+@end example
+
+The @option{--sort} options sorts all transactions in a report. If
+periods are used (such as @option{--monthly}), this can get somewhat
+confusing. In that case, you'll probably want to sort within periods
+using @option{--period-sort} instead of @option{--sort}.
+
+@c -w, --wide for the default register report, use 132 columns
+
+And if the register seems too cramped, and you have a lot of screen
+real estate, you can use @option{-w} to format the report within 132
+acolumns, instead of 80. You are more likely then to see full payee
+and account names, as well as properly formatted totals when
+long-named commodities are used.
+
+If you want only the first or last N entries to be printed---which can
+be very useful for viewing the last 10 entries in your checking
+account, while also showing the cumulative balance from all
+entries---use the @option{--head} and/or @option{--tail} options. The
+two options may be used simultaneously, for example:
+
+@example
+ledger --tail 20 reg checking
+@end example
+
+If the output from your command is very long, Ledger can output the
+data to a pager utility, such as @command{more} or @command{less}:
+
+@example
+ledger --pager /usr/bin/less reg checking
+@end example
+
+@subsubsection Averages and percentages
+
+@c -A, --average report average transaction amount
+
+To see the running total changed to a running average, use
+@option{-A}. The final transaction's total will be the overall
+average of all displayed transactions. The works in conjunction with
+period reporting, so that you can see your monthly average expenses
+with:
+
+@example
+ledger -AM reg ^expenses:food
+ledger -AMn reg ^expenses
+@end example
+
+This works in the balance report too:
+
+@example
+ledger -AM bal ^expenses:food
+ledger -AMs bal ^expenses
+@end example
+
+@c -D, --deviation report deviation from the average
+
+The @option{-D} option changes the running average into a deviation
+from the running average. This only makes sense in the register
+report, however.
+
+@example
+ledger -DM reg ^expenses:food
+@end example
+
+@c -%, --percentage report balance totals as a percentile of the parent
+
+In the balance report only, @option{-%} changes the reported totals
+into a percentage of the parent account. This kind of report is
+confusing if negative amounts are involved, and doesn't work at all if
+multiple commodities occur in an account's history. It has a somewhat
+limited usefulness, therefore, but in certain cases it can be handy,
+such as reviewing overall expenses:
+
+@example
+ledger -%s -S T bal ^expenses
+@end example
+
+@subsubsection Reporting total data
+
+@c --totals in the "xml" report, include running total
+
+Normally in the @command{xml} report, only transaction amounts are
+printed. To include the running total under a @samp{<total>} tag, use
+@option{--totals}. This does not affect any other report.
+
+@c -j, --amount-data print only raw amount data (useful for scripting)
+@c -J, --total-data print only raw total data
+
+In the register report only, the output can be changed with
+@option{-j} to show only the date and the amount---without
+commodities. This only makes sense if a single commodity appears in
+the report, but can be quite useful for scripting, or passing the data
+to Gnuplot. To show only the date and running total, use @option{-J}.
+
+@subsubsection Display by value expression
+
+@c -d, --display EXPR display only transactions matching EXPR
+
+With @option{-d} you can decide which transactions (or accounts in the
+balance report) are displayed, according to a value expression. The
+computed total is not affected, only the display. This can be very
+useful for shortening a report without changing the running total:
+
+@example
+ledger -d 'd>=[last month]' reg checking
+@end example
+
+This command shows the checking account's register, beginning from
+last month, but with the running total reflecting the entire history
+of the account.
+
+@subsubsection Change report format
+
+@c -y, --date-format STR use STR as the date format (default: %Y/%m/%d)
+
+When dates are printed in any report, the default format is
+@samp{%Y/%m/%d}, which yields dates of the form @samp{YYYY/mm/dd}.
+This can be changed with @option{-y}, whose argument is a
+@code{strftime} string---see your system's C library documentation for
+the allowable codes. Mostly you will want to use @samp{%Y}, @samp{%m}
+and @samp{%d}, in whatever combination is convenient for your locale.
+
+@c -F, --format STR use STR as the format; for each report type, use:
+@c --balance-format --register-format --print-format
+@c --plot-amount-format --plot-total-format --equity-format
+@c --prices-format --wide-register-format
+
+To change the format of the entire reported line, use @option{-F}. It
+supports quite a large number of options, which are all documented in
+@ref{Format strings}. In addition, each specific kind of report
+(except for @command{xml}) can be changed using one of the following
+options:
+
+@table @option
+@item --balance-format
+@command{balance} report. Default:
+@smallexample
+%20T %2_%-a\n
+@end smallexample
+
+@item --register-format
+@command{register} report. Default:
+@smallexample
+%D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n
+@end smallexample
+
+@item --print-format
+@command{print} report. Default:
+@smallexample
+%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n
+@end smallexample
+
+@item --plot-amount-format
+@command{register} report when @option{-j} (plot amount) is used. Default:
+@smallexample
+%D %(St)\n
+@end smallexample
+
+@item --plot-total-format
+@command{register} report when @option{-J} (plot total) is used. Default:
+@smallexample
+%D %(ST)\n
+@end smallexample
+
+@item --equity-format
+@command{equity} report. Default:
+@smallexample
+\n%D %Y%C%P\n %-34W %12o%n\n%/ %-34W %12o%n\n
+@end smallexample
+
+@item --prices-format
+@command{prices} report. Default:
+@smallexample
+\n%D %Y%C%P\n%/ %-34W %12t\n
+@end smallexample
+
+@item --wide-register-format
+@command{register} report when @option{-w} (wide) is used. Default:
+@smallexample
+%D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n
+@end smallexample
+@end table
+
+@subsection Standard queries
+
+If your ledger file uses the standard top-level accounts: Assets,
+Liabilities, Income, Expenses, Equity: then the following queries will
+enable you to generate some typical accounting reports from your data.
+
+Your @emph{net worth} can be determined by balancing assets against
+liabilities:
+
+@example
+ledger bal ^assets ^liab
+@end example
+
+By removing long-term investment and loan accounts, you can see your
+current net liquidity (or liquid net worth):
+
+@example
+ledger bal ^assets ^liab -retirement -brokerage -loan
+@end example
+
+Balancing expenses against income yields your @emph{cash flow}, or net
+profit/loss:
+
+@example
+ledger bal ^exp ^inc
+@end example
+
+In this case, if the number is positive it means you spent more than
+you earned during the report period.
+
+@c ----------------------------------------------------------------------
+
+The most often used command is the ``balance'' command:
+
+@example
+export LEDGER=/home/johnw/doc/ledger.dat
+ledger balance
+@end example
+
+Here I've set my Ledger environment variable to point to where my
+ledger file is hiding. Thereafter, I needn't specify it again.
+
+@subsection Reporting balance totals
+
+The balance command prints out the summarized balances of all my
+top-level accounts, excluding sub-accounts. In order to see the
+balances for a specific account, just specify a regular expression
+after the balance command:
+
+@example
+ledger balance expenses:food
+@end example
+
+This will show all the money that's been spent on food, since the
+beginning of the ledger. For food spending just this month
+(September), use:
+
+@example
+ledger -p sep balance expenses:food
+@end example
+
+Or maybe you want to see all of your assets, in which case the -s
+(show sub-accounts) option comes in handy:
+
+@example
+ledger -s balance ^assets
+@end example
+
+To exclude a particular account, use a regular expression with a
+leading minus sign. The following will show all expenses, but without
+food spending:
+
+@example
+ledger balance expenses -food
+@end example
+
+@subsection Reporting percentages
+
+There is no built-in way to report transaction amounts or account
+balances in terms of percentages
+
+@node Commands, Options, Usage overview, Running Ledger
+@section Commands
+
+@subsection balance
+
+The @command{balance} command reports the current balance of all
+accounts. It accepts a list of optional regexps, which confine the
+balance report to the matching accounts. If an account contains
+multiple types of commodities, each commodity's total is reported
+separately.
+
+@subsection register
+
+The @command{register} command displays all the transactions occurring
+in a single account, line by line. The account regexp must be
+specified as the only argument to this command. If any regexps occur
+after the required account name, the register will contain only those
+transactions that match. Very useful for hunting down a particular
+transaction.
+
+The output from @command{register} is very close to what a typical
+checkbook, or single-account ledger, would look like. It also shows a
+running balance. The final running balance of any register should
+always be the same as the current balance of that account.
+
+If you have Gnuplot installed, you may plot the amount or running
+total of any register by using the script @file{report}, which is
+included in the Ledger distribution. The only requirement is that you
+add either @option{-j} or @option{-J} to your register command, in
+order to plot either the amount or total column, respectively.
+
+@subsection print
+
+The @command{print} command prints out ledger entries in a textual
+format that can be parsed by Ledger. They will be properly formatted,
+and output in the most economic form possible. The ``print'' command
+also takes a list of optional regexps, which will cause only those
+transactions which match in some way to be printed.
+
+The @command{print} command can be a handy way to clean up a ledger
+file whose formatting has gotten out of hand.
+
+@subsection output
+
+The @command{output} command is very similar to the @command{print}
+command, except that it attempts to replicate the specified ledger
+file exactly. The format of the command is:
+
+@example
+ledger -f FILENAME output FILENAME
+@end example
+
+Where @file{FILENAME} is the name of the ledger file to output. The
+reason for specifying this command is that only entries contained
+within that file will be output, and not an included entries (as can
+happen with the @command{print} command).
+
+@subsection xml
+
+The @command{xml} command outputs results similar to what
+@command{print} and @command{register} display, but as an XML form.
+This data can then be read in and processed. Use the
+@option{--totals} option to include the running total with each
+transaction.
+
+@subsection emacs
+
+The @command{emacs} command outputs results in a form that can be read
+directly by Emacs Lisp. The format of the sexp is:
+
+@example
+((BEG-POS CLEARED DATE CODE PAYEE
+ (ACCOUNT AMOUNT)...) ; list of transactions
+ ...) ; list of entries
+@end example
+
+@subsection equity
+
+The @command{equity} command prints out accounts balances as if they
+were entries. This makes it easy to establish the starting balances
+for an account, such as when @ref{Archiving previous years}.
+
+@subsection prices
+
+The @command{prices} command displays the price history for matching
+commodities. The @option{-A} flag is useful with this report, to
+display the running average price, or @option{-D} to show each price's
+deviation from that average.
+
+There is also a @command{pricesdb} command which outputs the same
+information as @command{prices}, but does in a format that can be
+parsed by Ledger.
+
+@subsection entry
+
+The @command{entry} commands simplifies the creation of new entries.
+It works on the principle that 80% of all transactions are variants of
+earlier transactions. Here's how it works:
+
+Say you currently have this transaction in your ledger file:
+
+@smallexample
+2004/03/15 * Viva Italiano
+ Expenses:Food $12.45
+ Expenses:Tips $2.55
+ Liabilities:MasterCard $-15.00
+@end smallexample
+
+Now it's @samp{2004/4/9}, and you've just eating at @samp{Viva
+Italiano} again. The exact amounts are different, but the overall
+form is the same. With the @command{entry} command you can type:
+
+@example
+ledger entry 2004/4/9 viva food 11 tips 2.50
+@end example
+
+This produces the following output:
+
+@smallexample
+2004/04/09 Viva Italiano
+ Expenses:Food $11.00
+ Expenses:Tips $2.50
+ Liabilities:MasterCard $-13.50
+@end smallexample
+
+It works by finding a past transaction matching the regular expression
+@samp{viva}, and assuming that any accounts or amounts specified will
+be similar to that earlier transaction. If Ledger does not succeed in
+generating a new entry, an error is printed and the exit code is set
+to @samp{1}.
+
+There is a shell script in the distribution's @file{scripts} directory
+called @file{entry}, which simplifies the task of adding a new entry
+to your ledger. It launches @command{vi} to confirm that the entry
+looks appropriate.
+
+Here are a few more examples of the @command{entry} command, assuming
+the above journal entry:
+
+@example
+ledger entry 4/9 viva 11.50
+ledger entry 4/9 viva 11.50 checking # (from `checking')
+ledger entry 4/9 viva food 11.50 tips 8
+ledger entry 4/9 viva food 11.50 tips 8 cash
+ledger entry 4/9 viva food $11.50 tips $8 cash
+ledger entry 4/9 viva dining "DM 11.50"
+@end example
+
+@node Options, Format strings, Commands, Running Ledger
+@section Options
+
+With all of the reports, command-line options are useful to modify the
+output generated. These command-line options always occur before the
+command word. This is done to distinguish options from exclusive
+regular expressions, which also begin with a dash. The basic form for
+most commands is:
+
+@example
+ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]]
+@end example
+
+The @var{OPTIONS} and @var{REGEXPS} expressions are both optional.
+You could just use @samp{ledger balance}, without any options---which
+prints a summary of all accounts. But for more specific reporting, or
+to change the appearance of the output, options are needed.
+
+@menu
+* Basic options::
+* Report filtering::
+* Output customization::
+* Commodity reporting::
+* Environment variables::
+@end menu
+
+@node Basic options, Report filtering, Options, Options
+@subsection Basic options
+
+These are the most basic command options. Most likely, the user will
+want to set them using @ref{Environment variables}, instead of using
+actual command-line options:
+
+@option{--help} (@option{-h}) prints a summary of all the options, and
+what they are used for. This can be a handy way to remember which
+options do what. This help screen is also printed if ledger is run
+without a command.
+
+@option{--version} (@option{-v}) prints the current version of ledger
+and exits. This is useful for sending bug reports, to let the author
+know which version of ledger you are using.
+
+@option{--file FILE} (@option{-f FILE}) reads FILE as a ledger file.
+This command may be used multiple times. FILE may also be a list of
+file names separated by colons. Typically, the environment variable
+@env{LEDGER_FILE} is set, rather than using this command-line option.
+
+@option{--output FILE} (@option{-o FILE}) redirects output from any
+command to @var{FILE}. By default, all output goes to standard
+output.
+
+@option{--init-file FILE} (@option{-i FILE}) causes FILE to be read by
+ledger before any other ledger file. This file may not contain any
+transactions, but it may contain option settings. To specify options
+in the init file, use the same syntax as the command-line. Here's an
+example init file:
+
+@smallexample
+--price-db ~/finance/.pricedb
+
+; ~/.ledgerrc ends here
+@end smallexample
+
+Option settings on the command-line or in the environment always take
+precedence over settings in the init file.
+
+@option{--cache FILE} identifies FILE as the default binary cache
+file. That is, if the ledger files to be read are specified using the
+environment variable @env{LEDGER_FILE}, then whenever a command is
+finished a binary copy will be written to the specified cache, to
+speed up the loading time of subsequent queries. This filename can
+also be given using the environment variable @env{LEDGER_CACHE}, or by
+putting the option into your init file. The @option{--no-cache}
+option causes Ledger to always ignore the binary cache.
+
+@option{--account NAME} (@option{-a NAME}) specifies the default
+account which QIF file transactions are assumed to relate to.
+
+@node Report filtering, Output customization, Basic options, Options
+@subsection Report filtering
+
+These options change which transactions affect the outcome of a
+report, in ways other than just using regular expressions:
+
+@option{--current}(@option{-c}) displays only entries occurring on or
+before the current date.
+
+@option{--begin DATE} (@option{-b DATE}) constrains the report to
+entries on or after @var{DATE}. Only entries after that date will be
+calculated, which means that the running total in the balance report
+will always start at zero with the first matching entry. (Note: This
+is different from using @option{--display} to constrain what is
+displayed).
+
+@option{--end DATE} (@option{-e DATE}) constrains the report so that
+entries on or after @var{DATE} are not considered. The ending date
+is inclusive.
+
+@option{--period STR} (@option{-p STR}) sets the reporting period
+to @var{STR}. This will subtotal all matching entries within each
+period separately, making it easy to see weekly, monthly, quarterly,
+etc., transaction totals. A period string can even specify the
+beginning and end of the report range, using simple terms like ``last
+june'' or ``next month''. For more using period expressions, see
+@ref{Period expressions}.
+
+@option{--period-sort EXPR} sorts the transactions within each
+reporting period using the value expression @var{EXPR}. This is most
+often useful when reporting monthly expenses, in order to view the
+highest expense categories at the top of each month:
+
+@example
+ledger -M --period-sort -At reg ^Expenses
+@end example
+
+@option{--cleared} (@option{-C}) displays only transactions whose entry
+has been marked ``cleared'' (by placing an asterix to the right of the
+date).
+
+@option{--uncleared} (@option{-U}) displays only transactions whose
+entry has not been marked ``cleared'' (i.e., if there is no asterix to
+the right of the date).
+
+@option{--real} (@option{-R}) displays only real transactions, not
+virtual. (A virtual transaction is indicated by surrounding the
+account name with parentheses or brackets; see the section on using
+virtual transactions for more information).
+
+@option{--actual} (@option{-L}) displays only actual transactions, and
+not those created due to automated transactions.
+
+@option{--related} (@option{-r}) displays transactions that are
+related to whichever transactions would otherwise have matched the
+filtering criteria. In the register report, this shows where money
+went to, or the account it came from. In the balance report, it shows
+all the accounts affected by entries having a related transaction.
+For example, if a file had this entry:
+
+@smallexample
+2004/03/20 Safeway
+ Expenses:Food $65.00
+ Expenses:Cash $20.00
+ Assets:Checking $-85.00
+@end smallexample
+
+And the register command was:
+
+@example
+ledger -r register food
+@end example
+
+The following would be output, showing the transactions related to the
+transaction that matched:
+
+@smallexample
+2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00
+ Assets:Checking $85.00 $65.00
+@end smallexample
+
+@option{--budget} is useful for displaying how close your transactions
+meet your budget. @option{--add-budget} also shows unbudgeted
+transactions, while @option{--unbudgeted} shows only those.
+@option{--forecast} is a related option that projects your budget into
+the future, showing how it will affect future balances.
+@xref{Budgeting and forecasting}.
+
+@option{--limit EXPR} (@option{-l EXPR}) limits which transactions
+take part in the calculations of a report.
+
+@option{--amount EXPR} (@option{-t EXPR}) changes the value expression
+used to calculate the ``value'' column in the @command{register}
+report, the amount used to calculate account totals in the
+@command{balance} report, and the values printed in the
+@command{equity} report. @xref{Value expressions}.
+
+@option{--total EXPR} (@option{-T EXPR}) sets the value expression
+used for the ``totals'' column in the @command{register} and
+@command{balance} reports.
+
+@node Output customization, Commodity reporting, Report filtering, Options
+@subsection Output customization
+
+These options affect only the output, but not which transactions are
+used to create it:
+
+@option{--collapse} (@option{-n}) causes entries in a
+@command{register} report with multiple transactions to be collapsed
+into a single, subtotaled entry.
+
+@option{--subtotal} (@option{-s}) causes all entries in a
+@command{register} report to be collapsed into a single, subtotaled
+entry.
+
+@option{--by-payee} (@option{-P}) reports subtotals by payee.
+
+@option{--comm-as-payee} (@option{-x}) changes the payee of every
+transaction to be the commodity used in that transaction. This can be
+useful when combined with other options, such as @option{-s}.
+
+@option{--empty} (@option{-E}) includes even empty accounts in the
+@command{balance} report.
+
+@option{--weekly} (@option{-W}) reports transaction totals by the
+week. The week begins on whichever day of the week begins the month
+containing that transaction. To set a specific begin date, use a
+period string, such as @samp{weekly from DATE}. @option{--monthly}
+(@option{-M}) reports transaction totals by month; @option{--yearly}
+(@option{-Y}) reports transaction totals by year. For more complex
+period, using the @option{--period} option described above.
+
+@option{--dow} reports transactions totals for each day of the week.
+This is an easy way to see if weekend spending is more than on
+weekdays.
+
+@option{--sort EXPR} (@option{-S EXPR}) sorts a report by comparing
+the values determined using the value expression @var{EXPR}. For
+example, using @option{-S -UT} in the balance report will sort account
+balances from greatest to least, using the absolute value of the
+total. For more on how to use value expressions, see @ref{Value
+expressions}.
+
+@option{--wide} (@option{-w}) causes the default @command{register}
+report to assume 132 columns instead of 80.
+
+@option{--head} causes only the first N entries to be printed. This
+is different from using the command-line utility @command{head}, which
+would limit to the first N transactions. @option{--tail} outputs only
+the last N entries. Both options may be used simultaneously. If a
+negative amount is given, it will invert the meaning of the flag
+(instead of the first five entries being printed, for example, it
+would print all but the first five).
+
+@option{--pager} tells Ledger to pass its output to the given pager
+program---very useful when the output is especially long. This
+behavior can be made the default by setting the @env{LEDGER_PAGER}
+environment variable.
+
+@option{--average} (@option{-A}) reports the average transaction
+value.
+
+@option{--deviation} (@option{-D}) reports each transaction's
+deviation from the average. It is only meaningful in the
+@command{register} and @command{prices} reports.
+
+@option{--percentage} (@option{-%}) shows account subtotals in the
+@command{balance} report as percentages of the parent account.
+
+@option{--totals} include running total information in the
+@command{xml} report.
+
+@option{--amount-data} (@option{-j}) changes the @command{register}
+report so that it output nothing but the date and the value column,
+and the latter without commodities. This is only meaningful if the
+report uses a single commodity. This data can then be fed to other
+programs, which could plot the date, analyze it, etc.
+
+@option{--total-data} (@option{-J}) changes the @command{register}
+report so that it output nothing but the date and totals column,
+without commodities.
+
+@option{--display EXPR} (@option{-d EXPR}) limits which transactions
+or accounts or actually displayed in a report. They might still be
+calculated, and be part of the running total of a register report, for
+example, but they will not be displayed. This is useful for seeing
+last month's checking transactions, against a running balance which
+includes all transaction values:
+
+@example
+ledger -d "d>=[last month]" reg checking
+@end example
+
+The output from this command is very different from the following,
+whose running total includes only transactions from the last month
+onward:
+
+@example
+ledger -p "last month" reg checking
+@end example
+
+Which is more useful depends on what you're looking to know: the total
+amount for the reporting range (@option{-p}), or simply a display
+restricted to the reporting range (using @option{-d}).
+
+@option{--date-format STR} (@option{-y STR}) changes the basic date
+format used by reports. The default uses a date like 2004/08/01,
+which represents the default date format of @samp{%Y/%m/%d}. To
+change the way dates are printed in general, the easiest way is to put
+@option{--date-format FORMAT} in the Ledger initialization file
+@file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}).
+
+@option{--format STR} (@option{-F STR}) sets the reporting format for
+whatever report ledger is about to make. @xref{Format strings}.
+There are also specific format commands for each report type:
+
+@itemize
+@item @option{--balance-format STR}
+@item @option{--register-format STR}
+@item @option{--print-format STR}
+@item @option{--plot-amount-format STR} (-j @command{register})
+@item @option{--plot-total-format STR} (-J @command{register})
+@item @option{--equity-format STR}
+@item @option{--prices-format STR}
+@item @option{--wide-register-format STR} (-w @command{register})
+@end itemize
+
+@node Commodity reporting, Environment variables, Output customization, Options
+@subsection Commodity reporting
+
+These options affect how commodity values are displayed:
+
+@option{--price-db FILE} sets the file that is used for recording
+downloaded commodity prices. It is always read on startup, to
+determine historical prices. Other settings can be placed in this
+file manually, to prevent downloading quotes for a specific, for
+example. This is done by adding a line like the following:
+
+@example
+; Don't download quotes for the dollar, or timelog values
+N $
+N h
+@end example
+
+@option{--price-exp MINS} (@option{-L MINS}) sets the expected
+freshness of price quotes, in minutes. That is, if the last known
+quote for any commodity is older than this value---and if
+@option{--download} is being used---then the Internet will be
+consulted again for a newer price. Otherwise, the old price is still
+considered to be fresh enough.
+
+@option{--download} (@option{-Q}) causes quotes to be automagically
+downloaded, as needed, by running a script named @command{getquote}
+and expecting that script to return a value understood by ledger. A
+sample implementation of a @command{getquote} script, implemented in
+Perl, is provided in the distribution. Downloaded quote price are
+then appended to the price database, usually specified using the
+environment variable @env{LEDGER_PRICE_DB}.
+
+There are several different ways that ledger can report the totals it
+displays. The most flexible way to adjust them is by using value
+expressions, and the @option{-t} and @option{-T} options. However,
+there are also several ``default'' reports, which will satisfy most
+users basic reporting needs:
+
+@table @code
+@item -O, --quantity
+Reports commodity totals (this is the default)
+
+@item -B, --basis
+Reports the cost basis for all transactions.
+
+@item -V, --market
+Reports the last known market value for all commodities.
+
+@item -g, --performance
+Reports the net gain/loss for each transaction in a @command{register}
+report.
+
+@item -G --gain
+Reports the net gain/loss for all commodities in the report that have
+a price history.
+@end table
+
+@node Environment variables, , Commodity reporting, Options
+@subsection Environment variables
+
+Every option to ledger may be set using an environment variable. If
+an option has a long name such @option{--this-option}, setting the
+environment variable @env{LEDGER_THIS_OPTION} will have the same
+affect as specifying that option on the command-line. Options on the
+command-line always take precedence over environment variable
+settings, however.
+
+Note that you may also permanently specify option values by placing
+option settings in the file @file{~/.ledgerrc}, for example:
+
+@example
+--cache /tmp/.mycache
+@end example
+
+@node Format strings, Value expressions, Options, Running Ledger
+@section Format strings
+
+Format strings may be used to change the output format of reports.
+They are specified by passing a formatting string to the
+@option{--format} (@option{-F}) option. Within that string,
+constructs are allowed which make it possible to display the various
+parts of an account or transaction in custom ways.
+
+Within a format strings, a substitution is specified using a percent
+character (@samp{%}). The basic format of all substitutions is:
+
+@example
+%[-][MIN WIDTH][.MAX WIDTH]EXPR
+@end example
+
+If the optional minus sign (@samp{-}) follows the percent character,
+whatever is substituted will be left justified. The default is right
+justified. If a minimum width is given next, the substituted text
+will be at least that wide, perhaps wider. If a period and a maximum
+width is given, the substituted text will never be wider than this,
+and will be truncated to fit. Here are some examples:
+
+@example
+%-P An entry's payee, left justified
+%20P The same, right justified, at least 20 chars wide
+%.20P The same, no more than 20 chars wide
+%-.20P Left justified, maximum twenty chars wide
+@end example
+
+The expression following the format constraints can be a single
+letter, or an expression enclosed in parentheses or brackets. The
+allowable expressions are:
+
+@table @code
+@item %
+Inserts a percent sign.
+
+@item t
+Inserts the results of the value expression specified by @option{-t}.
+If @option{-t} was not specified, the current report style's value
+expression is used.
+
+@item T
+Inserts the results of the value expression specified by @option{-T}.
+If @option{-T} was not specified, the current report style's value
+expression is used.
+
+@item |
+Inserts a single space. This is useful if a width is specified, for
+inserting a certain number of spaces.
+
+@item _
+Inserts a space for each level of an account's depth. That is, if an
+account has two parents, this construct will insert two spaces. If a
+minimum width is specified, that much space is inserted for each level
+of depth. Thus @samp{%5_}, for an account with four parents, will
+insert twenty spaces.
+
+@item (EXPR)
+Inserts the amount resulting from the value expression given in
+parentheses. To insert five times the total value of an account, for
+example, one could say @samp{%12(5*O)}. Note: It's important to put
+the five first in that expression, so that the commodity doesn't get
+stripped from the total.
+
+@item [DATEFMT]
+Inserts the result of formatting a transaction's date with a date
+format string, exactly like those supported by @code{strftime}. For
+example: @samp{%[%Y/%m/%d %H:%M:%S]}.
+
+@item S
+Insert the pathname of the file from which the entry's data was read.
+
+@item B
+Inserts the beginning character position of that entry within the file.
+
+@item b
+Inserts the beginning line of that entry within the file.
+
+@item E
+Inserts the ending character position of that entry within the file.
+
+@item e
+Inserts the ending line of that entry within the file.
+
+@item D
+By default, this is the same as @samp{%[%Y/%m%/d]}. The date format
+used can be changed at any time with the @option{-y} flag, however.
+Using @samp{%D} gives the user more control over the way dates are
+output.
+
+@item d
+This is the same as the @samp{%D} option, unless the entry has an
+effective date, in which case it prints
+@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
+
+@item X
+If a transaction has been cleared, this inserts @samp{*} followed by a
+space; otherwise nothing is inserted.
+
+@item Y
+This is the same as @samp{%X}, except that it only displays a state
+character if all of the member transactions have the same state.
+
+@item C
+Inserts the checking number for an entry, in parentheses, followed by
+a space; if none was specified, nothing is inserted.
+
+@item P
+Inserts the payee related to a transaction.
+
+@item a
+Inserts the optimal short name for an account. This is normally used
+in balance reports. It prints a parent account's name if that name
+has not been printed yet, otherwise it just prints the account's name.
+
+@item A
+Inserts the full name of an account.
+
+@item W
+This is the same as @samp{%A}, except that it first displays the
+transaction's state @emph{if the entry's transaction states are not
+all the same}, followed by the full account name. This is offered as
+a printing optimization, so that combined with @samp{%Y}, only the
+minimum amount of state detail is printed.
+
+@item o
+Inserts the ``optimized'' form of a transaction's amount. This is
+used by the print report. In some cases, this inserts nothing; in
+others, it inserts the transaction amount and its cost. It's use is
+not recommend unless you are modifying the print report.
+
+@item n
+Inserts the note associated with a transaction, preceded by two spaces
+and a semi-colon, if it exists. Thus, no none becomes an empty
+string, while the note @samp{foo} is substituted as @samp{ ; foo}.
+
+@item N
+Inserts the note associated with a transaction, if one exists.
+
+@item /
+The @samp{%/} construct is special. It separates a format string
+between what is printed for the first transaction of an entry, and
+what is printed for all subsequent transactions. If not used, the
+same format string is used for all transactions.
+@end table
+
+@node Value expressions, Period expressions, Format strings, Running Ledger
+@section Value expressions
+
+Value expressions are an expression language used by Ledger to
+calculate values used by the program for many different purposes:
+
+@enumerate
+@item
+The values displayed in reports
+@item
+For predicates (where truth is anything non-zero), to determine which
+transactions are calculated (@option{-l}) or displayed (@option{-d}).
+@item
+For sorting criteria, to yield the sort key.
+@item
+In the matching criteria used by automated transactions.
+@end enumerate
+
+Value expressions support most simple math and logic operators, in
+addition to a set of one letter functions and variables. A function's
+argument is whatever follows it. The following is a display predicate
+that I use with the @command{balance} command:
+
+@example
+ledger -d /^Liabilities/?T<0:UT>100 balance
+@end example
+
+The effect is that account totals are displayed only if: 1) A
+Liabilities account has a total less than zero; or 2) the absolute
+value of the account's total exceeds 100 units of whatever commodity
+contains. If it contains multiple commodities, only one of them must
+exceed 100 units.
+
+Display predicates are also very handy with register reports, to
+constrain which entries are printed. For example, the following
+command shows only entries from the beginning of the current month,
+while still calculating the running balance based on all entries:
+
+@example
+ledger -d "d>[this month]" register checking
+@end example
+
+This advantage to this command's complexity is that it prints the
+running total in terms of all entries in the register. The following,
+simpler command is similar, but totals only the displayed
+transactions:
+
+@example
+ledger -b "this month" register checking
+@end example
+
+@subsection Variables
+
+Below are the one letter variables available in any value expression.
+For the register and print commands, these variables relate to
+individual transactions, and sometimes the account affected by a
+transaction. For the balance command, these variables relate to
+accounts---often with a subtle difference in meaning. The use of each
+variable for both is specified.
+
+@table @code
+@item t
+This maps to whatever the user specified with @option{-t}. In a
+register report, @option{-t} changes the value column; in a balance
+report, it has no meaning by default. If @option{-t} was not
+specified, the current report style's value expression is used.
+
+@item T
+This maps to whatever the user specified with @option{-T}. In a
+register report, @option{-T} changes the totals column; in a balance
+report, this is the value given for each account. If @option{-T} was
+not specified, the current report style's value expression is used.
+
+@item m
+This is always the present moment/date.
+@end table
+
+@subsubsection Transaction/account details
+
+@table @code
+@item d
+A transaction's date, as the number of seconds past the epoch. This
+is always ``today'' for an account.
+
+@item a
+The transaction's amount; the balance of an account, without
+considering children.
+
+@item b
+The cost of a transaction; the cost of an account, without its
+children.
+
+@item v
+The market value of a transaction, or an account without its children.
+
+@item g
+The net gain (market value minus cost basis), for a transaction or an
+account without its children. It is the same as @samp{v-b}.
+
+@item l
+The depth (``level'') of an account. If an account has one parent,
+it's depth is one.
+
+@item n
+The index of a transaction, or the count of transactions affecting an
+account.
+
+@item X
+1 if a transaction's entry has been cleared, 0 otherwise.
+
+@item R
+1 if a transaction is not virtual, 0 otherwise.
+
+@item Z
+1 if a transaction is not automated, 0 otherwise.
+@end table
+
+@subsubsection Calculated totals
+
+@table @code
+@item O
+The total of all transactions seen so far, or the total of an account
+and all its children.
+
+@item N
+The total count of transactions affecting an account and all its
+children.
+
+@item B
+The total cost of all transactions seen so far; the total cost of an
+account and all its children.
+
+@item V
+The market value of all transactions seen so far, or of an account and
+all its children.
+
+@item G
+The total net gain (market value minus cost basis), for a series of
+transactions, or an account and its children. It is the same as
+@samp{V-B}.
+@end table
+
+@subsection Functions
+
+The available one letter functions are:
+
+@table @code
+@item -
+Negates the argument.
+
+@item U
+The absolute (unsigned) value of the argument.
+
+@item S
+Strips the commodity from the argument.
+
+@item A
+The arithmetic mean of the argument; @samp{Ax} is the same as
+@samp{x/n}.
+
+@item P
+The present market value of the argument. The syntax @samp{P(x,d)} is
+supported, which yields the market value at time @samp{d}. If no date
+is given, then the current moment is used.
+@end table
+
+@subsection Operators
+
+The binary and ternary operators, in order of precedence, are:
+
+@enumerate
+@item @samp{* /}
+@item @samp{+ -}
+@item @samp{! < > =}
+@item @samp{& | ?:}
+@end enumerate
+
+@subsection Complex expressions
+
+More complicated expressions are possible using:
+
+@table @code
+@item NUM
+A plain integer represents a commodity-less amount.
+
+@item @{AMOUNT@}
+An amount in braces can be any kind of amount supported by ledger,
+with or without a commodity. Use this for decimal values.
+
+@item /REGEXP/
+@item W/REGEXP/
+A regular expression that matches against an account's full name. If
+a transaction, this will match against the account affected by the
+transaction.
+
+@item //REGEXP/
+@item p/REGEXP/
+A regular expression that matches against an entry's payee name.
+
+@item ///REGEXP/
+@item w/REGEXP/
+A regular expression that matches against an account's base name. If
+a transaction, this will match against the account affected by the
+transaction.
+
+@item c/REGEXP/
+A regular expression that matches against the entry code (the text
+that occurs between parentheses before the payee name).
+
+@item e/REGEXP/
+A regular expression that matches against a transaction's note, or
+comment field.
+
+@item (EXPR)
+A sub-expression is nested in parenthesis. This can be useful passing
+more complicated arguments to functions, or for overriding the natural
+precedence order of operators.
+
+@item [DATE]
+Useful specifying a date in plain terms. For example, you could say
+@samp{[2004/06/01]}.
+@end table
+
+@node Period expressions, File format, Value expressions, Running Ledger
+@section Period expressions
+
+A period expression indicates a span of time, or a reporting interval,
+or both. The full syntax is:
+
+@example
+[INTERVAL] [BEGIN] [END]
+@end example
+
+The optional @var{INTERVAL} part may be any one of:
+
+@example
+every day
+every week
+every monthly
+every quarter
+every year
+every N days # N is any integer
+every N weeks
+every N months
+every N quarters
+every N years
+daily
+weekly
+biweekly
+monthly
+bimonthly
+quarterly
+yearly
+@end example
+
+After the interval, a begin time, end time, both or neither may be
+specified. As for the begin time, it can be either of:
+
+@example
+from <SPEC>
+since <SPEC>
+@end example
+
+The end time can be either of:
+
+@example
+to <SPEC>
+until <SPEC>
+@end example
+
+Where @var{SPEC} can be any of:
+
+@example
+2004
+2004/10
+2004/10/1
+10/1
+october
+oct
+this week # or day, month, quarter, year
+next week
+last week
+@end example
+
+The beginning and ending can be given at the same time, if it spans a
+single period. In that case, just use @var{SPEC} by itself. In that
+case, the period @samp{oct}, for example, will cover all the days in
+october. The possible forms are:
+
+@example
+<SPEC>
+in <SPEC>
+@end example
+
+Here are a few examples of period expressions:
+
+@example
+monthly
+monthly in 2004
+weekly from oct
+weekly from last month
+from sep to oct
+from 10/1 to 10/5
+monthly until 2005
+from apr
+until nov
+last oct
+weekly last august
+@end example
+
+@node File format, Some typical queries, Period expressions, Running Ledger
+@section File format
+
+The ledger file format is quite simple, but also very flexible. It
+supports many options, though typically the user can ignore most of
+them. They are summarized below.
+
+The initial character of each line determines what the line means, and
+how it should be interpreted. Allowable initial characters are:
+
+@table @code
+@item NUMBER
+A line beginning with a number denotes an entry. It may be followed
+by any number of lines, each beginning with whitespace, to denote the
+entry's account transactions. The format of the first line is:
+
+@example
+DATE[=EDATE] [*|!] [(CODE)] DESC
+@end example
+
+If @samp{*} appears after the date (with optional effective date), it
+indicates the entry is ``cleared'', which can mean whatever the user
+wants it t omean. If @samp{!} appears after the date, it indicates d
+the entry is ``pending''; i.e., tentatively cleared from the user's
+point of view, but not yet actually cleared. If a @samp{CODE} appears
+in parentheses, it may be used to indicate a check number, or the type
+of the transaction. Following these is the payee, or a description of
+the transaction.
+
+The format of each following transaction is:
+
+@example
+ ACCOUNT AMOUNT [; NOTE]
+@end example
+
+The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
+transactions, or square brackets if it is a virtual transactions that
+must balance. The @samp{AMOUNT} can be followed by a per-unit
+transaction cost, by specifying @samp{@@ AMOUNT}, or a complete
+transaction cost with @samp{@@@@ AMOUNT}. Lastly, the @samp{NOTE} may
+specify an actual and/or effective date for the transaction by using
+the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
+@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
+
+@item =
+An automated entry. A value expression must appear after the equal
+sign.
+
+After this initial line there should be a set of one or more
+transactions, just as if it were normal entry. If the amounts of the
+transactions have no commodity, they will be applied as modifiers to
+whichever real transaction is matched by the value expression.
+
+@item ~
+A period entry. A period expression must appear after the tilde.
+
+After this initial line there should be a set of one or more
+transactions, just as if it were normal entry.
+
+@item !
+A line beginning with an exclamation mark denotes a command directive.
+It must be immediately followed by the command word. The supported
+commands are:
+
+@table @samp
+@item !include
+Include the stated ledger file.
+
+@item !account
+The account name is given is taken to be the parent of all
+transactions that follow, until @samp{!end} is seen.
+
+@item !end
+Ends an account block.
+@end table
+
+@item ;
+A line beginning with a colon indicates a comment, and is ignored.
+
+@item Y
+If a line begins with a capital Y, it denotes the year used for all
+subsequent entries that give a date without a year. The year should
+appear immediately after the Y, for example: @samp{Y2004}. This is
+useful at the beginning of a file, to specify the year for that file.
+If all entries specify a year, however, this command has no effect.
+
+@item P
+Specifies a historical price for a commodity. These are usually found
+in a pricing history file (see the @option{-Q} option). The syntax
+is:
+@example
+P DATE SYMBOL PRICE
+@end example
+
+@item N SYMBOL
+Indicates that pricing information is to be ignored for a given
+symbol, nor will quotes ever be downloaded for that symbol. Useful
+with a home currency, such as the dollar ($). It is recommended that
+these pricing options be set in the price database file, which
+defaults to @file{~/.pricedb}. The syntax for this command is:
+@example
+N SYMBOL
+@end example
+
+@item D AMOUNT
+Specifies the default commodity to use, by specifying an amount in the
+expected format. The @command{entry} command will use this commodity
+as the default when none other can be determined. This command may be
+used multiple times, to set the default flags for different
+commodities; whichever is seen last is used as the default commodity.
+For example, to set US dollars as the default commodity, while also
+setting the thousands flag and decimal flag for that commodity, use:
+@example
+D $1,000.00
+@end example
+
+@item C AMOUNT1 = AMOUNT2
+Specifies a commodity conversion, where the first amount is given to
+be equivalent to the second amount. The first amount should use the
+decimal precision desired during reporting:
+@example
+C 1.00 Kb = 1024 bytes
+@end example
+
+@item i, o, b, h
+These four relate to timeclock support, which permits ledger to read
+timelog files. See the timeclock's documentation for more info on the
+syntax of its timelog files.
+@end table
+
+@node Some typical queries, Budgeting and forecasting, File format, Running Ledger
+@section Some typical queries
+
+A query such as the following shows all expenses since last
+October, sorted by total:
+
+@example
+ledger -b "last oct" -s -S T bal ^expenses
+@end example
+
+From left to right the options mean: Show entries since October, 2003;
+show all sub-accounts; sort by the absolute value of the total; and
+report the balance for all expenses.
+
+@subsection Reporting monthly expenses
+
+The following query makes it easy to see monthly expenses, with each
+month's expenses sorted by the amount:
+
+@example
+ledger -M --period-sort t reg ^expenses
+@end example
+
+Now, you might wonder where the money came from to pay for these
+things. To see that report, add @option{-r}, which shows the
+``related account'' transactions:
+
+@example
+ledger -M --period-sort t -r reg ^expenses
+@end example
+
+But maybe this prints too much information. You might just want to
+see how much you're spending with your MasterCard. That kind of query
+requires the use of a display predicate, since the transactions
+calculated must match @samp{^expenses}, while the transactions
+displayed must match @samp{mastercard}. The command would be:
+
+@example
+ledger -M -r -d /mastercard/ reg ^expenses
+@end example
+
+This query says: Report monthly subtotals; report the ``related
+account'' transactions; display only related transactions whose
+account matches @samp{mastercard}, and base the calculation on
+transactions matching @samp{^expenses}.
+
+This works just as well for report the overall total, too:
+
+@example
+ledger -s -r -d /mastercard/ reg ^expenses
+@end example
+
+The @option{-s} option subtotals all transactions, just as @option{-M}
+subtotaled by the month. The running total in both cases is off,
+however, since a display expression is being used.
+
+@subsection Visualizing with Gnuplot
+
+If you have @command{Gnuplot} installed, you can graph any of the
+above register reports. The script to do this is included in the
+ledger distribution, and is named @file{scripts/report}. Install
+@file{report} anywhere along your @env{PATH}, and then use
+@command{report} instead of @command{ledger} when doing a register
+report. The only thing to keep in mind is that you must specify
+@option{-j} or @option{-J} to indicate whether Gnuplot should plot the
+amount, or the running total. For example, this command plots total
+monthly expenses made on your MasterCard.
+
+@example
+report -j -M -r -d /mastercard/ reg ^expenses
+@end example
+
+The @command{report} script is a very simple Bourne shell script, that
+passes a set of scripted commands to Gnuplot. Feel free to modify the
+script to your liking, since you may prefer histograms to line plots,
+for example.
+
+@subsubsection Typical plots
+
+Here are some useful plots:
+
+@smallexample
+report -j -M reg ^expenses # monthly expenses
+report -J reg checking # checking account balance
+report -J reg ^income ^expenses # cash flow report
+
+# net worth report, ignoring non-$ transactions
+
+report -J -l "Ua>=@{\$0.01@}" reg ^assets ^liab
+
+# net worth report starting last February. the use of a display
+# predicate (-d) is needed, otherwise the balance will start at
+# zero, and thus the y-axis will not reflect the true balance
+
+report -J -l "Ua>=@{\$0.01@}" -d "d>=[last feb]" reg ^assets ^liab
+@end smallexample
+
+The last report uses both a calculation predicate (@option{-l}) and a
+display predicate (@option{-d}). The calculation predicates limits
+the report to transactions whose amount is greater than $1 (which can
+only happen if the transaction amount is in dollars). The display
+predicate limits the entries @emph{displayed} to just those since last
+February, even those entries from before then will be computed as part
+of the balance.
+
+@node Budgeting and forecasting, , Some typical queries, Running Ledger
+@section Budgeting and forecasting
+
+@subsection Budgeting
+
+Keeping a budget allows you to pay closer attention to your income and
+expenses, by reporting how far your actual financial activity is from
+your expectations.
+
+To start keeping a budget, put some period entries at the top of your
+ledger file. A period entry is almost identical to a regular entry,
+except that it begins with a tilde and has a period expression in
+place of a payee. For example:
+
+@smallexample
+~ Monthly
+ Expenses:Rent $500.00
+ Expenses:Food $450.00
+ Expenses:Auto:Gas $120.00
+ Expenses:Insurance $150.00
+ Expenses:Phone $125.00
+ Expenses:Utilities $100.00
+ Expenses:Movies $50.00
+ Expenses $200.00 ; all other expenses
+ Assets
+
+~ Yearly
+ Expenses:Auto:Repair $500.00
+ Assets
+@end smallexample
+
+These two period entries give the usual monthly expenses, as well as
+one typical yearly expense. For help on finding out what your average
+monthly expense is for any category, use a command like:
+
+@example
+ledger -p "this year" -MAs bal ^expenses
+@end example
+
+The reported totals are the current year's average for each account.
+
+Once these period entries are defined, creating a budget report is as
+easy as adding @option{--budget} to the command-line. For example, a
+typical monthly expense report would be:
+
+@example
+ledger -M reg ^exp
+@end example
+
+To see the same report balanced against your budget, use:
+
+@example
+ledger --budget -M reg ^exp
+@end example
+
+A budget report includes only those accounts that appear in the
+budget. To see all expenses balanced against the budget, use
+@option{--add-budget}. You can even see only the unbudgeted expenses
+using @option{--unbudgeted}:
+
+@example
+ledger --unbudgeted -M reg ^exp
+@end example
+
+You can also use these flags with the @command{balance} command.
+
+@subsection Forecasting
+
+Sometimes it's useful to know what your finances will look like in the
+future, such as determining when an account will reach zero. Ledger
+makes this easy to do, using the same period entries as are used for
+budgeting. An example forecast report can be generated with:
+
+@example
+ledger --forecast "T>@{\$-500.00@}" register ^assets ^liabilities
+@end example
+
+This report continues outputting transactions until the running total
+is greater than $-500.00. A final transaction is always output, to
+show you what the total afterwards would be.
+
+Forecasting can also be used with the balance report, but by date
+only, and not against the running total:
+
+@example
+ledger --forecast "d<[2010]" bal ^assets ^liabilities
+@end example
+
+@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
+you have a good ledger, tools can be written to work whatever
+mathematically tricks you need to better understand your spending
+patterns. Without a good ledger, no tool, however smart, can help
+you.
+
+The Ledger program aims at making ledger entry as simple as possible.
+Since it is a command-line tool, it does not provide a user interface
+for keeping a ledger. If you like, you may use GnuCash to maintain
+your ledger, in which case the Ledger program will read GnuCash's data
+files directly. In that case, read the GnuCash manual now, and skip
+to the next chapter.
+
+If you are not using GnuCash, but a text editor to maintain your
+ledger, read on. Ledger has been designed to make data entry as
+simple as possible, by keeping the ledger format easy, and also by
+automagically determining as much information as possible based on the
+nature of your entries.
+
+For example, you do not need to tell Ledger about the accounts you
+use. Any time Ledger sees a transaction involving an account it knows
+nothing about, it will create it. If you use a commodity that is new
+to Ledger, it will create that commodity, and determine its display
+characteristics (placement of the symbol before or after the amount,
+display precision, etc) based on how you used the commodity in the
+transaction.
+
+Here is the Pacific Bell example from above, given as a Ledger
+transaction:
+
+@smallexample
+9/29 (100) Pacific Bell
+ Expenses:Utilities:Phone $23.00
+ Assets:Checking $-23.00
+@end smallexample
+
+As you can see, it is very similar to what would be written on paper,
+minus the computed balance totals, and adding in account names that
+work better with Ledger's scheme of things. In fact, since Ledger is
+smart about many things, you don't need to specify the balanced
+amount, if it is the same as the first line:
+
+@smallexample
+9/29 (100) Pacific Bell
+ Expenses:Utilities:Phone $23.00
+ Assets:Checking
+@end smallexample
+
+For this entry, Ledger will figure out that $-23.00 must come from
+@samp{Assets:Checking} in order to balance the entry.
+
+@menu
+* Stating where money goes::
+* Assets and Liabilities::
+* Commodities and Currencies::
+* Accounts and Inventories::
+* Understanding Equity::
+* Dealing with Petty Cash::
+* Working with multiple funds and accounts::
+* Archiving previous years::
+* Virtual transactions::
+* Automated transactions::
+* Using Emacs to Keep Your Ledger::
+* Using GnuCash to Keep Your Ledger::
+* Using timeclock to record billable time::
+@end menu
+
+@node Stating where money goes, Assets and Liabilities, Keeping a ledger, Keeping a ledger
+@section Stating where money goes
+
+Accountants will talk of ``credits'' and ``debits'', but the meaning
+is often different from the layman's understanding. To avoid
+confusion, Ledger uses only subtractions and additions, although the
+underlying intent is the same as standard accounting principles.
+
+Recall that every transaction will involve two or more accounts.
+Money is transferred from one or more accounts to one or more other
+accounts. To record the transaction, an amount is @emph{subtracted}
+from the source accounts, and @emph{added} to the target accounts.
+
+In order to write a Ledger entry correctly, you must determine where
+the money comes from and where it goes to. For example, when you are
+paid a salary, you must add money to your bank account and also
+subtract it from an income account:
+
+@smallexample
+9/29 My Employer
+ Assets:Checking $500.00
+ Income:Salary $-500.00
+@end smallexample
+
+Why is the Income a negative figure? When you look at the balance
+totals for your ledger, you may be surprised to see that Expenses are
+a positive figure, and Income is a negative figure. It may take some
+getting used to, but to properly use a general ledger you must think
+in terms of how money moves. Rather than Ledger ``fixing'' the minus
+signs, let's understand why they are there.
+
+When you earn money, the money has to come from somewhere. Let's call
+that somewhere ``society''. In order for society to give you an
+income, you must take money away (withdraw) from society in order to
+put it into (make a payment to) your bank. When you then spend that
+money, it leaves your bank account (a withdrawal) and goes back to
+society (a payment). This is why Income will appear negative---it
+reflects the money you have drawn from society---and why Expenses will
+be positive---it is the amount you've given back. These additions and
+subtractions will always cancel each other out in the end, because you
+don't have the ability to create new money: it must always come from
+somewhere, and in the end must always leave. This is the beginning of
+economy, after which the explanation gets terribly difficult.
+
+Based on that explanation, here's another way to look at your balance
+report: every negative figure means that that account or person or
+place has less money now than when you started your ledger; and every
+positive figure means that that account or person or place has more
+money now that when you started your ledger. Make sense?
+
+@node Assets and Liabilities, Commodities and Currencies, Stating where money goes, Keeping a ledger
+@section Assets and Liabilities
+
+Assets are money that you have, and Liabilities are money that you
+owe. ``Liabilities'' is just a more inclusive name for Debts.
+
+An Asset is typically increased by transferring money from an Income
+account, such as when you get paid. Here is a typical entry:
+
+@smallexample
+2004/09/29 My Employer
+ Assets:Checking $500.00
+ Income:Salary
+@end smallexample
+
+Money, here, comes from an Income account belonging to ``My
+Employer'', and is transferred to your checking account. The money is
+now yours, which makes it an Asset.
+
+Liabilities track money owed to others. This can happen when you
+borrow money to buy something, or if you owe someone money. Here is
+an example of increasing a MasterCard liability by spending money with
+it:
+
+@smallexample
+2004/09/30 Restaurant
+ Expenses:Dining $25.00
+ Liabilities:MasterCard
+@end smallexample
+
+The Dining account balance now shows $25 spent on Dining, and a
+corresponding $25 owed on the MasterCard---and therefore shown as
+$-25.00. The MasterCard liability shows up as negative because it
+offsets the value of your assets.
+
+The combined total of your Assets and Liabilities is your net worth.
+So to see your current net worth, use this command:
+
+@example
+ledger balance ^assets ^liabilities
+@end example
+
+Relatedly, your Income accounts show up negative, because they
+transfer money @emph{from} an account in order to increase your
+assets. Your Expenses show up positive because that is where the
+money went to. The combined total of Income and Expenses is your cash
+flow. A positive cash flow means you are spending more than you make,
+since income is always a negative figure. To see your current cash
+flow, use this command:
+
+@example
+ledger balance ^income ^expenses
+@end example
+
+Another common question to ask of your expenses is: How much do I
+spend each month on X? Ledger provides a simple way of displaying
+monthly totals for any account. Here is an example that summarizes
+your monthly automobile expenses:
+
+@example
+ledger -M register expenses:auto
+@end example
+
+This assumes, of course, that you use account names like
+@samp{Expenses:Auto:Gas} and @samp{Expenses:Auto:Repair}.
+
+@subsection Tracking reimbursable expenses
+
+Sometimes you will want to spend money on behalf of someone else,
+which will eventually get repaid. Since the money is still ``yours'',
+it is really an asset. And since the expenditure was for someone
+else, you don't want it contaminating your Expenses reports. You will
+need to keep an account for tracking reimbursements.
+
+This is fairly easy to do in ledger. When spending the money, spend
+it @emph{to} your Assets:Reimbursements, using a different account for
+each person or business that you spend money for. For example:
+
+@smallexample
+2004/09/29 Circuit City
+ Assets:Reimbursements:Company XYZ $100.00
+ Liabilities:MasterCard
+@end smallexample
+
+This shows $100.00 spent on a MasterCard at Circuit City, with the
+expense was made on behalf of Company XYZ. Later, when Company XYZ
+pays the amount back, the money will transfer from that reimbursement
+account back to a regular asset account:
+
+@smallexample
+2004/09/29 Company XYZ
+ Assets:Checking $100.00
+ Assets:Reimbursements:Company XYZ
+@end smallexample
+
+This deposits the money owed from Company XYZ into a checking account,
+presumably because they paid the amount back with a check.
+
+But what to do if you run your own business, and you want to keep
+track of expenses made on your own behalf, while still tracking
+everything in a single ledger file? This is more complex, because you
+need to track two separate things: 1) The fact that the money should
+be reimbursed to you, and 2) What the expense account was, so that you
+can later determine where your company is spending its money.
+
+This kind of transaction is best handled with mirrored transactions in
+two different files, one for your personal accounts, and one for your
+company accounts. But keeping them in one file involves the same
+kinds of transactions, so those are what is shown here. First, the
+personal entry, which shows the need for reimbursement:
+
+@smallexample
+2004/09/29 Circuit City
+ Assets:Reimbursements:Company XYZ $100.00
+ Liabilities:MasterCard
+@end smallexample
+
+This is the same as above, except that you own Company XYZ, and are
+keeping track of its expenses in the same ledger file. This entry
+should be immediately followed by an equivalent entry, which shows the
+kind of expense, and also notes the fact that $100.00 is now payable
+to you:
+
+@smallexample
+2004/09/29 Circuit City
+ Company XYZ:Expenses:Computer:Software $100.00
+ Company XYZ:Accounts Payable:Your Name
+@end smallexample
+
+This second entry shows that Company XYZ has just spent $100.00 on
+software, and that this $100.00 came from Your Name, which must be
+paid back.
+
+These two entries can also be merged, to make things a little clearer.
+Note that all amounts must be specified now:
+
+@smallexample
+2004/09/29 Circuit City
+ Assets:Reimbursements:Company XYZ $100.00
+ Liabilities:MasterCard $-100.00
+ Company XYZ:Expenses:Computer:Software $100.00
+ Company XYZ:Accounts Payable:Your Name $-100.00
+@end smallexample
+
+To ``pay back'' the reimbursement, just reverse the order of
+everything, except this time drawing the money from a company asset,
+paying it to accounts payable, and then drawing it again from the
+reimbursement account, and paying it to your personal asset account.
+It's easier shown than said:
+
+@smallexample
+2004/10/15 Company XYZ
+ Assets:Checking $100.00
+ Assets:Reimbursements:Company XYZ $-100.00
+ Company XYZ:Accounts Payable:Your Name $100.00
+ Company XYZ:Assets:Checking $-100.00
+@end smallexample
+
+And now the reimbursements account is paid off, accounts payable is
+paid off, and $100.00 has been effectively transferred from the
+company's checking account to your personal checking account. The
+money simply ``waited''---in both @samp{Assets:Reimbursements:Company
+XYZ}, and @samp{Company XYZ:Accounts Payable:Your Name}---until such
+time as it could be paid off.
+
+The value of tracking expenses from both sides like that is that you
+do not contaminate your personal expense report with expenses made on
+behalf of others, while at the same time making it possible to
+generate accurate reports of your company's expenditures. It is more
+verbose than just paying for things with your personal assets, but it
+gives you a very accurate information trail.
+
+The advantage to keep these doubled entries together is that they
+always stay in sync. The advantage to keeping them apart is that it
+clarifies the transfer's point of view. To keep the transactions in
+separate files, just separate the two entries that were joined above.
+For example, for both the expense and the pay-back shown above, the
+following four entries would be created. Two in your personal ledger
+file:
+
+@smallexample
+2004/09/29 Circuit City
+ Assets:Reimbursements:Company XYZ $100.00
+ Liabilities:MasterCard $-100.00
+
+2004/10/15 Company XYZ
+ Assets:Checking $100.00
+ Assets:Reimbursements:Company XYZ $-100.00
+@end smallexample
+
+And two in your company ledger file:
+
+@smallexample
+!account Company XYZ
+
+2004/09/29 Circuit City
+ Expenses:Computer:Software $100.00
+ Accounts Payable:Your Name $-100.00
+
+2004/10/15 Company XYZ
+ Accounts Payable:Your Name $100.00
+ Assets:Checking $-100.00
+
+!end
+@end smallexample
+
+(Note: The @samp{!account} above means that all accounts mentioned in
+the file are children of that account. In this case it means that all
+activity in the file relates to Company XYZ).
+
+After creating these entries, you will always know that $100.00 was
+spent using your MasterCard on behalf of Company XYZ, and that Company
+XYZ spent the money on computer software and paid it back about two
+weeks later.
+
+@node Commodities and Currencies, Accounts and Inventories, Assets and Liabilities, Keeping a ledger
+@section Commodities and Currencies
+
+Ledger makes no assumptions about the commodities you use; it only
+requires that you specify a commodity. The commodity may be any
+non-numeric string that does not contain a period, comma, forward
+slash or at-sign. It may appear before or after the amount, although
+it is assumed that symbols appearing before the amount refer to
+currencies, while non-joined symbols appearing after the amount refer
+to commodities. Here are some valid currency and commodity
+specifiers:
+
+@example
+$20.00 ; currency: twenty US dollars
+40 AAPL ; commodity: 40 shares of Apple stock
+60 DM ; currency: 60 Deutsch Mark
+£50 ; currency: 50 British pounds
+50 EUR ; currency: 50 Euros (or use appropriate symbol)
+@end example
+
+Ledger will examine the first use of any commodity to determine how
+that commodity should be printed on reports. It pays attention to
+whether the name of commodity was separated from the amount, whether
+it came before or after, the precision used in specifying the amount,
+whether thousand marks were used, etc. This is done so that printing
+the commodity looks the same as the way you use it.
+
+An account may contain multiple commodities, in which case it will
+have separate totals for each. For example, if your brokerage account
+contains both cash, gold, and several stock quantities, the balance
+might look like:
+
+@smallexample
+ $200.00
+100.00 AU
+ AAPL 40
+ BORL 100
+ FEQTX 50 Assets:Brokerage
+@end smallexample
+
+This balance report shows how much of each commodity is in your
+brokerage account.
+
+Sometimes, you will want to know the current street value of your
+balance, and not the commodity totals. For this to happen, you must
+specify what the current price is for each commodity. The price can
+be any commodity, in which case the balance will be computed in terms
+of that commodity. The usual way to specify prices is with a price
+history file, which might look like this:
+
+@smallexample
+P 2004/06/21 02:18:01 FEQTX $22.49
+P 2004/06/21 02:18:01 BORL $6.20
+P 2004/06/21 02:18:02 AAPL $32.91
+P 2004/06/21 02:18:02 AU $400.00
+@end smallexample
+
+Specify the price history to use with the @option{--price-db} option,
+with the @option{-V} option to report in terms of current market
+value:
+
+@example
+ledger --price-db prices.db -V balance brokerage
+@end example
+
+The balance for your brokerage account will be reported in US dollars,
+since the prices database uses that currency.
+
+@smallexample
+$40880.00 Assets:Brokerage
+@end smallexample
+
+You can convert from any commodity to any other commodity. Let's say
+you had $5000 in your checking account, and for whatever reason you
+wanted to know many ounces of gold that would buy, in terms of the
+current price of gold:
+
+@example
+ledger -T "@{1 AU@}*(O/P@{1 AU@})" balance checking
+@end example
+
+Although the total expression appears complex, it is simply saying
+that the reported total should be in multiples of AU units, where the
+quantity is the account total divided by the price of one AU. Without
+the initial multiplication, the reported total would still use the
+dollars commodity, since multiplying or dividing amounts always keeps
+the left value's commodity. The result of this command might be:
+
+@smallexample
+14.01 AU Assets:Checking
+@end smallexample
+
+@subsection Commodity price histories
+
+Whenever a commodity is purchased using a different commodity (such as
+a share of common stock using dollars), it establishes a price for
+that commodity on that day. It is also possible, by recording price
+details in a ledger file, to specify other prices for commodities at
+any given time. Such price entries might look like those below:
+
+@smallexample
+P 2004/06/21 02:17:58 TWCUX $27.76
+P 2004/06/21 02:17:59 AGTHX $25.41
+P 2004/06/21 02:18:00 OPTFX $39.31
+P 2004/06/21 02:18:01 FEQTX $22.49
+P 2004/06/21 02:18:02 AAPL $32.91
+@end smallexample
+
+By default, ledger will not consider commodity prices when generating
+its various reports. It will always report balances in terms of the
+commodity total, rather than the current value of those commodities.
+To enable pricing reports, use one of the commodity reporting options.
+
+@subsection Commodity equivalencies
+
+Sometimes a commodity has several forms which are all equivalent. An
+example of this is time. Whether tracked in terms of minutes, hours
+or days, it should be possible to convert between the various forms.
+Doing this requires the use of commodity equivalencies.
+
+For example, you might have the following two transactions, one which
+transfers an hour of time into a @samp{Billable} account, and another
+which decreases the same account by ten minutes. The resulting report
+will indicate that fifty minutes remain:
+
+@smallexample
+2005/10/01 Work done for company
+ Billable:Client 1h
+ Project:XYZ
+
+2005/10/02 Return ten minutes to the project
+ Project:XYZ 10m
+ Billable:Client
+@end smallexample
+
+Reporting the balance for this ledger file produces:
+
+@smallexample
+ 50.0m Billable:Client
+ -50.0m Project:XYZ
+@end smallexample
+
+This example works because ledger already knows how to handle seconds,
+minutes and hours, as part of its time tracking support. Defining
+other equivalencies is simple. The following is an example that
+creates data equivalencies, helpful for tracking bytes, kilobytes,
+megabytes, and more:
+
+@smallexample
+C 1.00 Kb = 1024 b
+C 1.00 Mb = 1024 Kb
+C 1.00 Gb = 1024 Mb
+C 1.00 Tb = 1024 Gb
+@end smallexample
+
+Each of these definitions correlates a commodity (such as @samp{Kb})
+and a default precision, with a certain quantity of another commodity.
+In the above example, kilobytes are reporetd with two decimal places
+of precision and each kilobyte is equal to 1024 bytes.
+
+Equivalency chains can be as long as desired. Whenever a commodity
+would report as a decimal amount (less than @samp{1.00}), the next
+smallest commodity is used. If a commodity could be reported in terms
+of a higher commodity without resulting to a partial fraction, then
+the larger commodity is used.
+
+@node Accounts and Inventories, Understanding Equity, Commodities and Currencies, Keeping a ledger
+@section Accounts and Inventories
+
+Since Ledger's accounts and commodity system is so flexible, you can
+have accounts that don't really exist, and use commodities that no one
+else recognizes. For example, let's say you are buying and selling
+various items in EverQuest, and want to keep track of them using a
+ledger. Just add items of whatever quantity you wish into your
+EverQuest account:
+
+@smallexample
+9/29 Get some stuff at the Inn
+ Places:Black's Tavern -3 Apples
+ Places:Black's Tavern -5 Steaks
+ EverQuest:Inventory
+@end smallexample
+
+Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The
+amounts are negative, because you are taking @emph{from} Black's
+Tavern in order to add to your Inventory account. Note that you don't
+have to use @samp{Places:Black's Tavern} as the source account. You
+could use @samp{EverQuest:System} to represent the fact that you
+acquired them online. The only purpose for choosing one kind of
+source account over another is for generate more informative reports
+later on. The more you know, the better analysis you can perform.
+
+If you later sell some of these items to another player, the entry
+would look like:
+
+@smallexample
+10/2 Sturm Brightblade
+ EverQuest:Inventory -2 Steaks
+ EverQuest:Inventory 15 Gold
+@end smallexample
+
+Now you've turned 2 steaks into 15 gold, courtesy of your customer,
+Sturm Brightblade.
+
+@node Understanding Equity, Dealing with Petty Cash, Accounts and Inventories, Keeping a ledger
+@section Understanding Equity
+
+The most confusing entry in any ledger will be your equity account---
+because starting balances can't come out of nowhere.
+
+When you first start your ledger, you will likely already have money
+in some of your accounts. Let's say there's $100 in your checking
+account; then add an entry to your ledger to reflect this amount.
+Where will money come from? The answer: your equity.
+
+@smallexample
+10/2 Opening Balance
+ Assets:Checking $100.00
+ Equity:Opening Balances
+@end smallexample
+
+But what is equity? You may have heard of equity when people talked
+about house mortgages, as ``the part of the house that you own''.
+Basically, equity is like the value of something. If you own a car
+worth $5000, then you have $5000 in equity in that car. In order to
+turn that car (a commodity) into a cash flow, or a credit to your bank
+account, you will have to debit the equity by selling it.
+
+When you start a ledger, you are probably already worth something.
+Your net worth is your current equity. By transferring the money in
+the ledger from your equity to your bank accounts, you are crediting
+the ledger account based on your prior equity. That is why, when you
+look at the balance report, you will see a large negative number for
+Equity that never changes: Because that is what you were worth (what
+you debited from yourself in order to start the ledger) before the
+money started moving around. If the total positive value of your
+assets is greater than the absolute value of your starting equity, it
+means you are making money.
+
+Clear as mud? Keep thinking about it. Until you figure it out, put
+@samp{-Equity} at the end of your balance command, to remove the
+confusing figure from the total.
+
+@node Dealing with Petty Cash, Working with multiple funds and accounts, Understanding Equity, Keeping a ledger
+@section Dealing with Petty Cash
+
+Something that stops many people from keeping a ledger at all is the
+insanity of tracking small cash expenses. They rarely generate a
+receipt, and there are often a lot of small transactions, rather than
+a few large ones, as with checks.
+
+One solution is: don't bother. Move your spending to a debit card,
+but in general ignore cash. Once you withdraw it from the ATM, mark
+it as already spent to an @samp{Expenses:Cash} category:
+
+@smallexample
+2004/03/15 ATM
+ Expenses:Cash $100.00
+ Assets:Checking
+@end smallexample
+
+If at some point you make a large cash expense that you want to track,
+just ``move'' the amount of the expense from @samp{Expenses:Cash} into
+the target account:
+
+@smallexample
+2004/03/20 Somebody
+ Expenses:Food $65.00
+ Expenses:Cash
+@end smallexample
+
+This way, you can still track large cash expenses, while ignoring all
+of the smaller ones.
+
+@node Working with multiple funds and accounts, Archiving previous years, Dealing with Petty Cash, Keeping a ledger
+@section Working with multiple funds and accounts
+
+There are situations when the accounts you're tracking are different
+between your clients and the financial institutions where money is
+kept. An example of this is working as the treasurer for a religious
+institution. From the secular point of view, you might be working
+with three different accounts:
+
+@itemize
+@item Checking
+@item Savings
+@item Credit Card
+@end itemize
+
+From a religious point of view, the community expects to divide its
+resources into multiple ``funds'', from which it makes purchases or
+reserves resources for later:
+
+@itemize
+@item School fund
+@item Building fund
+@item Community fund
+@end itemize
+
+The problem with this kind of setup is that when you spend money, it
+comes from two or more places at once: the account and the fund. And
+yet, the correlation of amounts between funds and accounts is rarely
+one-to-one. What if the school fund has @samp{$500.00}, but
+@samp{$400.00} of that comes from Checking, and @samp{$100.00} from
+Savings?
+
+Traditional finance packages require that the money reside in only one
+place. But there are really two ``views'' of the data: from the
+account point of view and from the fund point of view -- yet both sets
+should reflect the same overall expenses and cash flow. It's simply
+where the money resides that differs.
+
+This situation can be handled one of two ways. The first is using
+virtual transactions to represent the fact that money is moving to and
+from two kind of accounts at the same time:
+
+@smallexample
+2004/03/20 Contributions
+ Assets:Checking $500.00
+ Income:Donations
+
+2004/03/25 Distribution of donations
+ [Funds:School] $300.00
+ [Funds:Building] $200.00
+ [Assets:Checking] $-500.00
+@end smallexample
+
+The use of square brackets in the second entry ensures that the
+virtual transactions balance to zero. Now money can be spent directly
+from a fund at the same time as money is drawn from a physical
+account:
+
+@smallexample
+2004/03/25 Payment for books (paid from Checking)
+ Expenses:Books $100.00
+ Assets:Checking $-100.00
+ (Funds:School) $-100.00
+@end smallexample
+
+When reports are generated, by default they'll appear in terms of the
+funds. In this case, you will likely want to mask out your
+@samp{Assets} account, because otherwise the balance won't make much
+sense:
+
+@example
+ledger bal -^Assets
+@end example
+
+If the @option{--real} option is used, the report will be in terms of
+the real accounts:
+
+@example
+ledger --real bal
+@end example
+
+If more asset accounts are needed as the source of a transaction, just
+list them as you would normally, for example:
+
+@smallexample
+2004/03/25 Payment for books (paid from Checking)
+ Expenses:Books $100.00
+ Assets:Checking $-50.00
+ Liabilities:Credit Card $-50.00
+ (Funds:School) $-100.00
+@end smallexample
+
+The second way of tracking funds is to use entry codes. In this
+respect the codes become like virtual accounts that embrace the entire
+set of transactions. Basically, we are associating an entry with a
+fund by setting its code. Here are two entries that desposit money
+into, and spend money from, the @samp{Funds:School} fund:
+
+@smallexample
+2004/03/25 (Funds:School) Donations
+ Assets:Checking $100.00
+ Income:Donations
+
+2004/04/25 (Funds:School) Payment for books
+ Expenses:Books $50.00
+ Assets:Checking
+@end smallexample
+
+Note how the accounts now relate only to the real accounts, and any
+balance or registers reports will reflect this. That the entries
+relate to a particular fund is kept only in the code.
+
+How does this become a fund report? By using the
+@option{--code-as-payee} option, you can generate a register report
+where the payee for each transaction shows the code. Alone, this is
+not terribly interesting; but when combined with the
+@option{--by-payee} option, you will now see account subtotals for any
+transactions related to a specific fund. So, to see the current
+monetary balances of all funds, the command would be:
+
+@smallexample
+ledger --code-as-payee -P reg ^Assets
+@end smallexample
+
+Or to see a particular funds expenses, the @samp{School} fund in this
+case:
+
+@smallexample
+ledger --code-as-payee -P reg ^Expenses -- School
+@end smallexample
+
+Both approaches yield different kinds of flexibility, depending on how
+you prefer to think of your funds: as virtual accounts, or as tags
+associated with particular entries. Your own tastes will decide which
+is best for your situation.
+
+@node Archiving previous years, Virtual transactions, Working with multiple funds and accounts, Keeping a ledger
+@section Archiving previous years
+
+After a while, your ledger can get to be pretty large. While this
+will not slow down the ledger program much---it's designed to process
+ledger files very quickly---things can start to feel ``messy''; and
+it's a universal complaint that when finances feel messy, people avoid
+them.
+
+Thus, archiving the data from previous years into their own files can
+offer a sense of completion, and freedom from the past. But how to
+best accomplish this with the ledger program? There are two commands
+that make it very simple: @command{print}, and @command{equity}.
+
+Let's take an example file, with data ranging from year 2000 until
+2004. We want to archive years 2000 and 2001 to their own file,
+leaving just 2003 and 2004 in the current file. So, use
+@command{print} to output all the earlier entries to a file called
+@file{ledger-old.dat}:
+
+@smallexample
+ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat
+@end smallexample
+
+To delete older data from the current ledger file, use @command{print}
+again, this time specifying year 2002 as the starting date:
+
+@example
+ledger -f ledger.dat -b 2002 print > x
+mv x ledger.dat
+@end example
+
+However, now the current file contains @emph{only} transactions from
+2002 onward, which will not yield accurate present-day balances,
+because the net income from previous years is no longer being tallied.
+To compensate for this, we must append an equity report for the old
+ledger at the beginning of the new one:
+
+@example
+ledger -f ledger-old.dat equity > equity.dat
+cat equity.dat ledger.dat > x
+mv x ledger.dat
+rm equity.dat
+@end example
+
+Now the balances reported from @file{ledger.dat} are identical to what
+they were before the data was split.
+
+How often should you split your ledger? You never need to, if you
+don't want to. Even eighty years of data will not slow down ledger
+much---and that's just using present day hardware! Or, you can keep
+the previous and current year in one file, and each year before that
+in its own file. It's really up to you, and how you want to organize
+your finances. For those who also keep an accurate paper trail, it
+might be useful to archive the older years to their own files, then
+burn those files to a CD to keep with the paper records---along with
+any electronic statements received during the year. In the arena of
+organization, just keep in mind this maxim: Do whatever keeps you
+doing it.
+
+@node Virtual transactions, Automated transactions, Archiving previous years, Keeping a ledger
+@section Virtual transactions
+
+A virtual transaction is when you, in your mind, see money as moving
+to a certain place, when in reality that money has not moved at all.
+There are several scenarios in which this type of tracking comes in
+handy, and each of them will be discussed in detail.
+
+To enter a virtual transaction, surround the account name in
+parentheses. This form of usage does not need to balance. However,
+if you want to ensure the virtual transaction balances with other
+virtual transactions in the same entry, use square brackets. For
+example:
+
+@smallexample
+10/2 Paycheck
+ Assets:Checking $1000.00
+ Income:Salary $-1000.00
+ (Debt:Alimony) $200.00
+@end smallexample
+
+In this example, after receiving a paycheck an alimony debt is
+increased---even though no money has moved around yet.
+
+@smallexample
+10/2 Paycheck
+ Assets:Checking $1000.00
+ Income:Salary $-1000.00
+ [Savings:Trip] $200.00
+ [Assets:Checking] $-200.00
+@end smallexample
+
+In this example, $200 has been deducted from checking toward savings
+for a trip. It will appear as though the money has been moved from
+the account into @samp{Savings:Trip}, although no money has actually
+moved anywhere.
+
+When balances are displayed, virtual transactions will be factored in.
+To view balances without any virtual balances factored in, using the
+@option{-R} flag, for ``reality''.
+
+@node Automated transactions, Using Emacs to Keep Your Ledger, Virtual transactions, Keeping a ledger
+@section Automated transactions
+
+As a Bahá'í, I need to compute Huqúqu'lláh whenever I acquire assets.
+It is similar to tithing for Jews and Christians, or to Zakát for
+Muslims. The exact details of computing Huqúqu'lláh are somewhat
+complex, but if you have further interest, please consult the Web.
+
+Ledger makes this otherwise difficult law very easy. Just set up an
+automated transaction at the top of your ledger file:
+
+@smallexample
+; This automated entry will compute Huqúqu'lláh based on this
+; journal's transactions. Any that match will affect the
+; Liabilities:Huququ'llah account by 19% of the value of that
+; transaction.
+
+= /^(?:Income:|Expenses:(?:Business|Rent$|Furnishings|Taxes|Insurance))/
+ (Liabilities:Huququ'llah) 0.19
+@end smallexample
+
+This automated transaction works by looking at each transaction in the
+ledger file. If any match the given value expression, 19% of the
+transaction's value is applied to the @samp{Liabilities:Huququ'llah}
+account. So, if $1000 is earned from @samp{Income:Salary}, $190 is
+added to @samp{Liabilities:Huqúqu'lláh}; if $1000 is spent on Rent,
+$190 is subtracted. The ultimate balance of Huqúqu'lláh reflects how
+much is owed in order to fulfill one's obligation to Huqúqu'lláh.
+When ready to pay, just write a check to cover the amount shown in
+@samp{Liabilities:Huququ'llah}. That entry would look like:
+
+@smallexample
+2003/01/01 (101) Baha'i Huqúqu'lláh Trust
+ Liabilities:Huququ'llah $1,000.00
+ Assets:Checking
+@end smallexample
+
+That's it. To see how much Huqúq is currently owed based on your
+ledger entries, use:
+
+@example
+ledger balance Liabilities:Huquq
+@end example
+
+This works fine, but omits one aspect of the law: that Huquq is only
+due once the liability exceeds the value of 19 mithqáls of gold (which
+is roughly 2.22 ounces). So what we want is for the liability to
+appear in the balance report only when it exceeds the present day
+value of 2.22 ounces of gold. This can be accomplished using the
+command:
+
+@smallexample
+ledger -Q -t "/Liab.*Huquq/?(a/P@{2.22 AU@}<=@{-1.0@}&a):a" -s bal liab
+@end smallexample
+
+With this command, the current price for gold is downloaded, and the
+Huqúqu'lláh is reported only if its value exceeds that of 2.22 ounces
+of gold. If you wish the liability to be reflected in the parent
+subtotal either way, use this instead:
+
+@smallexample
+ledger -Q -T "/Liab.*Huquq/?(O/P@{2.22 AU@}<=@{-1.0@}&O):O" -s bal liab
+@end smallexample
+
+In some cases, you may wish to refer to the account of whichever
+transaction matched your automated entry's value expression. To do
+this, use the special account name @samp{$account}:
+
+@smallexample
+= /^Some:Long:Account:Name/
+ [$account] -0.10
+ [Savings] 0.10
+@end smallexample
+
+This example causes 10% of the matching account's total to be deferred
+to the @samp{Savings} account---as a balanced virtual transaction,
+which may be excluded from reports by using @option{--real}.
+
+@node Using Emacs to Keep Your Ledger, Using GnuCash to Keep Your Ledger, Automated transactions, Keeping a ledger
+@section Using Emacs to Keep Your Ledger
+
+In the Ledger tarball is an Emacs module, @file{ledger.el}. This
+module makes the process of keeping a text ledger much easier for
+Emacs users. I recommend putting this at the top of your ledger file:
+
+@example
+; -*-ledger-*-
+@end example
+
+And this in your @file{.emacs} file, after copying @file{ledger.el} to
+your @file{site-lisp} directory:
+
+@example
+(load "ledger")
+@end example
+
+Now when you edit your ledger file, it will be in
+@command{ledger-mode}. @command{ledger-mode} adds these commands:
+
+@table @strong
+@item C-c C-a
+For quickly adding new entries based on the form of older ones (see
+previous section).
+
+@item C-c C-c
+Toggles the ``cleared'' flag of the transaction under point.
+
+@item C-c C-d
+Delete the entry under point.
+
+@item C-c C-r
+Reconciles an account by displaying the transactions in another
+buffer, where simply hitting the spacebar will toggle the pending flag
+of the transaction in the ledger. Once all the appropriate
+transactions have been marked, press C-c C-c in the reconcile buffer
+to ``commit'' the reconciliation, which will mark all of the entries
+as cleared, and display the new cleared balance in the minibuffer.
+
+@item C-c C-m
+Set the default month for new entries added with C-c C-a. This is
+handy if you have a large number of transactions to enter from a
+previous month.
+
+@item C-c C-y
+Set the default year for new entries added with C-c C-a. This is
+handy if you have a large number of transactions to enter from a
+previous year.
+@end table
+
+Once you enter the reconcile buffer, there are several key commands
+available:
+
+@table @strong
+@item RET
+Visit the ledger file entry corresponding to the reconcile entry.
+
+@item C-c C-c
+Commit the reconcialation. This marks all of the marked transactions
+as ``cleared'', saves the ledger file, and then displays the new
+cleared balance.
+
+@item C-l
+Refresh the reconcile buffer by re-reading transactions from the
+ledger data file.
+
+@item SPC
+Toggle the transaction under point as cleared.
+
+@item a
+Add a new entry to the ledger data file, and refresh the reconcile
+buffer to include its transactions (if the entry is added to the same
+account as the one being reconciled).
+
+@item d
+Delete the entry related to the transaction under point. Note: This
+may result in multiple transactions being deleted.
+
+@item n
+Move to the next line.
+
+@item p
+Move to the previous line.
+
+@item C-c C-r
+@item r
+Attempt to auto-reconcile the transactions to the entered balance. If
+it can do so, it will mark all those transactions as pending that
+would yield the specified balance.
+
+@item C-x C-s
+@item s
+Save the ledger data file, and show the current cleared balance for
+the account being reconciled.
+
+@item q
+Quit the reconcile buffer.
+@end table
+
+There is also an @command{emacs} command which can be used to output
+reports in a format directly @code{read}-able from Emacs Lisp.
+
+@node Using GnuCash to Keep Your Ledger, Using timeclock to record billable time, Using Emacs to Keep Your Ledger, Keeping a ledger
+@section Using GnuCash to Keep Your Ledger
+
+The Ledger tool is fast and simple, but it offers no custom method for
+actually editing the ledger. It assumes you know how to use a text
+editor, and like doing so. There is, at least, an Emacs mode that
+makes editing Ledger's data files much easier.
+
+You are also free to use GnuCash to maintain your ledger, and the
+Ledger program for querying and reporting on the contents of that
+ledger. It takes a little longer to parse the XML data format that
+GnuCash uses, but the end result is identical.
+
+Then again, why would anyone use a Gnome-centric, multi-megabyte
+behemoth to edit their data, and only a one megabyte binary to query
+it?
+
+@node Using timeclock to record billable time, , Using GnuCash to Keep Your Ledger, Keeping a ledger
+@section Using timeclock to record billable time
+
+The timeclock tool makes it easy to track time events, like clocking
+into and out of a particular job. These events accumulate in a
+timelog file.
+
+Each in/out event may have an optional description. If the ``in''
+description is a ledger account name, these in/out pairs may be viewed
+as virtual transactions, adding time commodities (hours) to that
+account.
+
+For example, the command-line version of the timeclock tool could be
+used to begin a timelog file like:
+
+@example
+export TIMELOG=$HOME/.timelog
+ti ClientOne category
+sleep 10
+to waited for ten seconds
+@end example
+
+The @file{.timelog} file now contains:
+
+@smallexample
+i 2004/10/06 15:21:00 ClientOne category
+o 2004/10/06 15:21:10 waited for ten seconds
+@end smallexample
+
+Ledger parses this directly, as if it had seen the following entry:
+
+@smallexample
+2004/10/06 category
+ (ClientOne) 10s
+@end smallexample
+
+In other words, the timelog event pair is seen as adding 0.00277h (ten
+seconds) worth of time to the @samp{ClientOne} account. This would be
+considered billable time, which later could be invoiced and credited
+to accounts receivable:
+
+@smallexample
+2004/11/01 (INV#1) ClientOne, Inc.
+ Receivable:ClientOne $0.10
+ ClientOne -0.00277h @@ $35.00
+@end smallexample
+
+The above transaction converts the clocked time into an invoice for
+the time spent, at an hourly rate of $35. Once the invoice is paid,
+the money is deposited from the receivable account into a checking
+account:
+
+@smallexample
+2004/12/01 ClientOne, Inc.
+ Assets:Checking $0.10
+ Receivable:ClientOne
+@end smallexample
+
+And now the time spent has been turned into hard cash in the checking
+account.
+
+The advantage to using timeclock and invoicing to bill time is that
+you will always know, by looking at the balance report, exactly how
+much unbilled and unpaid time you've spent working for any particular
+client.
+
+I like to @samp{!include} my timelog at the top of my company's
+accounting ledger, with the attached prefix @samp{Billable}:
+
+@smallexample
+; -*-ledger-*-
+
+; This is the ledger file for my company. But first, include the
+; timelog data, entering all of the time events within the umbrella
+; account "Billable".
+
+!account Billable
+!include /home/johnw/.timelog
+!end
+
+; Here follows this fiscal year's transactions for the company.
+
+2004/11/01 (INV#1) ClientOne, Inc.
+ Receivable:ClientOne $0.10
+ Billable:ClientOne -0.00277h @@ $35.00
+
+2004/12/01 ClientOne, Inc.
+ Assets:Checking $0.10
+ Receivable:ClientOne
+@end smallexample
+
+@node Using XML, , 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}. Typically these transactions will
+all balance each other, but if not they will be automatically balanced
+into an account named @samp{<Unknown>}.
+
+Within the @samp{en:transactions} 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 can read
+the same data as long as the @file{expat} library was available
+when Ledger was built.
+
+@bye
diff --git a/doc/sample.dat b/doc/sample.dat
new file mode 100644
index 00000000..4a271d6f
--- /dev/null
+++ b/doc/sample.dat
@@ -0,0 +1,26 @@
+= /^Expenses:Books/
+ (Liabilities:Taxes) -0.10
+
+~ Monthly
+ Assets:Bank:Checking $500.00
+ Income:Salary
+
+2004/05/01 * Checking balance
+ Assets:Bank:Checking $1,000.00
+ Equity:Opening Balances
+
+2004/05/01 * Investment balance
+ Assets:Brokerage 50 AAPL @ $30.00
+ Equity:Opening Balances
+
+2004/05/14 * Pay day
+ Assets:Bank:Checking $500.00
+ Income:Salary
+
+2004/05/27 Book Store
+ Expenses:Books $20.00
+ Liabilities:MasterCard
+
+2004/05/27 (100) Credit card company
+ Liabilities:MasterCard $20.00
+ Assets:Bank:Checking
generated by cgit v1.2.3 (git 2.39.1) at 2025-01-24 14:33:13 +0000