diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Doxyfile | 275 | ||||
| -rw-r--r-- | docs/Manual.mellel/main.xml | 2 | ||||
| -rw-r--r-- | docs/date-examples.txt | 42 | ||||
| -rw-r--r-- | docs/ledger.info | 3640 | ||||
| -rw-r--r-- | docs/ledger.texi | 3960 | ||||
| -rw-r--r-- | docs/sample.dat | 26 |
6 files changed, 0 insertions, 7945 deletions
diff --git a/docs/Doxyfile b/docs/Doxyfile deleted file mode 100644 index a03b54d4..00000000 --- a/docs/Doxyfile +++ /dev/null @@ -1,275 +0,0 @@ -# Doxyfile 1.5.1 - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- -PROJECT_NAME = Ledger -PROJECT_NUMBER = 3.0 -OUTPUT_DIRECTORY = %builddir%/docs -CREATE_SUBDIRS = NO -OUTPUT_LANGUAGE = English -USE_WINDOWS_ENCODING = NO -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ABBREVIATE_BRIEF = "The $name class" \ - "The $name widget" \ - "The $name file" \ - is \ - provides \ - specifies \ - contains \ - represents \ - a \ - an \ - the -ALWAYS_DETAILED_SEC = NO -INLINE_INHERITED_MEMB = NO -FULL_PATH_NAMES = YES -STRIP_FROM_PATH = /Applications/Copied/ -STRIP_FROM_INC_PATH = -SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = NO -MULTILINE_CPP_IS_BRIEF = NO -DETAILS_AT_TOP = NO -INHERIT_DOCS = YES -SEPARATE_MEMBER_PAGES = NO -TAB_SIZE = 8 -ALIASES = -OPTIMIZE_OUTPUT_FOR_C = NO -OPTIMIZE_OUTPUT_JAVA = NO -BUILTIN_STL_SUPPORT = YES -DISTRIBUTE_GROUP_DOC = NO -SUBGROUPING = YES -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- -EXTRACT_ALL = NO -EXTRACT_PRIVATE = NO -EXTRACT_STATIC = NO -EXTRACT_LOCAL_CLASSES = YES -EXTRACT_LOCAL_METHODS = NO -HIDE_UNDOC_MEMBERS = YES -HIDE_UNDOC_CLASSES = YES -HIDE_FRIEND_COMPOUNDS = NO -HIDE_IN_BODY_DOCS = NO -INTERNAL_DOCS = NO -CASE_SENSE_NAMES = NO -HIDE_SCOPE_NAMES = NO -SHOW_INCLUDE_FILES = YES -INLINE_INFO = YES -SORT_MEMBER_DOCS = YES -SORT_BRIEF_DOCS = NO -SORT_BY_SCOPE_NAME = NO -GENERATE_TODOLIST = YES -GENERATE_TESTLIST = YES -GENERATE_BUGLIST = YES -GENERATE_DEPRECATEDLIST= YES -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -SHOW_USED_FILES = YES -SHOW_DIRECTORIES = NO -FILE_VERSION_FILTER = -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- -QUIET = NO -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO -WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- -INPUT = %srcdir% -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 -RECURSIVE = NO -EXCLUDE = -EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXAMPLE_PATH = -EXAMPLE_PATTERNS = * -EXAMPLE_RECURSIVE = NO -IMAGE_PATH = -INPUT_FILTER = -FILTER_PATTERNS = -FILTER_SOURCE_FILES = NO -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- -SOURCE_BROWSER = YES -INLINE_SOURCES = NO -STRIP_CODE_COMMENTS = YES -REFERENCED_BY_RELATION = YES -REFERENCES_RELATION = YES -REFERENCES_LINK_SOURCE = YES -USE_HTAGS = NO -VERBATIM_HEADERS = YES -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- -ALPHABETICAL_INDEX = NO -COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- -GENERATE_HTML = YES -HTML_OUTPUT = html -HTML_FILE_EXTENSION = .html -HTML_HEADER = -HTML_FOOTER = -HTML_STYLESHEET = -HTML_ALIGN_MEMBERS = YES -GENERATE_HTMLHELP = NO -CHM_FILE = -HHC_LOCATION = -GENERATE_CHI = NO -BINARY_TOC = NO -TOC_EXPAND = NO -DISABLE_INDEX = NO -ENUM_VALUES_PER_LINE = 4 -GENERATE_TREEVIEW = YES -TREEVIEW_WIDTH = 250 -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- -GENERATE_LATEX = YES -LATEX_OUTPUT = latex -LATEX_CMD_NAME = latex -MAKEINDEX_CMD_NAME = makeindex -COMPACT_LATEX = NO -PAPER_TYPE = usletter -EXTRA_PACKAGES = -LATEX_HEADER = -PDF_HYPERLINKS = YES -USE_PDFLATEX = YES -LATEX_BATCHMODE = NO -LATEX_HIDE_INDICES = NO -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- -GENERATE_RTF = NO -RTF_OUTPUT = rtf -COMPACT_RTF = NO -RTF_HYPERLINKS = NO -RTF_STYLESHEET_FILE = -RTF_EXTENSIONS_FILE = -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- -GENERATE_MAN = NO -MAN_OUTPUT = man -MAN_EXTENSION = .3 -MAN_LINKS = NO -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- -GENERATE_XML = NO -XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = -XML_PROGRAMLISTING = YES -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- -GENERATE_AUTOGEN_DEF = NO -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- -GENERATE_PERLMOD = NO -PERLMOD_LATEX = NO -PERLMOD_PRETTY = YES -PERLMOD_MAKEVAR_PREFIX = -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = NO -EXPAND_ONLY_PREDEF = NO -SEARCH_INCLUDES = YES -INCLUDE_PATH = -INCLUDE_FILE_PATTERNS = -PREDEFINED = -EXPAND_AS_DEFINED = -SKIP_FUNCTION_MACROS = YES -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- -TAGFILES = -GENERATE_TAGFILE = -ALLEXTERNALS = NO -EXTERNAL_GROUPS = YES -PERL_PATH = /usr/bin/perl -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- -CLASS_DIAGRAMS = YES -HIDE_UNDOC_RELATIONS = YES -HAVE_DOT = YES -CLASS_GRAPH = YES -COLLABORATION_GRAPH = YES -GROUP_GRAPHS = YES -UML_LOOK = YES -TEMPLATE_RELATIONS = NO -INCLUDE_GRAPH = YES -INCLUDED_BY_GRAPH = YES -CALL_GRAPH = NO -CALLER_GRAPH = NO -GRAPHICAL_HIERARCHY = YES -DIRECTORY_GRAPH = YES -DOT_IMAGE_FORMAT = png -DOT_PATH = /Applications/Copied/Doxygen.app/Contents/Resources/dot -DOTFILE_DIRS = -MAX_DOT_GRAPH_WIDTH = 1024 -MAX_DOT_GRAPH_HEIGHT = 1024 -MAX_DOT_GRAPH_DEPTH = 1000 -DOT_TRANSPARENT = NO -DOT_MULTI_TARGETS = NO -GENERATE_LEGEND = YES -DOT_CLEANUP = YES -#--------------------------------------------------------------------------- -# Configuration::additions related to the search engine -#--------------------------------------------------------------------------- -SEARCHENGINE = NO diff --git a/docs/Manual.mellel/main.xml b/docs/Manual.mellel/main.xml deleted file mode 100644 index 10acf8fe..00000000 --- a/docs/Manual.mellel/main.xml +++ /dev/null @@ -1,2 +0,0 @@ -<?xml version="1.0" encoding="UTF-8" ?> -<archive creator='com.redlex.mellel' writer-version='13' compatibility-version='10'><pooled-objects><section-style ref='ss-0'><name>Default (1 column)</name><unique-id>ERSS-26967d18-8242-42d9-a231-f14908f85583</unique-id><column-count value='1'/><balance-columns value='yes'/><gutter-width value='11'/><gutter-line-type value='none'/><gutter-line-color type='calibrated-white' white='0' alpha='1'/><gutter-line-width value='1'/><gutter-line-top value='0'/><gutter-line-bottom value='0'/><background-color><value type='calibrated-white' white='1' alpha='1'/><opaque value='no'/></background-color><space-above-column value='0'/></section-style><section-style ref='ss-1'><name>2 Columns</name><unique-id>ERSS-00ca23ce-d93f-433a-8725-ef091011e6fd</unique-id><column-count value='2'/><balance-columns value='yes'/><gutter-width value='14.40000057220459'/><gutter-line-type value='solid'/><gutter-line-color type='calibrated-white' white='0' alpha='1'/><gutter-line-width value='0.5'/><gutter-line-top value='5'/><gutter-line-bottom value='5'/><background-color><value type='calibrated-white' white='1' alpha='1'/><opaque value='no'/></background-color><space-above-column value='0'/></section-style><section-style ref='ss-2'><name>3 Columns</name><unique-id>ERSS-776d85db-61b6-4109-b53f-0187642c4d42</unique-id><column-count value='3'/><balance-columns value='yes'/><gutter-width value='10.800000190734863'/><gutter-line-type value='none'/><gutter-line-color type='calibrated-white' white='0' alpha='1'/><gutter-line-width value='0.5'/><gutter-line-top value='5'/><gutter-line-bottom value='5'/><background-color><value type='calibrated-white' white='1' alpha='1'/><opaque value='no'/></background-color><space-above-column value='0'/></section-style><section-style ref='ss-3'><name>3 Columns (background)</name><unique-id>ERSS-fd7d57d7-b3a6-4823-9aa7-845e6243d3b8</unique-id><column-count value='3'/><balance-columns value='yes'/><gutter-width value='10.800000190734863'/><gutter-line-type value='none'/><gutter-line-color type='calibrated-white' white='0' alpha='1'/><gutter-line-width value='0.5'/><gutter-line-top value='5'/><gutter-line-bottom value='5'/><background-color><value type='calibrated-rgb' red='0.99301600456237793' green='1' blue='0.62362498044967651' alpha='1'/><opaque value='yes'/></background-color><space-above-column value='0'/></section-style><character-style ref='cs-0'><name>Title</name><shortcut>3</shortcut><unique-id>ERCS-535e8429-c441-4876-b588-0728feeecfb2</unique-id><variations><variation><line-type value='none'/><stroke-type value='none'/><secondary-font-script value='none'/><case-type value='small-caps'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='100'/><language value='None'/><main-font><font-family>Times</font-family><font-face>Bold</font-face></main-font><opentype/><secondary-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><background-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><main-font-size value='24'/><line-stroke-weight type='relative' value='100'/></variation><variation/><variation><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation><variation/><variation><line-type value='under'/></variation><variation/><variation/><variation><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation></variations></character-style><character-style ref='cs-1'><name>Heading</name><shortcut>4</shortcut><unique-id>ERCS-9251b4c9-d4f3-4df9-b0c5-68d0d27f34bb</unique-id><variations><variation><line-type value='none'/><stroke-type value='none'/><secondary-font-script value='arabic'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='137.5'/><language value='Farsi'/><main-font><font-family>Times</font-family><font-face>Bold</font-face></main-font><opentype><discretionary-ligatures/><titling-alternates/><contextual-alternates/></opentype><secondary-font><font-family>Scheherazade</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><background-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><main-font-size value='16'/><line-stroke-weight type='relative' value='100'/></variation><variation/><variation><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation><variation/><variation><line-type value='under'/></variation><variation/><variation><main-font-size value='14'/></variation><variation><main-font-size value='14'/><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation></variations></character-style><character-style ref='cs-2'><name>Header/footer</name><shortcut/><unique-id>ERCS-e6ef5c8c-cc64-4a1d-9e68-2d4dff765309</unique-id><variations><variation><main-font-size value='11'/><stroke-type value='none'/><secondary-font-script value='none'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='100'/><language value='None'/><main-font><font-family>Times</font-family><font-face>Regular</font-face></main-font><opentype/><secondary-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><background-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><line-type value='none'/><line-stroke-weight type='relative' value='100'/></variation><variation><main-font><font-family>Times</font-family><font-face>Bold</font-face></main-font></variation><variation><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font></variation><variation><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation><variation><line-type value='under'/></variation><variation><line-type value='under'/><char-color type='calibrated-rgb' red='0' green='0' blue='0.9960780143737793' alpha='1'/></variation><variation><main-font-size value='10'/></variation><variation><main-font-size value='10'/><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font></variation></variations></character-style><character-style ref='cs-3'><name>Body</name><shortcut/><unique-id>ERCS-736c2800-45c1-4637-9f5c-5234175a5cdc</unique-id><variations><variation><ligatures value='yes'/><line-stroke-weight type='relative' value='100'/><secondary-font-script value='none'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='100'/><language value='None'/><main-font><font-family>Helvetica Neue</font-family><font-face>Regular</font-face></main-font><opentype/><secondary-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><background-type value='none'/><main-font-size value='12'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><line-type value='none'/><stroke-type value='none'/></variation><variation><main-font><font-family>Helvetica Neue</font-family><font-face>Bold</font-face></main-font></variation><variation><main-font><font-family>Helvetica Neue</font-family><font-face>Italic</font-face></main-font></variation><variation><main-font><font-family>Helvetica Neue</font-family><font-face>Bold Italic</font-face></main-font></variation><variation><line-type value='under'/></variation><variation><line-type value='under'/><char-color type='calibrated-rgb' red='0' green='0' blue='0.9960780143737793' alpha='1'/></variation><variation><main-font-size value='11'/></variation><variation><main-font-size value='11'/><main-font><font-family>Helvetica Neue</font-family><font-face>Italic</font-face></main-font></variation></variations></character-style><character-style ref='cs-4'><name>Regular</name><shortcut>1</shortcut><unique-id>ERCS-520af7d0-14e9-4bc7-9b4b-def9cb71ee51</unique-id><variations><variation><background-type value='none'/><stroke-type value='none'/><secondary-font-script value='arabic'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='133'/><language value='None'/><main-font><font-family>Times</font-family><font-face>Regular</font-face></main-font><opentype><discretionary-ligatures/><contextual-alternates/></opentype><secondary-font><font-family>Scheherazade</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><main-font-size value='12'/><line-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><ligatures value='yes'/><line-stroke-weight type='relative' value='100'/></variation><variation/><variation/><variation/><variation/><variation/><variation/><variation/></variations></character-style><character-style ref='cs-5'><name>Sub-heading</name><shortcut>5</shortcut><unique-id>ERCS-55328100-7846-47e1-a585-e7b3786f98bc</unique-id><variations><variation><line-type value='none'/><stroke-type value='none'/><secondary-font-script value='arabic'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='128.57142639160156'/><language value='Farsi'/><main-font><font-family>Times</font-family><font-face>Bold</font-face></main-font><opentype><discretionary-ligatures/><titling-alternates/><contextual-alternates/></opentype><secondary-font><font-family>Scheherazade</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><background-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><main-font-size value='14'/><line-stroke-weight type='relative' value='100'/></variation><variation><main-font-size value='12'/></variation><variation><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation><variation/><variation><line-type value='under'/></variation><variation/><variation><main-font-size value='12'/></variation><variation><main-font-size value='12'/><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation></variations></character-style><character-style ref='cs-6'><name>-</name><shortcut/><unique-id>ERCS-f5c8396d-a39e-4572-8ff2-c96fc49a732d</unique-id><variations><variation><line-type value='none'/><line-stroke-weight type='relative' value='100'/><secondary-font-script value='none'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='100'/><language value='None'/><main-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></main-font><opentype/><secondary-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><background-type value='none'/><main-font-size value='12'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><ligatures value='yes'/><stroke-type value='none'/></variation><variation/><variation/><variation/><variation/><variation/><variation/><variation/></variations></character-style><character-style ref='cs-7'><name>Author</name><shortcut/><unique-id>ERCS-14083e28-2b71-4152-819c-a3275ba3148b</unique-id><variations><variation><position value='none'/><line-stroke-weight type='relative' value='100'/><secondary-font-script value='none'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='100'/><language value='None'/><main-font><font-family>Times</font-family><font-face>Regular</font-face></main-font><opentype/><secondary-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><line-type value='none'/><baseline-shift value='0'/><main-font-size value='18'/><kashida value='yes'/><background-type value='none'/><stroke-type value='none'/></variation><variation/><variation/><variation/><variation/><variation/><variation/><variation/></variations></character-style><character-style ref='cs-8'><name>Quotation</name><shortcut/><unique-id>ERCS-67ffcc5d-db4c-47bc-94e9-d735735063bd</unique-id><variations><variation><line-type value='none'/><line-stroke-weight type='relative' value='100'/><secondary-font-script value='arabic'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='133'/><language value='None'/><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font><opentype><discretionary-ligatures/><contextual-alternates/></opentype><secondary-font><font-family>Scheherazade</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><background-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><main-font-size value='12'/><stroke-type value='none'/></variation><variation/><variation/><variation/><variation/><variation/><variation/><variation/></variations></character-style><character-style ref='cs-9'><name>Note text</name><shortcut>6</shortcut><unique-id>ERCS-4a3b6e47-1a2e-4621-bd3c-84653d66704e</unique-id><variations><variation><line-type value='none'/><stroke-type value='none'/><secondary-font-script value='arabic'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='127'/><language value='Farsi'/><main-font><font-family>Times</font-family><font-face>Regular</font-face></main-font><opentype><discretionary-ligatures/><contextual-alternates/></opentype><secondary-font><font-family>Scheherazade</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><background-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><main-font-size value='11'/><line-stroke-weight type='relative' value='100'/></variation><variation><main-font><font-family>Times</font-family><font-face>Bold</font-face></main-font></variation><variation><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font></variation><variation><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation><variation><line-type value='under'/></variation><variation><line-type value='under'/><char-color type='calibrated-rgb' red='0' green='0' blue='0.9960780143737793' alpha='1'/></variation><variation/><variation><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font></variation></variations></character-style><character-style ref='cs-10'><name>Note text small</name><shortcut>7</shortcut><unique-id>ERCS-38a2863b-6d51-48b3-9286-075760d73df8</unique-id><variations><variation><main-font-size value='10'/><stroke-type value='none'/><secondary-font-script value='none'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='100'/><language value='None'/><main-font><font-family>Times</font-family><font-face>Regular</font-face></main-font><opentype/><secondary-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><background-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><line-type value='none'/><line-stroke-weight type='relative' value='100'/></variation><variation><main-font><font-family>Times</font-family><font-face>Bold</font-face></main-font></variation><variation><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font></variation><variation><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation><variation><line-type value='under'/></variation><variation><line-type value='under'/><char-color type='calibrated-rgb' red='0' green='0' blue='0.9960780143737793' alpha='1'/></variation><variation><main-font-size value='9'/></variation><variation><main-font-size value='9'/><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font></variation></variations></character-style><character-style ref='cs-11'><name>Citation</name><shortcut/><unique-id>ERCS-95056148-2573-4a6c-8535-29a54aa45ea5</unique-id><variations><variation><line-type value='none'/><line-stroke-weight type='relative' value='100'/><secondary-font-script value='arabic'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='127'/><language value='Farsi'/><main-font><font-family>Times</font-family><font-face>Regular</font-face></main-font><opentype/><secondary-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><background-type value='none'/><kashida value='yes'/><main-font-size value='11'/><position value='none'/><baseline-shift value='0'/><stroke-type value='none'/></variation><variation/><variation/><variation/><variation/><variation/><variation/><variation/></variations></character-style><character-style ref='cs-12'><name>Numbering</name><shortcut/><unique-id>ERCS-736d8573-94d3-45f1-b2d0-b51dc0e2d54f</unique-id><variations><variation><line-type value='none'/><line-stroke-weight type='relative' value='100'/><secondary-font-script value='none'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='100'/><language value='None'/><main-font><font-family>Courier New</font-family><font-face>Regular</font-face></main-font><opentype/><secondary-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><background-type value='none'/><main-font-size value='12'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><ligatures value='yes'/><stroke-type value='none'/></variation><variation><main-font><font-family>Courier New</font-family><font-face>Bold</font-face></main-font></variation><variation><main-font><font-family>Courier New</font-family><font-face>Italic</font-face></main-font></variation><variation><main-font><font-family>Courier New</font-family><font-face>Bold Italic</font-face></main-font></variation><variation><line-type value='under'/></variation><variation><line-type value='under'/><char-color type='calibrated-rgb' red='0' green='0' blue='0.9960780143737793' alpha='1'/></variation><variation><main-font-size value='11'/></variation><variation><main-font-size value='11'/><main-font><font-family>Courier New</font-family><font-face>Italic</font-face></main-font></variation></variations></character-style><character-style ref='cs-13'><name>Foreign</name><shortcut>2</shortcut><unique-id>ERCS-44143335-80f4-4274-ab18-d3babcd943fa</unique-id><variations><variation><line-type value='none'/><line-stroke-weight type='relative' value='100'/><secondary-font-script value='arabic'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='133'/><language value='None'/><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font><opentype><discretionary-ligatures/><contextual-alternates/></opentype><secondary-font><font-family>Scheherazade</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><background-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><main-font-size value='12'/><stroke-type value='none'/></variation><variation/><variation/><variation/><variation/><variation/><variation/><variation/></variations></character-style><character-style ref='cs-14'><name>Body</name><shortcut/><unique-id>ERCS-736c2800-45c1-4637-9f5c-5234175a5cdc</unique-id><variations><variation><main-font-size value='12'/><line-stroke-weight type='relative' value='100'/><secondary-font-script value='none'/><case-type value='none'/><char-color type='calibrated-white' white='0' alpha='1'/><stroke-weight type='relative' value='100'/><background-color type='calibrated-white' white='1' alpha='1'/><line-stroke-color type='calibrated-white' white='0' alpha='1'/><direction-override value='default'/><stroke-color type='calibrated-white' white='0' alpha='1'/><secondary-font-scale value='100'/><language value='None'/><main-font><font-family>Times</font-family><font-face>Regular</font-face></main-font><opentype/><secondary-font><font-family>Lucida Grande</font-family><font-face>Regular</font-face></secondary-font><fill-type value='solid'/><line-stroke-type value='none'/><ligatures value='yes'/><line-type value='none'/><background-type value='none'/><position value='none'/><baseline-shift value='0'/><kashida value='yes'/><stroke-type value='none'/></variation><variation><main-font><font-family>Times</font-family><font-face>Bold</font-face></main-font></variation><variation><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font></variation><variation><main-font><font-family>Times</font-family><font-face>Bold Italic</font-face></main-font></variation><variation><line-type value='under'/></variation><variation><line-type value='under'/><char-color type='calibrated-rgb' red='0' green='0' blue='0.9960780143737793' alpha='1'/></variation><variation><main-font-size value='11'/></variation><variation><main-font-size value='11'/><main-font><font-family>Times</font-family><font-face>Italic</font-face></main-font></variation></variations></character-style><list-style ref='ls-0'><name>Bullet</name><unique-id>ERLS-7b5d0a7d-507e-47a7-b6a3-2428b0a45211</unique-id><levels><level-attributes><margin-pos value='9'/><indent-pos value='9'/><symbol-pos value='0'/><symbol-type value='bullet'/><symbol-format-type value='none'/><symbol-character-attributes><character-style>cs-14</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='9'/><indent-pos value='9'/><symbol-pos value='0'/><symbol-type value='bullet'/><symbol-format-type value='none'/><symbol-character-attributes><character-style>cs-14</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='9'/><indent-pos value='9'/><symbol-pos value='0'/><symbol-type value='bullet'/><symbol-format-type value='none'/><symbol-character-attributes><character-style>cs-14</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='9'/><indent-pos value='9'/><symbol-pos value='0'/><symbol-type value='bullet'/><symbol-format-type value='none'/><symbol-character-attributes><character-style>cs-14</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='9'/><indent-pos value='9'/><symbol-pos value='0'/><symbol-type value='bullet'/><symbol-format-type value='none'/><symbol-character-attributes><character-style>cs-14</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='9'/><indent-pos value='9'/><symbol-pos value='0'/><symbol-type value='bullet'/><symbol-format-type value='none'/><symbol-character-attributes><character-style>cs-14</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='9'/><indent-pos value='9'/><symbol-pos value='0'/><symbol-type value='bullet'/><symbol-format-type value='none'/><symbol-character-attributes><character-style>cs-14</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='9'/><indent-pos value='9'/><symbol-pos value='0'/><symbol-type value='bullet'/><symbol-format-type value='none'/><symbol-character-attributes><character-style>cs-14</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='9'/><indent-pos value='9'/><symbol-pos value='0'/><symbol-type value='bullet'/><symbol-format-type value='none'/><symbol-character-attributes><character-style>cs-14</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes></levels></list-style><list-style ref='ls-1'><name>Harvard</name><unique-id>ERLS-1003053d-3f40-420d-bfdb-852df3437125</unique-id><levels><level-attributes><margin-pos value='24'/><indent-pos value='24'/><symbol-pos value='0'/><symbol-type value='roman-caps'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='latin-caps'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='lain-small'/><symbol-format-type value='add-round-brace'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='24'/><indent-pos value='24'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='wrap-round-braces'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='lain-small'/><symbol-format-type value='wrap-round-braces'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='roman-small'/><symbol-format-type value='add-round-brace'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='24'/><indent-pos value='24'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='wrap-round-braces'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='24'/><indent-pos value='24'/><symbol-pos value='0'/><symbol-type value='lain-small'/><symbol-format-type value='wrap-round-braces'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes></levels></list-style><list-style ref='ls-2'><name>Numbered</name><unique-id>ERLS-9361f404-031b-43f2-8474-9f5206842e4b</unique-id><levels><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes><level-attributes><margin-pos value='18'/><indent-pos value='18'/><symbol-pos value='0'/><symbol-type value='arabic'/><symbol-format-type value='add-dot'/><symbol-character-attributes><character-style>cs-4</character-style><character-style-variation value='base'/></symbol-character-attributes></level-attributes></levels></list-style><paragraph-style ref='ps-0'><name>Title</name><unique-id>ERPS-f0aad8c3-523e-4b21-b0f3-f81a31dd78a0</unique-id><shortcut>3</shortcut><alignment value='center'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='auto' value='1'/><space-above value='24'/><space-below value='0'/><space-above-top value='yes'/><associated-character-style>cs-0</associated-character-style><next-style-name>Regular</next-style-name><keep-lines-together value='no'/><keep-line-together-type value='separate-first-last'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='2'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-1'><name>Heading</name><unique-id>ERPS-9d6aa8a8-2564-48d2-891c-94e640504a4a</unique-id><shortcut>4</shortcut><alignment value='justify'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='auto' value='1'/><space-above value='11.519999504089355'/><space-below value='8.6399993896484375'/><space-above-top value='yes'/><associated-character-style>cs-1</associated-character-style><next-style-name>First paragraph</next-style-name><keep-lines-together value='no'/><keep-line-together-type value='all'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='2'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-2'><name>Header/footer</name><unique-id>ERPS-ed548d9d-8344-4c9e-8219-57ded150cd3e</unique-id><shortcut/><alignment value='center'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='auto' value='1'/><space-above value='0'/><space-below value='0'/><space-above-top value='yes'/><associated-character-style>cs-2</associated-character-style><keep-lines-together value='no'/><keep-line-together-type value='all'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-3'><name>Body</name><unique-id>ERPS-28555d53-1b0d-492e-ac18-82c87a7a4c1d</unique-id><shortcut>2</shortcut><alignment value='justify'/><margins start='18' end='18' indent='18'/><tab-stops><tab-array><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='fixed' value='16'/><space-above value='0'/><space-below value='0'/><space-above-top value='yes'/><associated-character-style>cs-4</associated-character-style><keep-lines-together value='yes'/><keep-line-together-type value='separate-first-last'/><keep-first-lines-count value='2'/><keep-last-lines-count value='2'/><keep-next-lines-count value='0'/><hyphenate value='yes'/><hyphenation-dictionary-name>US English</hyphenation-dictionary-name><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-4'><name>ToC style</name><unique-id>ERPS-6f941e4a-ce57-45f0-a913-8c2a88afc806</unique-id><shortcut/><alignment value='start'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array><tab-stop type='indent' pos='5.6692914962768555' identi='37'/><tab-stop type='indent' pos='11.338582992553711' identi='38'/><tab-stop type='indent' pos='17.007875442504883' identi='39'/><tab-stop type='indent' pos='22.677165985107422' identi='40'/><tab-stop type='indent' pos='28.346456527709961' identi='41'/><tab-stop type='indent' pos='34.015750885009766' identi='42'/><tab-stop type='indent' pos='39.685039520263672' identi='43'/><tab-stop type='indent' pos='45.354331970214844' identi='44'/><tab-stop type='indent' pos='51.02362060546875' identi='45'/><tab-stop type='decimal' pos='472.96878051757812' align-char='.' leader='dot' identi='46'/></tab-array></tab-stops><line-spacing type='auto' value='1'/><space-above value='0'/><space-below value='0'/><space-above-top value='yes'/><associated-character-style>cs-4</associated-character-style><keep-lines-together value='yes'/><keep-line-together-type value='all'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-5'><name>Sub-heading</name><unique-id>ERPS-ee82c3cf-d1fe-48ed-b963-0a6f5d020d32</unique-id><shortcut>5</shortcut><alignment value='justify'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='auto' value='1'/><space-above value='1.4399999380111694'/><space-below value='5.7599997520446777'/><space-above-top value='yes'/><associated-character-style>cs-5</associated-character-style><next-style-name>First paragraph</next-style-name><keep-lines-together value='no'/><keep-line-together-type value='all'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='2'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-6'><name>First paragraph</name><unique-id>ERPS-06906f45-c6e2-44e0-aa4f-fca7f91d6731</unique-id><shortcut/><alignment value='justify'/><margins start='18' end='18' indent='18'/><tab-stops><tab-array><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='16'/></tab-array></tab-stops><line-spacing type='fixed' value='16'/><space-above value='0'/><space-below value='4.3199996948242188'/><space-above-top value='yes'/><associated-character-style>cs-4</associated-character-style><next-style-name>Regular</next-style-name><keep-lines-together value='yes'/><keep-line-together-type value='separate-first-last'/><keep-first-lines-count value='2'/><keep-last-lines-count value='2'/><keep-next-lines-count value='0'/><hyphenate value='yes'/><hyphenation-dictionary-name>US English</hyphenation-dictionary-name><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-7'><name>Regular</name><unique-id>ERPS-1ed36d81-c0eb-442e-8960-9b3e8b8dd631</unique-id><shortcut>1</shortcut><alignment value='justify'/><margins start='18' end='18' indent='35.990001678466797'/><tab-stops><tab-array><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='16'/></tab-array></tab-stops><line-spacing type='fixed' value='16'/><space-above value='0'/><space-below value='4.3199996948242188'/><space-above-top value='no'/><associated-character-style>cs-4</associated-character-style><keep-lines-together value='yes'/><keep-line-together-type value='separate-first-last'/><keep-first-lines-count value='2'/><keep-last-lines-count value='2'/><keep-next-lines-count value='0'/><hyphenate value='yes'/><hyphenation-dictionary-name>US English</hyphenation-dictionary-name><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-8'><name>-</name><unique-id>ERPS-c995d152-df27-4484-9bee-89856d4f723e</unique-id><shortcut/><alignment value='justify'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array/></tab-stops><line-spacing type='auto' value='1'/><space-above value='0'/><space-below value='0'/><space-above-top value='yes'/><keep-lines-together value='no'/><keep-line-together-type value='all'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-9'><name>Date</name><unique-id>ERPS-0bdb60bb-4e52-478b-a502-73a1bb9fbff9</unique-id><shortcut/><alignment value='center'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array/></tab-stops><line-spacing type='auto' value='1'/><space-above value='18'/><space-below value='0'/><space-above-top value='no'/><associated-character-style>cs-4</associated-character-style><keep-lines-together value='no'/><keep-line-together-type value='all'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-10'><name>Author</name><unique-id>ERPS-36d4387e-023e-45a0-a061-09eea2fcc36d</unique-id><shortcut/><alignment value='center'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array/></tab-stops><line-spacing type='auto' value='1'/><space-above value='10.800000190734863'/><space-below value='10.800000190734863'/><space-above-top value='no'/><associated-character-style>cs-7</associated-character-style><keep-lines-together value='no'/><keep-line-together-type value='all'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-11'><name>Quotation</name><unique-id>ERPS-7e09316a-d4bb-400f-b0d1-f9d7b1791064</unique-id><shortcut/><alignment value='justify'/><margins start='36' end='36' indent='36'/><tab-stops><tab-array/></tab-stops><line-spacing type='fixed' value='16'/><space-above value='0'/><space-below value='4.3199996948242188'/><space-above-top value='no'/><associated-character-style>cs-8</associated-character-style><keep-lines-together value='no'/><keep-line-together-type value='all'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='0'/><hyphenate value='yes'/><hyphenation-dictionary-name>UK English</hyphenation-dictionary-name><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-12'><name>Note text</name><unique-id>ERPS-818e9562-0f32-4b31-b0b0-13ad8a366c82</unique-id><shortcut>6</shortcut><alignment value='start'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array><tab-stop type='indent' pos='18' identi='18'/><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='54' identi='17'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='fixed' value='15'/><space-above value='0'/><space-below value='10'/><space-above-top value='yes'/><associated-character-style>cs-9</associated-character-style><keep-lines-together value='yes'/><keep-line-together-type value='separate-first-last'/><keep-first-lines-count value='2'/><keep-last-lines-count value='2'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name>Basque</hyphenation-dictionary-name><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-13'><name>Note text small</name><unique-id>ERPS-e10b4f4a-8db0-4d77-9dba-e2ba460c32df</unique-id><shortcut>7</shortcut><alignment value='justify'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array><tab-stop type='indent' pos='18' identi='18'/><tab-stop type='indent' pos='36' identi='19'/><tab-stop type='indent' pos='54' identi='20'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='auto' value='1'/><space-above value='0'/><space-below value='10'/><space-above-top value='yes'/><associated-character-style>cs-10</associated-character-style><keep-lines-together value='yes'/><keep-line-together-type value='separate-first-last'/><keep-first-lines-count value='2'/><keep-last-lines-count value='2'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-14'><name>Subnote text</name><unique-id>ERPS-0cd6daa8-7741-4e82-8e42-451a99e2277c</unique-id><shortcut/><alignment value='start'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array><tab-stop type='indent' pos='18' identi='18'/><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='54' identi='17'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='fixed' value='15'/><space-above value='0'/><space-below value='0'/><space-above-top value='yes'/><associated-character-style>cs-9</associated-character-style><keep-lines-together value='yes'/><keep-line-together-type value='separate-first-last'/><keep-first-lines-count value='2'/><keep-last-lines-count value='2'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name>Basque</hyphenation-dictionary-name><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-15'><name>Citation</name><unique-id>ERPS-7ea91a3a-546c-4eb0-a705-0cdc90f6e4bd</unique-id><shortcut/><alignment value='justify'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array/></tab-stops><line-spacing type='auto' value='1'/><space-above value='0'/><space-below value='0'/><space-above-top value='no'/><keep-lines-together value='no'/><keep-line-together-type value='all'/><keep-first-lines-count value='1'/><keep-last-lines-count value='1'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-16'><name>Lists</name><unique-id>ERPS-55837069-b914-4a83-90e2-23440184fca8</unique-id><shortcut/><alignment value='justify'/><margins start='35.990001678466797' end='36' indent='0'/><tab-stops><tab-array><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='fixed' value='16'/><space-above value='0'/><space-below value='0'/><space-above-top value='yes'/><associated-character-style>cs-4</associated-character-style><keep-lines-together value='yes'/><keep-line-together-type value='separate-first-last'/><keep-first-lines-count value='2'/><keep-last-lines-count value='2'/><keep-next-lines-count value='0'/><hyphenate value='yes'/><hyphenation-dictionary-name>US English</hyphenation-dictionary-name><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><paragraph-style ref='ps-17'><name>Numbering</name><unique-id>ERPS-492ff9a0-ed2e-4d8b-b603-3c0397990b9c</unique-id><shortcut/><alignment value='justify'/><margins start='0' end='0' indent='0'/><tab-stops><tab-array><tab-stop type='regular' pos='18' identi='17'/><tab-stop type='regular' pos='36' identi='1'/><tab-stop type='regular' pos='54' identi='16'/><tab-stop type='regular' pos='72' identi='2'/><tab-stop type='regular' pos='90' identi='18'/><tab-stop type='regular' pos='108' identi='3'/><tab-stop type='regular' pos='126' identi='19'/><tab-stop type='regular' pos='144' identi='4'/><tab-stop type='regular' pos='162' identi='20'/><tab-stop type='regular' pos='180' identi='5'/><tab-stop type='regular' pos='216' identi='6'/><tab-stop type='regular' pos='252' identi='7'/><tab-stop type='regular' pos='288' identi='8'/><tab-stop type='regular' pos='324' identi='9'/><tab-stop type='regular' pos='360' identi='10'/><tab-stop type='regular' pos='396' identi='11'/><tab-stop type='regular' pos='432' identi='12'/></tab-array></tab-stops><line-spacing type='auto' value='1'/><space-above value='0'/><space-below value='0'/><space-above-top value='yes'/><associated-character-style>cs-12</associated-character-style><keep-lines-together value='yes'/><keep-line-together-type value='separate-first-last'/><keep-first-lines-count value='2'/><keep-last-lines-count value='2'/><keep-next-lines-count value='0'/><hyphenate value='no'/><hyphenation-dictionary-name/><use-custom-min-values value='no'/><custom-min-word-length value='5'/><custom-min-before-hyphen value='2'/><custom-min-after-hyphen value='2'/><hyphenation-zone value='0'/><hyphenation-limit value='3'/></paragraph-style><page-style ref='pgs-0'><name>Regular</name><unique-id>ERAS-d360619d-75dc-46eb-a9d0-7a824944b0c2</unique-id><page-style-type value='any-page'/><page-number-type value='arabic'/><first-header-visible value='no'/><first-footer-visible value='no'/><odd-attributes><page-color type='calibrated-white' white='1' alpha='1'/><header-visible value='no'/><footer-visible value='no'/><header-text><p style='ps-2' dir='ltr'><c style='cs-2' var='b'>- <page-number/> -<line-break/></c></p></header-text><footer-text><p style='ps-2' dir='ltr'><c style='cs-2' var='b'><line-break/>- <page-number/> -</c></p></footer-text><header-height value='26.8621826171875'/><footer-height value='26.8621826171875'/></odd-attributes><even-attributes><page-color type='calibrated-white' white='1' alpha='1'/><header-visible value='no'/><footer-visible value='no'/><header-text><p style='ps-2' dir='ltr'><c style='cs-2' var='b'>- <page-number/> -<line-break/></c></p></header-text><footer-text><p style='ps-2' dir='ltr'><c style='cs-2' var='b'><line-break/>- <page-number/> -</c></p></footer-text><header-height value='26.86199951171875'/><footer-height value='26.86199951171875'/></even-attributes></page-style><page-style ref='pgs-1'><name>Regular & page</name><unique-id>ERAS-4c776385-67d3-4e05-a92c-4023a8163fe0</unique-id><page-style-type value='even-odd'/><page-number-type value='arabic'/><first-header-visible value='yes'/><first-footer-visible value='yes'/><odd-attributes><page-color type='calibrated-white' white='1' alpha='1'/><header-visible value='yes'/><footer-visible value='yes'/><header-text><p style='ps-2' dir='ltr'><c style='cs-2' var='b'>- <page-number/> -<line-break/></c></p></header-text><footer-text><p style='ps-2' dir='ltr'><c style='cs-2' var='b'><line-break/>- <page-number/> -</c></p></footer-text><header-height value='26.8621826171875'/><footer-height value='26.8621826171875'/></odd-attributes><even-attributes><page-color type='calibrated-white' white='1' alpha='1'/><header-visible value='yes'/><footer-visible value='yes'/><header-text><p style='ps-2' dir='ltr'><c style='cs-2' var='b'>- <page-number/> -<line-break/></c></p></header-text><footer-text><p style='ps-2' dir='ltr'><c style='cs-2' var='b'><line-break/>- <page-number/> -</c></p></footer-text><header-height value='26.86199951171875'/><footer-height value='26.86199951171875'/></even-attributes></page-style><note-style ref='ns-0'><name>Footnote</name><unique-id>ERNS-d33725d6-f107-4569-9687-bc596de48d54</unique-id><reference-symbol-attributes><note-symbol-type value='arabic'/><note-symbol-fromat value='none'/><note-symbol-char-attributes><position value='superscript'/></note-symbol-char-attributes></reference-symbol-attributes><note-symbol-attributes><note-symbol-type value='arabic'/><note-symbol-fromat value='add-dot'/><note-symbol-char-attributes><character-style>cs-9</character-style></note-symbol-char-attributes></note-symbol-attributes><note-symbol-tab value='yes'/><note-text-attributes><paragraph-style>ps-12</paragraph-style><character-style>cs-9</character-style></note-text-attributes><note-position value='bottom-of-column'/><note-splitting-permission value='anywhere'/><indexing-type value='serial'/><may-separate value='no'/><space-above-separator value='14'/><space-below-separator value='10'/><separator-placment value='left'/><separator-line-type value='solid'/><separator-color type='calibrated-white' white='0' alpha='1'/><separator-weight value='1'/><separator-coverage value='30'/></note-style><note-style ref='ns-1'><name>Footnote small</name><unique-id>ERNS-63ec112a-e8ab-4335-b603-0bf05f314129</unique-id><reference-symbol-attributes><note-symbol-type value='arabic'/><note-symbol-fromat value='none'/><note-symbol-char-attributes><position value='superscript'/></note-symbol-char-attributes></reference-symbol-attributes><note-symbol-attributes><note-symbol-type value='arabic'/><note-symbol-fromat value='add-dot'/><note-symbol-char-attributes><character-style>cs-10</character-style></note-symbol-char-attributes></note-symbol-attributes><note-symbol-tab value='yes'/><note-text-attributes><paragraph-style>ps-13</paragraph-style><character-style>cs-10</character-style></note-text-attributes><note-position value='bottom-of-column'/><note-splitting-permission value='anywhere'/><indexing-type value='serial'/><may-separate value='no'/><space-above-separator value='14'/><space-below-separator value='10'/><separator-placment value='left'/><separator-line-type value='solid'/><separator-color type='calibrated-white' white='0' alpha='1'/><separator-weight value='1'/><separator-coverage value='30'/></note-style><note-style ref='ns-2'><name>Endnote</name><unique-id>ERNS-bab0d83e-db56-4616-b2eb-a5f7e796f5c3</unique-id><reference-symbol-attributes><note-symbol-type value='arabic'/><note-symbol-fromat value='none'/><note-symbol-char-attributes><position value='superscript'/></note-symbol-char-attributes></reference-symbol-attributes><note-symbol-attributes><note-symbol-type value='arabic'/><note-symbol-fromat value='add-dot'/><note-symbol-char-attributes><character-style>cs-9</character-style></note-symbol-char-attributes></note-symbol-attributes><note-symbol-tab value='yes'/><note-text-attributes><paragraph-style>ps-12</paragraph-style><character-style>cs-9</character-style></note-text-attributes><note-position value='end-of-document'/><note-splitting-permission value='anywhere'/><indexing-type value='serial'/><may-separate value='no'/><space-above-separator value='0'/><space-below-separator value='10'/><separator-placment value='none'/><separator-line-type value='solid'/><separator-color type='calibrated-white' white='0' alpha='1'/><separator-weight value='1'/><separator-coverage value='30'/></note-style><note-style ref='ns-3'><name>Endnote small</name><unique-id>ERNS-50755ab9-af3d-486f-a316-b6fc8026a2f0</unique-id><reference-symbol-attributes><note-symbol-type value='arabic'/><note-symbol-fromat value='none'/><note-symbol-char-attributes><position value='superscript'/></note-symbol-char-attributes></reference-symbol-attributes><note-symbol-attributes><note-symbol-type value='arabic'/><note-symbol-fromat value='add-dot'/><note-symbol-char-attributes><character-style>cs-10</character-style></note-symbol-char-attributes></note-symbol-attributes><note-symbol-tab value='yes'/><note-text-attributes><paragraph-style>ps-13</paragraph-style><character-style>cs-10</character-style></note-text-attributes><note-position value='end-of-document'/><note-splitting-permission value='anywhere'/><indexing-type value='serial'/><may-separate value='no'/><space-above-separator value='0'/><space-below-separator value='0'/><separator-placment value='none'/><separator-line-type value='solid'/><separator-color type='calibrated-white' white='0' alpha='1'/><separator-weight value='1'/><separator-coverage value='30'/></note-style><note-stream ref='nsm-0'><name>Footnote</name><unique-id>note stream:-1191101285</unique-id><shortcut>N</shortcut><start-at value='1'/><attributes><note-style>ns-2</note-style></attributes></note-stream></pooled-objects><root><new-selection><anchor value='55'/><ending value='55'/><leading-edge value='yes'/></new-selection><document-setup><dictionary><screen-background-color type='calibrated-white' white='1' alpha='1'/><inner-margin value='72'/><outer-margin value='72'/><facing-pages value='no'/><binding-direction value='ltr'/><top-margin value='72'/><use-screen-background-color value='no'/><bottom-margin value='72'/></dictionary></document-setup><outline-settings><outline-open value='yes'/><outline-view-width value='150'/><outline-state><display-tags-separately value='yes'/><disclosure-states><element value='yes'/><element value='yes'/><element value='yes'/><element value='yes'/><element value='yes'/><element value='yes'/><element value='yes'/></disclosure-states><tag-dictionaries><element><tag-level value='-1'/><tag-tree-open value='yes'/><tag-index value='-1'/></element><element><tag-level value='0'/><tag-tree-open value='yes'/><tag-index value='1'/></element><element><tag-level value='0'/><tag-tree-open value='yes'/><tag-index value='2'/></element><element><tag-level value='0'/><tag-tree-open value='yes'/><tag-index value='3'/></element><element><tag-level value='0'/><tag-tree-open value='yes'/><tag-index value='4'/></element><element><tag-level value='0'/><tag-tree-open value='yes'/><tag-index value='5'/></element></tag-dictionaries></outline-state></outline-settings><misc-settings><print-markings value='no'/><doc-export-markings value='no'/><auto-title-sheet-rtl value='no'/><rtf-export-markings value='no'/></misc-settings><marker-names><element>Banana</element><element>Salmon</element><element>Cantaloupe</element><element>Lime</element><element>Sky</element><element>Light Lavender</element><element>Magnesium</element><element>Midnight</element></marker-names><print-info><data>040B73747265616D747970656481E803840140848484134E534D757461626C6544696374696F6E6172790084840C4E5344696374696F6E617279008484084E534F626A65637400858401691B92848484084E53537472696E67019584012B104E534A6F62446973706F736974696F6E86928497980F4E535072696E7453706F6F6C4A6F6286928497980B4E53506170657253697A658692848484074E5356616C7565009584012A84840C7B5F4E5353697A653D66667D9B81640281180386928497980D4E534D757374436F6C6C6174658692848484084E534E756D626572009B9A848401639D018692849798144E53566572746963616C506167696E6174696F6E8692849F9A8496960086928497980D4E535072696E7465724E616D658692849798184550534F4E205374796C75732050686F746F20525835303086928497980B4E535072696E7454696D658692848484064E5344617465009584016483000000DCC0632DC286928497980D4E5350616765734163726F73738692849F9AA396018692849798144E53566572746963616C6C7943656E74657265648692AA928497980F4E535072696E74416C6C50616765738692AA928497980B4E5350617065724E616D658692849798096E612D6C657474657286928497980F4E535363616C696E67466163746F728692849F9A84840166A0018692849798084E53436F706965738692AA92849798094E535072696E7465728692848484094E535072696E746572009592A58692849798104E535072696E7450726F7465637465648692849F9AA09D008692849798154E53486F72697A6F6E616C506167696E6174696F6E8692849F9AA396028692849798164E53486F72697A6F6E74616C6C7943656E74657265648692AA928497980B4E534661784E756D62657286928497980086928497980E4E53426F74746F6D4D617267696E8692849F9AB1A00086928497980B4E53546F704D617267696E8692849F9AB1A00086928497980B4E534669727374506167658692AA928497980A4E534C617374506167658692849F9AA39682FFFFFF7F86928497980C4E534C6566744D617267696E8692849F9AB1A0008692849798184E5344657461696C65644572726F725265706F7274696E678692B7928497980D4E5352696768744D617267696E8692849F9AB1A00086928497980A4E53536176655061746886928497980086928497980B4E535061676573446F776E8692AA928497980D4E534F7269656E746174696F6E8692A286</data></print-info><document-info><variables><variable>Notes on the Seven Valleys</variable><variable><subject></variable><variable>John Wiegley</variable><variable>jwiegley@gmail.com</variable><variable>http://johnwiegley.com</variable><variable><variable#6></variable><variable><variable#7></variable><variable><variable#8></variable><variable><variable#9></variable><variable>Address Line 1</variable><variable>Address Line 2</variable><variable>Address Line 3</variable><variable>Ret. Add. Ln 1</variable><variable>Ret. Add. Ln 2</variable><variable>Ret. Add. Ln 3</variable><variable><variable#16></variable><variable><variable#17></variable><variable><variable#18></variable><variable><variable#19></variable><variable><variable#20></variable></variables><keywords>mysticism sufism bahai valleys</keywords><category><category></category><comments><comments></comments></document-info><bibliography-should-generate-bibliography value='yes'/><text-model version='2'><document-text><page-range style='pgs-0'><section style='ss-0' column-order='ltr'><p style='ps-0' dir='ltr'><c style='cs-0'>Ledger</c></p><p style='ps-1' dir='ltr'><c style='cs-1'><autotitle level='0' index='0'><c style='cs-1'>Introduction</c></autotitle></c></p><p style='ps-1' dir='ltr'><c style='cs-1'><autotitle level='0' index='0'><c style='cs-1'>Tutorial</c></autotitle></c></p><p style='ps-1' dir='ltr'><c style='cs-1'><autotitle level='0' index='0'><c style='cs-1'>Anatomy of a journal file</c></autotitle></c></p><p style='ps-1' dir='ltr'><c style='cs-1'><autotitle level='0' index='0'><c style='cs-1'>The reporting commands</c></autotitle></c></p><p style='ps-1' dir='ltr'><c style='cs-1'><autotitle level='0' index='0'><c style='cs-1'>Using XPath expressions</c></autotitle></c></p><p style='ps-1' dir='ltr'><c style='cs-1'><autotitle level='0' index='0'><c style='cs-1'>Scripting with Python</c></autotitle></c></p><p style='ps-1' dir='ltr'><c style='cs-1'><autotitle level='0' index='0'><c style='cs-1'>Ledger’s architecture</c></autotitle></c></p></section></page-range></document-text><note-streams><streams><stream>nsm-0</stream></streams><height-limit value='100'/><mark-notes-on-screen value='no'/><mark-notes-on-print value='no'/></note-streams><auto-title-setup><name>Essay</name><levels><level><flow><name>Level 1</name><main-format><elements><element><type>curr-level</type><specifier value='0'/><character-style>cs-1</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>. </text><specifier value='0'/><character-style>cs-1</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-1</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-1</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-1</paragraph-style></main-format><mention-format><elements><element><type>curr-level</type><specifier value='0'/><character-style>cs-2</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>. </text><specifier value='0'/><character-style>cs-2</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-2</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-2</paragraph-style></mention-format><prompt-for-title value='yes'/><number-type value='arabic'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='yes'/></flow><flow><name>Chart</name><main-format><elements><element><type>free-text</type><text>Chart </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-3</paragraph-style></main-format><toc-format><elements><element><type>free-text</type><text>Chart </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>page-number</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-4</paragraph-style></toc-format><prompt-for-title value='yes'/><number-type value='arabic'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='yes'/></flow><flow><name>Equation</name><main-format><elements><element><type>free-text</type><text>Equation </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-3</paragraph-style></main-format><toc-format><elements><element><type>free-text</type><text>Equation </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>page-number</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-4</paragraph-style></toc-format><prompt-for-title value='yes'/><number-type value='arabic'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='yes'/></flow><flow><name>Figure</name><main-format><elements><element><type>free-text</type><text>Figure </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-3</paragraph-style></main-format><toc-format><elements><element><type>free-text</type><text>Figure </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>page-number</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-4</paragraph-style></toc-format><prompt-for-title value='yes'/><number-type value='arabic'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='yes'/></flow><flow><name>Picture</name><main-format><elements><element><type>free-text</type><text>Picture </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-3</paragraph-style></main-format><toc-format><elements><element><type>free-text</type><text>Picture </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>page-number</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-4</paragraph-style></toc-format><prompt-for-title value='yes'/><number-type value='arabic'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='yes'/></flow><flow><name>Table</name><main-format><elements><element><type>free-text</type><text>Table </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-3</paragraph-style></main-format><toc-format><elements><element><type>free-text</type><text>Table </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>: </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>page-number</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-4</paragraph-style></toc-format><prompt-for-title value='yes'/><number-type value='arabic'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='yes'/></flow></level><level><flow><name>Level 2</name><main-format><elements><element><type>title</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-5</paragraph-style></main-format><mention-format><elements><element><type>curr-level</type><specifier value='0'/><character-style>cs-2</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>. </text><specifier value='0'/><character-style>cs-2</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-2</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-2</paragraph-style></mention-format><toc-format><elements><element><type>tab</type><specifier value='0'/><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>page-number</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-4</paragraph-style></toc-format><prompt-for-title value='yes'/><number-type value='lain-small'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='yes'/></flow></level><level><flow><name>Level 3</name><main-format><elements><element><type>curr-level</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='b'/></element><element><type>free-text</type><text>) </text><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='b'/></element><element><type>title</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='b'/></element></elements><paragraph-style>ps-5</paragraph-style></main-format><toc-format><elements><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>. </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>page-number</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-4</paragraph-style></toc-format><prompt-for-title value='yes'/><number-type value='lain-small'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='yes'/></flow></level><level><flow><name>Level 4</name><main-format><elements><element><type>tab</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>(</text><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>) </text><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-5</paragraph-style></main-format><toc-format><elements><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>. </text><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element><element><type>page-number</type><specifier value='0'/><character-style>cs-4</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-4</paragraph-style></toc-format><prompt-for-title value='yes'/><number-type value='roman-small'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='yes'/></flow></level><level><flow><name>Level 5</name><main-format><elements><element><type>tab</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>(</text><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>) </text><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-5</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-5</paragraph-style></main-format><prompt-for-title value='no'/><number-type value='arabic'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='no'/></flow></level><level><flow><name>Level 6</name><main-format><elements><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>free-text</type><text>) </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element></elements><paragraph-style>ps-5</paragraph-style></main-format><prompt-for-title value='no'/><number-type value='lain-small'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='no'/></flow></level><level><flow><name>Level 7</name><main-format><elements><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>free-text</type><text>) </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element></elements><paragraph-style>ps-5</paragraph-style></main-format><prompt-for-title value='no'/><number-type value='roman-small'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='no'/></flow></level><level><flow><name>Level 8</name><main-format><elements><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>free-text</type><text>) </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='b'/></element></elements><paragraph-style>ps-5</paragraph-style></main-format><prompt-for-title value='no'/><number-type value='arabic'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='no'/></flow></level><level><flow><name>Level 9</name><main-format><elements><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>) </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-5</paragraph-style></main-format><prompt-for-title value='no'/><number-type value='lain-small'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='no'/></flow></level><level><flow><name>Level 10</name><main-format><elements><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>tab</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>curr-level</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>free-text</type><text>) </text><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element><element><type>title</type><specifier value='0'/><character-style>cs-3</character-style><character-style-variation value='base'/></element></elements><paragraph-style>ps-5</paragraph-style></main-format><prompt-for-title value='no'/><number-type value='roman-small'/><number-start-at value='1'/><number-increment value='1'/><include-in-toc value='no'/></flow></level></levels></auto-title-setup><style-set><name>Essay</name><unique-id>ERSS-46432b76-59bf-4b49-95a3-8d89c0fd8b88</unique-id><locking-state value='unlocked'/><character-styles><style>cs-4</style><style>cs-6</style><style>cs-0</style><style>cs-7</style><style>cs-1</style><style>cs-5</style><style>cs-6</style><style>cs-8</style><style>cs-9</style><style>cs-10</style><style>cs-11</style><style>cs-6</style><style>cs-2</style><style>cs-12</style><style>cs-13</style></character-styles><paragraph-styles><style>ps-6</style><style>ps-7</style><style>ps-3</style><style>ps-8</style><style>ps-0</style><style>ps-9</style><style>ps-10</style><style>ps-1</style><style>ps-5</style><style>ps-8</style><style>ps-11</style><style>ps-12</style><style>ps-13</style><style>ps-14</style><style>ps-15</style><style>ps-8</style><style>ps-2</style><style>ps-16</style><style>ps-17</style><style>ps-4</style></paragraph-styles><list-styles><style>ls-0</style><style>ls-1</style><style>ls-2</style></list-styles><section-styles><style>ss-0</style><style>ss-1</style><style>ss-2</style><style>ss-3</style></section-styles><page-styles><style>pgs-0</style><style>pgs-1</style></page-styles><note-styles><style>ns-0</style><style>ns-1</style><style>ns-2</style><style>ns-3</style></note-styles><set-seed>41A771082020561D</set-seed><default-character-style/><default-paragraph-style/><default-list-style/><default-section-style/><default-page-style/><default-note-style/></style-set></text-model><view-options><show-options><space value='no'/><header-and-footer-frames value='yes'/><section-break value='no'/><paragraph-break value='no'/><autotitle-frame value='no'/><toolbar value='yes'/><tab value='no'/><line-break value='no'/><page-break value='no'/><soft-hyphen value='no'/><column-break value='no'/><pageStyle-break value='no'/><invisible-table-lines value='yes'/><paragraph-ruler value='yes'/><page-margins value='yes'/><citation-frames value='yes'/></show-options><compact-view-mode value='no'/><window-position>73 0 1092 878 0 0 1440 878 </window-position><zoom-mode value='explicit'/><zoom value='150'/></view-options></root></archive>
\ No newline at end of file diff --git a/docs/date-examples.txt b/docs/date-examples.txt deleted file mode 100644 index 2c2afe94..00000000 --- a/docs/date-examples.txt +++ /dev/null @@ -1,42 +0,0 @@ -2002-02-02 -2002/02/02 -2002.02.02 -02-02-2002 -02/02/2002 -02.02.2002 -02-02-02 -02/02/02 -02.02.02 -02-02 -02/02 -02.02 -20020202 -20020202T023318 -20020202T023318-0700 -20020202T023318-0100 -02-Feb-2002 -2002-Feb-02 -02 Feb 2002 -02-Feb-2002 -02 February 2002 -02-February-2002 -2002 Feb 02 -2002-Feb-02 -2002 February 02 -2002-February-02 -02 Feb -02-Feb -02 February -02-February -Feb 02 -Feb-02 -February 02 -February-02 -Feb 02, 2002 -February 02, 2002 -2002-02-02 12:00:00 -2002-02-02 12:00:00 AM -2002-02-02 12:00 AM -2002-02-02 12:00AM -2002-02-02 12p -2002-02-02 12a diff --git a/docs/ledger.info b/docs/ledger.info deleted file mode 100644 index 651f5d91..00000000 --- a/docs/ledger.info +++ /dev/null @@ -1,3640 +0,0 @@ -This is /Users/johnw/src/ledger/docs/ledger.info, produced by makeinfo -version 4.7 from /Users/johnw/src/ledger/docs/ledger.texi. - -INFO-DIR-SECTION User Applications - Copyright (c) 2003-2006, 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. - -START-INFO-DIR-ENTRY -* Ledger: (ledger). Command Line Accounting -END-INFO-DIR-ENTRY - - -File: ledger.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) - -Overview -******** - -Copyright (c) 2003-2006, 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. - -* Menu: - -* Introduction:: -* Running Ledger:: -* Keeping a ledger:: -* Using XML:: - - -File: ledger.info, Node: Introduction, Next: Running Ledger, Prev: Top, Up: Top - -1 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. _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: - - 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 - - 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.(1) - - 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: - - 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 - - The account balances and registers in this file, if saved as -`ledger.dat', could be reported using: - - $ ledger -f ledger.dat balance - $ ledger -f ledger.dat register checking - $ ledger -f ledger.dat register bell - -* Menu: - -* Building the program:: -* Getting help:: - - ---------- Footnotes ---------- - - (1) In some special cases, it automatically balances this entry for -you. - - -File: ledger.info, Node: Building the program, Next: Getting help, Prev: Introduction, Up: Introduction - -1.1 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: - - ./configure && make install - - -File: ledger.info, Node: Getting help, Prev: Building the program, Up: Introduction - -1.2 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: - - https://lists.sourceforge.net/lists/listinfo/ledger-discuss - - You can also find help at the `#ledger' channel on the IRC server -`irc.freenode.net'. - - -File: ledger.info, Node: Running Ledger, Next: Keeping a ledger, Prev: Introduction, Up: Top - -2 Running Ledger -**************** - -Ledger has a very simple command-line interface, named--enticing -enough--`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: - - ledger [OPTIONS...] COMMAND [ARGS...] - - 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 `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 `--'. For example, the following -balance command reports account totals for rent, food and movies, but -only those whose payee matches Freddie: - - ledger bal rent food movies -- freddie - - There are many, many command options available with the `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:: - - -File: ledger.info, Node: Usage overview, Next: Commands, Prev: Running Ledger, Up: Running Ledger - -2.1 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 -LEDGER is set to the file `sample.dat' (which is included in the -distribution), and that the contents of that file are: - - = /^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 - - 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. - -2.1.1 Checking balances ------------------------ - -Ledger has seven basic commands, but by far the most often used are -`balance' and `register'. To see a summary balance of all accounts, -use: - - ledger bal - - `bal' is a short-hand for `balance'. This command prints out the -summary totals of the five parent accounts used in `sample.dat': - - $1,480.00 - 50 AAPL Assets - $-2,500.00 Equity - $20.00 Expenses - $-500.00 Income - $-2.00 Liabilities - -------------------- - $-1,502.00 - 50 AAPL - - None of the child accounts are shown, just the parent account totals. -We can see that in `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(1). 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 `--real' option: - - ledger --real bal - - Now the report is: - - $1,480.00 - 50 AAPL Assets - $-2,500.00 Equity - $20.00 Expenses - $-500.00 Income - -------------------- - $-1,500.00 - 50 AAPL - - 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 `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 `--basis', or `-B', option: - - ledger --real -B bal - - This command reports: - - $2,980.00 Assets - $-2,500.00 Equity - $20.00 Expenses - $-500.00 Income - - 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, -_which must always be true_. Reporting the real basis cost should -never yield a remainder(2). - -2.1.1.1 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 -`-s' option: - - ledger --real -B -s bal - - This reports: - - $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 - - This shows that the `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, -`T' represents the reported total, and `l' is the display level for the -account: - - ledger --real -B -d "T&l<=2" bal - - This reports: - - $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 - - Instead of reporting `Bank:Checking' as a child of `Assets', it -report only `Bank', since that account is a nesting level of 2, while -`Checking' is at level 3. - - To review the display predicate used--`T&l<=2'--this rather terse -expression means: Display an account only if it has a non-zero total -(`T'), and its nesting level is less than or equal to 2 (`l<=2'). - -2.1.1.2 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: - - ledger bal checking - - Reports: - - $1,480.00 Assets:Bank:Checking - - Any number of names may be used: - - ledger bal checking broker liab - - Reports: - - $1,480.00 Assets:Bank:Checking - 50 AAPL Assets:Brokerage - $-2.00 Liabilities - - 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: - - ledger bal ^assets.*checking ^liab - - Reports: - - $1,480.00 Assets:Bank:Checking - $-2.00 Liabilities:Taxes - -2.1.2 The register report -------------------------- - -While the `balance' command can be very handy for checking account -totals, by far the most powerful of Ledger's reporting tools is the -`register' command. In fact, internally both commands use the same -logic, but report the results differently: `balance' shows the summary -totals, while `register' reports each transaction and how it -contributes to that total. - - Paradoxically, the most basic form of `register' is almost never -used, since it displays every transaction: - - ledger reg - - `reg' is a short-hand for `register'. This command reports: - - 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 - - This rather verbose output shows every account transaction in -`sample.dat', and how it affects the running total. The final total is -identical to what we saw with the plain `balance' command. To see how -things really balance, we can use `--real -B', just as we did with -`balance': - - ledger --real -B reg - - Reports: - - 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 - - Here we see that everything balances to zero in the end, as it must. - -2.1.2.1 Specific register queries -................................. - -The most common use of the register command is to summarize -transactions based on the account(s) they affect. Using `sample.dat' -as as example, we could look at all book purchases using: - - ledger reg books - - Reports: - - 2004/05/29 Book Store Expenses:Books $20.00 $20.00 - - If a double-dash (`--') occurs in the list of regular expressions, -any following arguments are matched against payee names, instead of -account names: - - ledger reg ^liab -- credit - - Reports: - - 2004/05/29 Credit card company Liabilities:MasterCard $20.00 $20.00 - - 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. - -2.1.3 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 `--help-calc'. - -2.1.3.1 By date -............... - -`--current'(`-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. - - `--begin DATE' (`-b DATE') limits the report to only those entries -occurring on or after 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 `-d 'd>=[DATE]''): - - ledger --basis -b may -d 'd>=[5/14]' reg ^assets - - Reports: - - 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 - - In this example, the displayed transactions start from `5/14', but -the calculated total starts from the beginning of `may'. - - `--end DATE' (`-e DATE') states when reporting should end, both -calculation and display. The ending date is inclusive. - - The DATE argument to the `-b' and `-e' options can be rather -flexible. Assuming the current date to be November 15, 2004, then all -of the following are equivalent: - - 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 - - To constrain the report to a specific time period, use `--period' -(`-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: - - 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 - - See *Note Period expressions:: for more on syntax. Also, all of the -options `-b', `-e' and `-p' may be used together, but whatever -information occurs last takes priority. An example of such usage (in a -script, perhaps) would be: - - ledger -b 2004 -e 2005 -p monthly reg ^expenses - - This command is identical to: - - ledger -p "monthly in 2004" reg ^expenses - - The transactions within a period may be sorted using -`--period-sort', which takes a value expression. This is similar to -the `--sort' option, except that it sorts within each period entry, -rather than sorting all transactions in the report. See the -documentation on `--sort' below for more details. - -2.1.3.2 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: - -`-C, --cleared' - Consider only cleared transactions. - -`-U, --uncleared' - Consider only uncleared and pending transactions. - -`-R, --real' - Consider only real (non-virtual) transactions. - -`-L, --actual' - Consider only actual (non-automated) transactions. - - 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: - - ledger --budget --actual reg ^expenses - - This command outputs all transactions affecting a budgeted account, -but without subtracting the budget amount (because the generated -transactions are suppressed with `--actual'). The report shows how -much you actually spent on budgeted items. - -2.1.3.3 By relationship -....................... - -Normally, a register report includes only the transactions that match -the regular expressions specified after the command word. For example, -to report all expenses: - - ledger reg ^expenses - - This reports: - - 2004/05/29 Book Store Expenses:Books $20.00 $20.00 - - Using `--related' (`-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: - - ledger -r reg ^expenses - - Reports: - - 2004/05/29 Book Store Liabilities:MasterCard $20.00 $20.00 - -2.1.3.4 By budget -................. - -There is more information about budgeting and forecasting in *Note -Budgeting and forecasting::. Basically, if you have any period entries -in your ledger file, you can use these options. A period entry looks -like: - - ~ Monthly - Assets:Bank:Checking $500.00 - Income:Salary - - 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 -(*Note 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 `--budget' option will -report only transactions that match a budgeted account. Using -`sample.dat' from above: - - ledger --budget reg ^income - - Reports: - - 2004/05/01 Budget entry Income:Salary $500.00 $500.00 - 2004/05/14 Pay day Income:Salary $-500.00 0 - - 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 `--budget -p -monthly'. - - The `--add-budget' option reports all matching transactions in -addition to budget transactions; while `--unbudgeted' shows only those -that don't match a budgeted account. To summarize: - -`--budget' - Show transactions matching budgeted accounts. - -`--unbudgeted' - Show transactions matching unbudgeted accounts. - -`--add-budget' - Show both budgeted and unbudgeted transactions together (i.e., add - the generated budget transactions to the regular report). - - A report with the `--forecast' option will add budgeted transactions -while the specified value expression is true. For example: - - ledger --forecast 'd<[2005] reg ^income - - Reports: - - 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 - - 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: - - ledger --forecast 'd<[2008]' -p yearly reg ^inc ^exp - - This reports balances projected income against projected expenses, -showing the resulting total in yearly intervals until 2008. For the -case of `sample.dat', which has no budgeted expenses, the result of the -above command (in November 2004) is: - - 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 - -2.1.3.5 By value expression -........................... - -Value expressions can be quite complex, and are treated more fully in -*Note Value expressions::. They can be used for limiting a report with -`--limit' (`-l'). The following command report income since august, -but expenses since october: - - ledger -l '(/income/&d>=[aug])|(/expenses/&d>=[oct])' reg - - The basic form of this value expression is `(A&B)|(A&B)'. The `A' -in each part matches against an account name with `/name/', while each -`B' part compares the date of the transaction (`d') with a specified -month. The resulting report will contain only transactions which match -the value expression. - - 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: - - ledger -t 'a/2' reg ^exp - - The `-t' option doesn't affect the running total, only how the -transaction amount is displayed. To change the running total, use -`-T'. In that case, you will likely want to use the total (`O') -instead of the amount (`a'): - - ledger -T 'O/2' reg ^exp - -2.1.4 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 `--help-disp'. - -2.1.4.1 Summarizing -................... - -When multiple transactions relate to a single entry, they are reported -as part of that entry. For example, in the case of `sample.dat': - - ledger reg -- book - - Reports: - - 2004/05/29 Book Store Expenses:Books $20.00 $20.00 - Liabilities:MasterCard $-20.00 0 - (Liabilities:Taxes) $-2.00 $-2.00 - - 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 `-n' to collapse entries with multiple transactions: - - ledger -n reg -- book - - Reports: - - 2004/05/29 Book Store <Total> $-2.00 $-2.00 - - In the balance report, `-n' causes the grand total not to be -displayed at the bottom of the report. - - If an account occurs more than once in a report, it is possible to -combine them all and report the total per-account, using `-s'. For -example, this command: - - ledger -B reg ^assets - - Reports: - - 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 - - But if the `-s' option is added, the result becomes: - - 2004/05/01 - 2004/05/29 Assets:Bank:Checking $1,480.00 $1,480.00 - Assets:Brokerage $1,500.00 $2,980.00 - - When account subtotaling is used, only one entry is printed, and the -date and name reflect the range of the combined transactions. - - With `-P', transactions relating to the same payee are combined. In -this case, the date of the combined entry is that of the latest -transaction. - - `-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 `-P'. For example: - - ledger -Px reg ^assets - - Reports: - - 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 - - This reports shows the subtotal for each commodity held, and where it -is located. To see the basis cost, or initial investment, add `-B'. -Applied to the example above: - - 2004/05/29 $ Assets:Bank:Checking $1,480.00 $1,480.00 - 2004/05/01 AAPL Assets:Brokerage $1,500.00 $2,980.00 - - The only other options which affect summarized totals is `-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. - -2.1.4.2 Quick periods -..................... - -Although the `-p' option (also `--period') is much more versatile, -there are other options to make the most common period reports easier: - -`-W, --weekly' - Show weekly sub-totals. Same as `-p weekly'. - -`-M, --monthly' - Show monthly sub-totals. Same as `-p monthly'. - -`-Y, --yearly' - Show yearly sub-totals. Same as `-p yearly'. - - There is one kind of period report cannot be done with `-p'. This -is the `--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: - - ledger --dow reg ^inc ^exp - - Reports: - - 2004/05/27 Thursdays Expenses:Books $20.00 $20.00 - 2004/05/14 Fridays Income:Salary $-500.00 $-480.00 - -2.1.4.3 Ordering and width -.......................... - -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 `--sort' 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: - - 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 - - For the balance report, you will want to use `T' instead of `t': - - 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 - - The `--sort' options sorts all transactions in a report. If periods -are used (such as `--monthly'), this can get somewhat confusing. In -that case, you'll probably want to sort within periods using -`--period-sort' instead of `--sort'. - - And if the register seems too cramped, and you have a lot of screen -real estate, you can use `-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 `--head' and/or `--tail' options. The two options may -be used simultaneously, for example: - - ledger --tail 20 reg checking - - If the output from your command is very long, Ledger can output the -data to a pager utility, such as `more' or `less': - - ledger --pager /usr/bin/less reg checking - -2.1.4.4 Averages and percentages -................................ - -To see the running total changed to a running average, use `-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: - - ledger -AM reg ^expenses:food - ledger -AMn reg ^expenses - - This works in the balance report too: - - ledger -AM bal ^expenses:food - ledger -AMs bal ^expenses - - The `-D' option changes the running average into a deviation from -the running average. This only makes sense in the register report, -however. - - ledger -DM reg ^expenses:food - - In the balance report only, `-%' 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: - - ledger -%s -S T bal ^expenses - -2.1.4.5 Reporting total data -............................ - -Normally in the `xml' report, only transaction amounts are printed. To -include the running total under a `<total>' tag, use `--totals'. This -does not affect any other report. - - In the register report only, the output can be changed with `-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 `-J'. - -2.1.4.6 Display by value expression -................................... - -With `-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: - - ledger -d 'd>=[last month]' reg checking - - This command shows the checking account's register, beginning from -last month, but with the running total reflecting the entire history of -the account. - -2.1.4.7 Change report format -............................ - -When dates are printed in any report, the default format is `%Y/%m/%d', -which yields dates of the form `YYYY/mm/dd'. This can be changed with -`-y', whose argument is a `strftime' string--see your system's C -library documentation for the allowable codes. Mostly you will want to -use `%Y', `%m' and `%d', in whatever combination is convenient for your -locale. - - To change the format of the entire reported line, use `-F'. It -supports quite a large number of options, which are all documented in -*Note Format strings::. In addition, each specific kind of report -(except for `xml') can be changed using one of the following options: - -`--balance-format' - `balance' report. Default: - %20T %2_%-a\n - -`--register-format' - `register' report. Default: - %D %-.20P %-.22A %12.66t %12.80T\n%/%32|%-.22A %12.66t %12.80T\n - -`--print-format' - `print' report. Default: - %D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n - -`--plot-amount-format' - `register' report when `-j' (plot amount) is used. Default: - %D %(St)\n - -`--plot-total-format' - `register' report when `-J' (plot total) is used. Default: - %D %(ST)\n - -`--equity-format' - `equity' report. Default: - \n%D %Y%C%P\n %-34W %12o%n\n%/ %-34W %12o%n\n - -`--prices-format' - `prices' report. Default: - \n%D %Y%C%P\n%/ %-34W %12t\n - -`--wide-register-format' - `register' report when `-w' (wide) is used. Default: - %D %-.35P %-.38A %22.108t %22.132T\n%/%48|%-.38A %22.108t %22.132T\n - -2.1.5 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 _net worth_ can be determined by balancing assets against -liabilities: - - ledger bal ^assets ^liab - - By removing long-term investment and loan accounts, you can see your -current net liquidity (or liquid net worth): - - ledger bal ^assets ^liab -retirement -brokerage -loan - - Balancing expenses against income yields your _cash flow_, or net -profit/loss: - - ledger bal ^exp ^inc - - In this case, if the number is positive it means you spent more than -you earned during the report period. - - The most often used command is the "balance" command: - - export LEDGER=/home/johnw/doc/ledger.dat - ledger balance - - Here I've set my Ledger environment variable to point to where my -ledger file is hiding. Thereafter, I needn't specify it again. - -2.1.6 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: - - ledger balance expenses:food - - 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: - - ledger -p sep balance expenses:food - - Or maybe you want to see all of your assets, in which case the -s -(show sub-accounts) option comes in handy: - - ledger -s balance ^assets - - To exclude a particular account, use a regular expression with a -leading minus sign. The following will show all expenses, but without -food spending: - - ledger balance expenses -food - -2.1.7 Reporting percentages ---------------------------- - -There is no built-in way to report transaction amounts or account -balances in terms of percentages - - ---------- Footnotes ---------- - - (1) It is impossible for accounts not to balance in ledger; it -reports an error if a transaction does not balance - - (2) If it ever does, then generated transactions are involved, which -can be removed using `--actual' - - -File: ledger.info, Node: Commands, Next: Options, Prev: Usage overview, Up: Running Ledger - -2.2 Commands -============ - -2.2.1 balance -------------- - -The `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. - -2.2.2 register --------------- - -The `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 `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 `report', which is included -in the Ledger distribution. The only requirement is that you add -either `-j' or `-J' to your register command, in order to plot either -the amount or total column, respectively. - -2.2.3 print ------------ - -The `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 `print' command can be a handy way to clean up a ledger file -whose formatting has gotten out of hand. - -2.2.4 output ------------- - -The `output' command is very similar to the `print' command, except -that it attempts to replicate the specified ledger file exactly. The -format of the command is: - - ledger -f FILENAME output FILENAME - - Where `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 `print' command). - -2.2.5 xml ---------- - -The `xml' command outputs results similar to what `print' and -`register' display, but as an XML form. This data can then be read in -and processed. Use the `--totals' option to include the running total -with each transaction. - -2.2.6 emacs ------------ - -The `emacs' command outputs results in a form that can be read directly -by Emacs Lisp. The format of the sexp is: - - ((BEG-POS CLEARED DATE CODE PAYEE - (ACCOUNT AMOUNT)...) ; list of transactions - ...) ; list of entries - -2.2.7 equity ------------- - -The `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 *Note Archiving previous years::. - -2.2.8 prices ------------- - -The `prices' command displays the price history for matching -commodities. The `-A' flag is useful with this report, to display the -running average price, or `-D' to show each price's deviation from that -average. - - There is also a `pricesdb' command which outputs the same -information as `prices', but does in a format that can be parsed by -Ledger. - -2.2.9 entry ------------ - -The `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: - - 2004/03/15 * Viva Italiano - Expenses:Food $12.45 - Expenses:Tips $2.55 - Liabilities:MasterCard $-15.00 - - Now it's `2004/4/9', and you've just eating at `Viva Italiano' -again. The exact amounts are different, but the overall form is the -same. With the `entry' command you can type: - - ledger entry 2004/4/9 viva food 11 tips 2.50 - - This produces the following output: - - 2004/04/09 Viva Italiano - Expenses:Food $11.00 - Expenses:Tips $2.50 - Liabilities:MasterCard $-13.50 - - It works by finding a past transaction matching the regular -expression `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 `1'. - - There is a shell script in the distribution's `scripts' directory -called `entry', which simplifies the task of adding a new entry to your -ledger. It launches `vi' to confirm that the entry looks appropriate. - - Here are a few more examples of the `entry' command, assuming the -above journal entry: - - 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" - - -File: ledger.info, Node: Options, Next: Format strings, Prev: Commands, Up: Running Ledger - -2.3 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: - - ledger [OPTIONS] COMMAND [REGEXPS...] [-- [REGEXPS...]] - - The OPTIONS and REGEXPS expressions are both optional. You could -just use `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:: - - -File: ledger.info, Node: Basic options, Next: Report filtering, Prev: Options, Up: Options - -2.3.1 Basic options -------------------- - -These are the most basic command options. Most likely, the user will -want to set them using *Note Environment variables::, instead of using -actual command-line options: - - `--help' (`-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. - - `--version' (`-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. - - `--file FILE' (`-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 `LEDGER_FILE' -is set, rather than using this command-line option. - - `--output FILE' (`-o FILE') redirects output from any command to -FILE. By default, all output goes to standard output. - - `--init-file FILE' (`-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: - - --price-db ~/finance/.pricedb - - ; ~/.ledgerrc ends here - - Option settings on the command-line or in the environment always take -precedence over settings in the init file. - - `--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 `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 `LEDGER_CACHE', or by putting the option -into your init file. The `--no-cache' option causes Ledger to always -ignore the binary cache. - - `--account NAME' (`-a NAME') specifies the default account which QIF -file transactions are assumed to relate to. - - -File: ledger.info, Node: Report filtering, Next: Output customization, Prev: Basic options, Up: Options - -2.3.2 Report filtering ----------------------- - -These options change which transactions affect the outcome of a report, -in ways other than just using regular expressions: - - `--current'(`-c') displays only entries occurring on or before the -current date. - - `--begin DATE' (`-b DATE') constrains the report to entries on or -after 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 `--display' to constrain what is displayed). - - `--end DATE' (`-e DATE') constrains the report so that entries on or -after DATE are not considered. The ending date is inclusive. - - `--period STR' (`-p STR') sets the reporting period to 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 *Note Period expressions::. - - `--period-sort EXPR' sorts the transactions within each reporting -period using the value expression EXPR. This is most often useful when -reporting monthly expenses, in order to view the highest expense -categories at the top of each month: - - ledger -M --period-sort -At reg ^Expenses - - `--cleared' (`-C') displays only transactions whose entry has been -marked "cleared" (by placing an asterix to the right of the date). - - `--uncleared' (`-U') displays only transactions whose entry has not -been marked "cleared" (i.e., if there is no asterix to the right of the -date). - - `--real' (`-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). - - `--actual' (`-L') displays only actual transactions, and not those -created due to automated transactions. - - `--related' (`-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: - - 2004/03/20 Safeway - Expenses:Food $65.00 - Expenses:Cash $20.00 - Assets:Checking $-85.00 - - And the register command was: - - ledger -r register food - - The following would be output, showing the transactions related to -the transaction that matched: - - 2004/03/20 Safeway Expenses:Cash $-20.00 $-20.00 - Assets:Checking $85.00 $65.00 - - `--budget' is useful for displaying how close your transactions meet -your budget. `--add-budget' also shows unbudgeted transactions, while -`--unbudgeted' shows only those. `--forecast' is a related option that -projects your budget into the future, showing how it will affect future -balances. *Note Budgeting and forecasting::. - - `--limit EXPR' (`-l EXPR') limits which transactions take part in -the calculations of a report. - - `--amount EXPR' (`-t EXPR') changes the value expression used to -calculate the "value" column in the `register' report, the amount used -to calculate account totals in the `balance' report, and the values -printed in the `equity' report. *Note Value expressions::. - - `--total EXPR' (`-T EXPR') sets the value expression used for the -"totals" column in the `register' and `balance' reports. - - -File: ledger.info, Node: Output customization, Next: Commodity reporting, Prev: Report filtering, Up: Options - -2.3.3 Output customization --------------------------- - -These options affect only the output, but not which transactions are -used to create it: - - `--collapse' (`-n') causes entries in a `register' report with -multiple transactions to be collapsed into a single, subtotaled entry. - - `--subtotal' (`-s') causes all entries in a `register' report to be -collapsed into a single, subtotaled entry. - - `--by-payee' (`-P') reports subtotals by payee. - - `--comm-as-payee' (`-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 `-s'. - - `--empty' (`-E') includes even empty accounts in the `balance' -report. - - `--weekly' (`-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 `weekly from DATE'. `--monthly' (`-M') reports transaction totals -by month; `--yearly' (`-Y') reports transaction totals by year. For -more complex period, using the `--period' option described above. - - `--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. - - `--sort EXPR' (`-S EXPR') sorts a report by comparing the values -determined using the value expression EXPR. For example, using `-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 *Note Value expressions::. - - `--wide' (`-w') causes the default `register' report to assume 132 -columns instead of 80. - - `--head' causes only the first N entries to be printed. This is -different from using the command-line utility `head', which would limit -to the first N transactions. `--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). - - `--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 `LEDGER_PAGER' environment -variable. - - `--average' (`-A') reports the average transaction value. - - `--deviation' (`-D') reports each transaction's deviation from the -average. It is only meaningful in the `register' and `prices' reports. - - `--percentage' (`-%') shows account subtotals in the `balance' -report as percentages of the parent account. - - `--totals' include running total information in the `xml' report. - - `--amount-data' (`-j') changes the `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. - - `--total-data' (`-J') changes the `register' report so that it -output nothing but the date and totals column, without commodities. - - `--display EXPR' (`-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: - - ledger -d "d>=[last month]" reg checking - - The output from this command is very different from the following, -whose running total includes only transactions from the last month -onward: - - ledger -p "last month" reg checking - - Which is more useful depends on what you're looking to know: the -total amount for the reporting range (`-p'), or simply a display -restricted to the reporting range (using `-d'). - - `--date-format STR' (`-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 `%Y/%m/%d'. To change the way dates are printed -in general, the easiest way is to put `--date-format FORMAT' in the -Ledger initialization file `~/.ledgerrc' (or the file referred to by -`LEDGER_INIT'). - - `--format STR' (`-F STR') sets the reporting format for whatever -report ledger is about to make. *Note Format strings::. There are -also specific format commands for each report type: - - * `--balance-format STR' - - * `--register-format STR' - - * `--print-format STR' - - * `--plot-amount-format STR' (-j `register') - - * `--plot-total-format STR' (-J `register') - - * `--equity-format STR' - - * `--prices-format STR' - - * `--wide-register-format STR' (-w `register') - - -File: ledger.info, Node: Commodity reporting, Next: Environment variables, Prev: Output customization, Up: Options - -2.3.4 Commodity reporting -------------------------- - -These options affect how commodity values are displayed: - - `--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: - - ; Don't download quotes for the dollar, or timelog values - N $ - N h - - `--price-exp MINS' (`-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 `--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. - - `--download' (`-Q') causes quotes to be automagically downloaded, as -needed, by running a script named `getquote' and expecting that script -to return a value understood by ledger. A sample implementation of a -`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 -`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 `-t' and `-T' options. However, there are also -several "default" reports, which will satisfy most users basic -reporting needs: - -`-O, --quantity' - Reports commodity totals (this is the default) - -`-B, --basis' - Reports the cost basis for all transactions. - -`-V, --market' - Reports the last known market value for all commodities. - -`-g, --performance' - Reports the net gain/loss for each transaction in a `register' - report. - -`-G --gain' - Reports the net gain/loss for all commodities in the report that - have a price history. - - -File: ledger.info, Node: Environment variables, Prev: Commodity reporting, Up: Options - -2.3.5 Environment variables ---------------------------- - -Every option to ledger may be set using an environment variable. If an -option has a long name such `--this-option', setting the environment -variable `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 `~/.ledgerrc', for example: - - --cache /tmp/.mycache - - -File: ledger.info, Node: Format strings, Next: Value expressions, Prev: Options, Up: Running Ledger - -2.4 Format strings -================== - -Format strings may be used to change the output format of reports. -They are specified by passing a formatting string to the `--format' -(`-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 (`%'). The basic format of all substitutions is: - - %[-][MIN WIDTH][.MAX WIDTH]EXPR - - If the optional minus sign (`-') 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: - - %-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 - - The expression following the format constraints can be a single -letter, or an expression enclosed in parentheses or brackets. The -allowable expressions are: - -`%' - Inserts a percent sign. - -`t' - Inserts the results of the value expression specified by `-t'. If - `-t' was not specified, the current report style's value - expression is used. - -`T' - Inserts the results of the value expression specified by `-T'. If - `-T' was not specified, the current report style's value - expression is used. - -`|' - Inserts a single space. This is useful if a width is specified, - for inserting a certain number of spaces. - -`_' - 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 `%5_', for an account with four - parents, will insert twenty spaces. - -`(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 `%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. - -`[DATEFMT]' - Inserts the result of formatting a transaction's date with a date - format string, exactly like those supported by `strftime'. For - example: `%[%Y/%m/%d %H:%M:%S]'. - -`S' - Insert the pathname of the file from which the entry's data was - read. - -`B' - Inserts the beginning character position of that entry within the - file. - -`b' - Inserts the beginning line of that entry within the file. - -`E' - Inserts the ending character position of that entry within the - file. - -`e' - Inserts the ending line of that entry within the file. - -`D' - By default, this is the same as `%[%Y/%m%/d]'. The date format - used can be changed at any time with the `-y' flag, however. - Using `%D' gives the user more control over the way dates are - output. - -`d' - This is the same as the `%D' option, unless the entry has an - effective date, in which case it prints - `[ACTUAL_DATE=EFFECtIVE_DATE]'. - -`X' - If a transaction has been cleared, this inserts `*' followed by a - space; otherwise nothing is inserted. - -`Y' - This is the same as `%X', except that it only displays a state - character if all of the member transactions have the same state. - -`C' - Inserts the checking number for an entry, in parentheses, followed - by a space; if none was specified, nothing is inserted. - -`P' - Inserts the payee related to a transaction. - -`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. - -`A' - Inserts the full name of an account. - -`W' - This is the same as `%A', except that it first displays the - transaction's state _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 `%Y', only the - minimum amount of state detail is printed. - -`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. - -`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 `foo' is substituted as ` ; foo'. - -`N' - Inserts the note associated with a transaction, if one exists. - -`/' - The `%/' 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. - - -File: ledger.info, Node: Value expressions, Next: Period expressions, Prev: Format strings, Up: Running Ledger - -2.5 Value expressions -===================== - -Value expressions are an expression language used by Ledger to -calculate values used by the program for many different purposes: - - 1. The values displayed in reports - - 2. For predicates (where truth is anything non-zero), to determine - which transactions are calculated (`-l') or displayed (`-d'). - - 3. For sorting criteria, to yield the sort key. - - 4. In the matching criteria used by automated transactions. - - 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 `balance' command: - - ledger -d /^Liabilities/?T<0:UT>100 balance - - 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: - - ledger -d "d>[this month]" register checking - - 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: - - ledger -b "this month" register checking - -2.5.1 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. - -`t' - This maps to whatever the user specified with `-t'. In a register - report, `-t' changes the value column; in a balance report, it has - no meaning by default. If `-t' was not specified, the current - report style's value expression is used. - -`T' - This maps to whatever the user specified with `-T'. In a register - report, `-T' changes the totals column; in a balance report, this - is the value given for each account. If `-T' was not specified, - the current report style's value expression is used. - -`m' - This is always the present moment/date. - -2.5.1.1 Transaction/account details -................................... - -`d' - A transaction's date, as the number of seconds past the epoch. - This is always "today" for an account. - -`a' - The transaction's amount; the balance of an account, without - considering children. - -`b' - The cost of a transaction; the cost of an account, without its - children. - -`v' - The market value of a transaction, or an account without its - children. - -`g' - The net gain (market value minus cost basis), for a transaction or - an account without its children. It is the same as `v-b'. - -`l' - The depth ("level") of an account. If an account has one parent, - it's depth is one. - -`n' - The index of a transaction, or the count of transactions affecting - an account. - -`X' - 1 if a transaction's entry has been cleared, 0 otherwise. - -`R' - 1 if a transaction is not virtual, 0 otherwise. - -`Z' - 1 if a transaction is not automated, 0 otherwise. - -2.5.1.2 Calculated totals -......................... - -`O' - The total of all transactions seen so far, or the total of an - account and all its children. - -`N' - The total count of transactions affecting an account and all its - children. - -`B' - The total cost of all transactions seen so far; the total cost of - an account and all its children. - -`V' - The market value of all transactions seen so far, or of an account - and all its children. - -`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 - `V-B'. - -2.5.2 Functions ---------------- - -The available one letter functions are: - -`-' - Negates the argument. - -`U' - The absolute (unsigned) value of the argument. - -`S' - Strips the commodity from the argument. - -`A' - The arithmetic mean of the argument; `Ax' is the same as `x/n'. - -`P' - The present market value of the argument. The syntax `P(x,d)' is - supported, which yields the market value at time `d'. If no date - is given, then the current moment is used. - -2.5.3 Operators ---------------- - -The binary and ternary operators, in order of precedence, are: - - 1. `* /' - - 2. `+ -' - - 3. `! < > =' - - 4. `& | ?:' - -2.5.4 Complex expressions -------------------------- - -More complicated expressions are possible using: - -`NUM' - A plain integer represents a commodity-less amount. - -`{AMOUNT}' - An amount in braces can be any kind of amount supported by ledger, - with or without a commodity. Use this for decimal values. - -`/REGEXP/' - -`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. - -`//REGEXP/' - -`p/REGEXP/' - A regular expression that matches against an entry's payee name. - -`///REGEXP/' - -`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. - -`c/REGEXP/' - A regular expression that matches against the entry code (the text - that occurs between parentheses before the payee name). - -`e/REGEXP/' - A regular expression that matches against a transaction's note, or - comment field. - -`(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. - -`[DATE]' - Useful specifying a date in plain terms. For example, you could - say `[2004/06/01]'. - - -File: ledger.info, Node: Period expressions, Next: File format, Prev: Value expressions, Up: Running Ledger - -2.6 Period expressions -====================== - -A period expression indicates a span of time, or a reporting interval, -or both. The full syntax is: - - [INTERVAL] [BEGIN] [END] - - The optional INTERVAL part may be any one of: - - 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 - - After the interval, a begin time, end time, both or neither may be -specified. As for the begin time, it can be either of: - - from <SPEC> - since <SPEC> - - The end time can be either of: - - to <SPEC> - until <SPEC> - - Where SPEC can be any of: - - 2004 - 2004/10 - 2004/10/1 - 10/1 - october - oct - this week # or day, month, quarter, year - next week - last week - - The beginning and ending can be given at the same time, if it spans a -single period. In that case, just use SPEC by itself. In that case, -the period `oct', for example, will cover all the days in october. The -possible forms are: - - <SPEC> - in <SPEC> - - Here are a few examples of period expressions: - - 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 - - -File: ledger.info, Node: File format, Next: Some typical queries, Prev: Period expressions, Up: Running Ledger - -2.7 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: - -`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: - - DATE[=EDATE] [*|!] [(CODE)] DESC - - If `*' 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 `!' 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 `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: - - ACCOUNT AMOUNT [; NOTE] - - The `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 `AMOUNT' can be followed by a per-unit - transaction cost, by specifying ` AMOUNT', or a complete - transaction cost with `@ AMOUNT'. Lastly, the `NOTE' may specify - an actual and/or effective date for the transaction by using the - syntax `[ACTUAL_DATE]' or `[=EFFECTIVE_DATE]' or - `[ACTUAL_DATE=EFFECtIVE_DATE]'. - -`=' - 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. - -`~' - 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. - -`!' - A line beginning with an exclamation mark denotes a command - directive. It must be immediately followed by the command word. - The supported commands are: - - `!include' - Include the stated ledger file. - - `!account' - The account name is given is taken to be the parent of all - transactions that follow, until `!end' is seen. - - `!end' - Ends an account block. - -`;' - A line beginning with a colon indicates a comment, and is ignored. - -`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: `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. - -`P' - Specifies a historical price for a commodity. These are usually - found in a pricing history file (see the `-Q' option). The syntax - is: - P DATE SYMBOL PRICE - -`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 `~/.pricedb'. The syntax for this command is: - N SYMBOL - -`D AMOUNT' - Specifies the default commodity to use, by specifying an amount in - the expected format. The `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: - D $1,000.00 - -`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: - C 1.00 Kb = 1024 bytes - -`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. - - -File: ledger.info, Node: Some typical queries, Next: Budgeting and forecasting, Prev: File format, Up: Running Ledger - -2.8 Some typical queries -======================== - -A query such as the following shows all expenses since last October, -sorted by total: - - ledger -b "last oct" -s -S T bal ^expenses - - 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. - -2.8.1 Reporting monthly expenses --------------------------------- - -The following query makes it easy to see monthly expenses, with each -month's expenses sorted by the amount: - - ledger -M --period-sort t reg ^expenses - - Now, you might wonder where the money came from to pay for these -things. To see that report, add `-r', which shows the "related -account" transactions: - - ledger -M --period-sort t -r reg ^expenses - - 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 `^expenses', while the transactions displayed -must match `mastercard'. The command would be: - - ledger -M -r -d /mastercard/ reg ^expenses - - This query says: Report monthly subtotals; report the "related -account" transactions; display only related transactions whose account -matches `mastercard', and base the calculation on transactions matching -`^expenses'. - - This works just as well for report the overall total, too: - - ledger -s -r -d /mastercard/ reg ^expenses - - The `-s' option subtotals all transactions, just as `-M' subtotaled -by the month. The running total in both cases is off, however, since a -display expression is being used. - -2.8.2 Visualizing with Gnuplot ------------------------------- - -If you have `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 `scripts/report'. Install `report' anywhere -along your `PATH', and then use `report' instead of `ledger' when doing -a register report. The only thing to keep in mind is that you must -specify `-j' or `-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. - - report -j -M -r -d /mastercard/ reg ^expenses - - The `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. - -2.8.2.1 Typical plots -..................... - -Here are some useful plots: - - 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 - - The last report uses both a calculation predicate (`-l') and a -display predicate (`-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 _displayed_ to just those since last February, even those -entries from before then will be computed as part of the balance. - - -File: ledger.info, Node: Budgeting and forecasting, Prev: Some typical queries, Up: Running Ledger - -2.9 Budgeting and forecasting -============================= - -2.9.1 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: - - ~ 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 - - 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: - - ledger -p "this year" -MAs bal ^expenses - - 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 `--budget' to the command-line. For example, a typical -monthly expense report would be: - - ledger -M reg ^exp - - To see the same report balanced against your budget, use: - - ledger --budget -M reg ^exp - - A budget report includes only those accounts that appear in the -budget. To see all expenses balanced against the budget, use -`--add-budget'. You can even see only the unbudgeted expenses using -`--unbudgeted': - - ledger --unbudgeted -M reg ^exp - - You can also use these flags with the `balance' command. - -2.9.2 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: - - ledger --forecast "T>{\$-500.00}" register ^assets ^liabilities - - 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: - - ledger --forecast "d<[2010]" bal ^assets ^liabilities - - -File: ledger.info, Node: Keeping a ledger, Next: Using XML, Prev: Running Ledger, Up: Top - -3 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: - - 9/29 (100) Pacific Bell - Expenses:Utilities:Phone $23.00 - Assets:Checking $-23.00 - - 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: - - 9/29 (100) Pacific Bell - Expenses:Utilities:Phone $23.00 - Assets:Checking - - For this entry, Ledger will figure out that $-23.00 must come from -`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:: - - -File: ledger.info, Node: Stating where money goes, Next: Assets and Liabilities, Prev: Keeping a ledger, Up: Keeping a ledger - -3.1 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 _subtracted_ from -the source accounts, and _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: - - 9/29 My Employer - Assets:Checking $500.00 - Income:Salary $-500.00 - - 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? - - -File: ledger.info, Node: Assets and Liabilities, Next: Commodities and Currencies, Prev: Stating where money goes, Up: Keeping a ledger - -3.2 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: - - 2004/09/29 My Employer - Assets:Checking $500.00 - Income:Salary - - 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: - - 2004/09/30 Restaurant - Expenses:Dining $25.00 - Liabilities:MasterCard - - 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: - - ledger balance ^assets ^liabilities - - Relatedly, your Income accounts show up negative, because they -transfer money _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: - - ledger balance ^income ^expenses - - 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: - - ledger -M register expenses:auto - - This assumes, of course, that you use account names like -`Expenses:Auto:Gas' and `Expenses:Auto:Repair'. - -3.2.1 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 _to_ your Assets:Reimbursements, using a different account for each -person or business that you spend money for. For example: - - 2004/09/29 Circuit City - Assets:Reimbursements:Company XYZ $100.00 - Liabilities:MasterCard - - 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: - - 2004/09/29 Company XYZ - Assets:Checking $100.00 - Assets:Reimbursements:Company XYZ - - 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: - - 2004/09/29 Circuit City - Assets:Reimbursements:Company XYZ $100.00 - Liabilities:MasterCard - - 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: - - 2004/09/29 Circuit City - Company XYZ:Expenses:Computer:Software $100.00 - Company XYZ:Accounts Payable:Your Name - - 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: - - 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 - - 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: - - 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 - - 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 `Assets:Reimbursements:Company XYZ', and -`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: - - 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 - - And two in your company ledger file: - - !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 - - (Note: The `!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. - - -File: ledger.info, Node: Commodities and Currencies, Next: Accounts and Inventories, Prev: Assets and Liabilities, Up: Keeping a ledger - -3.3 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: - - $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) - - 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: - - $200.00 - 100.00 AU - AAPL 40 - BORL 100 - FEQTX 50 Assets:Brokerage - - 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: - - 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 - - Specify the price history to use with the `--price-db' option, with -the `-V' option to report in terms of current market value: - - ledger --price-db prices.db -V balance brokerage - - The balance for your brokerage account will be reported in US -dollars, since the prices database uses that currency. - - $40880.00 Assets:Brokerage - - 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: - - ledger -T "{1 AU}*(O/P{1 AU})" balance checking - - 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: - - 14.01 AU Assets:Checking - -3.3.1 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: - - 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 - - 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. - -3.3.2 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 `Billable' account, and another which -decreases the same account by ten minutes. The resulting report will -indicate that fifty minutes remain: - - 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 - - Reporting the balance for this ledger file produces: - - 50.0m Billable:Client - -50.0m Project:XYZ - - 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: - - C 1.00 Kb = 1024 b - C 1.00 Mb = 1024 Kb - C 1.00 Gb = 1024 Mb - C 1.00 Tb = 1024 Gb - - Each of these definitions correlates a commodity (such as `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 `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. - - -File: ledger.info, Node: Accounts and Inventories, Next: Understanding Equity, Prev: Commodities and Currencies, Up: Keeping a ledger - -3.4 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: - - 9/29 Get some stuff at the Inn - Places:Black's Tavern -3 Apples - Places:Black's Tavern -5 Steaks - EverQuest:Inventory - - Now your EverQuest:Inventory has 3 apples and 5 steaks in it. The -amounts are negative, because you are taking _from_ Black's Tavern in -order to add to your Inventory account. Note that you don't have to -use `Places:Black's Tavern' as the source account. You could use -`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: - - 10/2 Sturm Brightblade - EverQuest:Inventory -2 Steaks - EverQuest:Inventory 15 Gold - - Now you've turned 2 steaks into 15 gold, courtesy of your customer, -Sturm Brightblade. - - -File: ledger.info, Node: Understanding Equity, Next: Dealing with Petty Cash, Prev: Accounts and Inventories, Up: Keeping a ledger - -3.5 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. - - 10/2 Opening Balance - Assets:Checking $100.00 - Equity:Opening Balances - - 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 -`-Equity' at the end of your balance command, to remove the confusing -figure from the total. - - -File: ledger.info, Node: Dealing with Petty Cash, Next: Working with multiple funds and accounts, Prev: Understanding Equity, Up: Keeping a ledger - -3.6 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 `Expenses:Cash' category: - - 2004/03/15 ATM - Expenses:Cash $100.00 - Assets:Checking - - If at some point you make a large cash expense that you want to -track, just "move" the amount of the expense from `Expenses:Cash' into -the target account: - - 2004/03/20 Somebody - Expenses:Food $65.00 - Expenses:Cash - - This way, you can still track large cash expenses, while ignoring all -of the smaller ones. - - -File: ledger.info, Node: Working with multiple funds and accounts, Next: Archiving previous years, Prev: Dealing with Petty Cash, Up: Keeping a ledger - -3.7 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: - - * Checking - - * Savings - - * Credit Card - - 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: - - * School fund - - * Building fund - - * Community fund - - 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 `$500.00', but `$400.00' of -that comes from Checking, and `$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: - - 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 - - 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: - - 2004/03/25 Payment for books (paid from Checking) - Expenses:Books $100.00 - Assets:Checking $-100.00 - (Funds:School) $-100.00 - - 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 `Assets' -account, because otherwise the balance won't make much sense: - - ledger bal -^Assets - - If the `--real' option is used, the report will be in terms of the -real accounts: - - ledger --real bal - - If more asset accounts are needed as the source of a transaction, -just list them as you would normally, for example: - - 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 - - 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 `Funds:School' fund: - - 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 - - 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 `--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 `--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: - - ledger --code-as-payee -P reg ^Assets - - Or to see a particular funds expenses, the `School' fund in this -case: - - ledger --code-as-payee -P reg ^Expenses -- School - - 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. - - -File: ledger.info, Node: Archiving previous years, Next: Virtual transactions, Prev: Working with multiple funds and accounts, Up: Keeping a ledger - -3.8 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: `print', and `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 `print' to -output all the earlier entries to a file called `ledger-old.dat': - - ledger -f ledger.dat -b 2000 -e 2001 print > ledger-old.dat - - To delete older data from the current ledger file, use `print' -again, this time specifying year 2002 as the starting date: - - ledger -f ledger.dat -b 2002 print > x - mv x ledger.dat - - However, now the current file contains _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: - - ledger -f ledger-old.dat equity > equity.dat - cat equity.dat ledger.dat > x - mv x ledger.dat - rm equity.dat - - Now the balances reported from `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. - - -File: ledger.info, Node: Virtual transactions, Next: Automated transactions, Prev: Archiving previous years, Up: Keeping a ledger - -3.9 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: - - 10/2 Paycheck - Assets:Checking $1000.00 - Income:Salary $-1000.00 - (Debt:Alimony) $200.00 - - In this example, after receiving a paycheck an alimony debt is -increased--even though no money has moved around yet. - - 10/2 Paycheck - Assets:Checking $1000.00 - Income:Salary $-1000.00 - [Savings:Trip] $200.00 - [Assets:Checking] $-200.00 - - 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 `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 `-R' flag, for "reality". - - -File: ledger.info, Node: Automated transactions, Next: Using Emacs to Keep Your Ledger, Prev: Virtual transactions, Up: Keeping a ledger - -3.10 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: - - ; 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 - - 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 `Liabilities:Huququ'llah' -account. So, if $1000 is earned from `Income:Salary', $190 is added to -`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 -`Liabilities:Huququ'llah'. That entry would look like: - - 2003/01/01 (101) Baha'i Huqúqu'lláh Trust - Liabilities:Huququ'llah $1,000.00 - Assets:Checking - - That's it. To see how much Huqúq is currently owed based on your -ledger entries, use: - - ledger balance Liabilities:Huquq - - 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: - - ledger -Q -t "/Liab.*Huquq/?(a/P{2.22 AU}<={-1.0}&a):a" -s bal liab - - 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: - - ledger -Q -T "/Liab.*Huquq/?(O/P{2.22 AU}<={-1.0}&O):O" -s bal liab - - 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 `$account': - - = /^Some:Long:Account:Name/ - [$account] -0.10 - [Savings] 0.10 - - This example causes 10% of the matching account's total to be -deferred to the `Savings' account--as a balanced virtual transaction, -which may be excluded from reports by using `--real'. - - -File: ledger.info, Node: Using Emacs to Keep Your Ledger, Next: Using GnuCash to Keep Your Ledger, Prev: Automated transactions, Up: Keeping a ledger - -3.11 Using Emacs to Keep Your Ledger -==================================== - -In the Ledger tarball is an Emacs module, `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: - - ; -*-ledger-*- - - And this in your `.emacs' file, after copying `ledger.el' to your -`site-lisp' directory: - - (load "ledger") - - Now when you edit your ledger file, it will be in `ledger-mode'. -`ledger-mode' adds these commands: - -*C-c C-a* - For quickly adding new entries based on the form of older ones (see - previous section). - -*C-c C-c* - Toggles the "cleared" flag of the transaction under point. - -*C-c C-d* - Delete the entry under point. - -*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. - -*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. - -*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. - - Once you enter the reconcile buffer, there are several key commands -available: - -*RET* - Visit the ledger file entry corresponding to the reconcile entry. - -*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. - -*C-l* - Refresh the reconcile buffer by re-reading transactions from the - ledger data file. - -*SPC* - Toggle the transaction under point as cleared. - -*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). - -*d* - Delete the entry related to the transaction under point. Note: - This may result in multiple transactions being deleted. - -*n* - Move to the next line. - -*p* - Move to the previous line. - -*C-c C-r* - -*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. - -*C-x C-s* - -*s* - Save the ledger data file, and show the current cleared balance for - the account being reconciled. - -*q* - Quit the reconcile buffer. - - There is also an `emacs' command which can be used to output reports -in a format directly `read'-able from Emacs Lisp. - - -File: ledger.info, Node: Using GnuCash to Keep Your Ledger, Next: Using timeclock to record billable time, Prev: Using Emacs to Keep Your Ledger, Up: Keeping a ledger - -3.12 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. Perhaps an Emacs mode will appear someday -soon to make editing Ledger's data files much easier. - - Until then, you are 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, 35 megabyte -behemoth to edit their data, and a one megabyte binary to query it? - - -File: ledger.info, Node: Using timeclock to record billable time, Prev: Using GnuCash to Keep Your Ledger, Up: Keeping a ledger - -3.13 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: - - export TIMELOG=$HOME/.timelog - ti ClientOne category - sleep 10 - to waited for ten seconds - - The `.timelog' file now contains: - - i 2004/10/06 15:21:00 ClientOne category - o 2004/10/06 15:21:10 waited for ten seconds - - Ledger parses this directly, as if it had seen the following entry: - - 2004/10/06 category - (ClientOne) 10s - - In other words, the timelog event pair is seen as adding 0.00277h -(ten seconds) worth of time to the `ClientOne' account. This would be -considered billable time, which later could be invoiced and credited to -accounts receivable: - - 2004/11/01 (INV#1) ClientOne, Inc. - Receivable:ClientOne $0.10 - ClientOne -0.00277h @ $35.00 - - 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: - - 2004/12/01 ClientOne, Inc. - Assets:Checking $0.10 - Receivable:ClientOne - - 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 `!include' my timelog at the top of my company's -accounting ledger, with the attached prefix `Billable': - - ; -*-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 - - -File: ledger.info, Node: Using XML, Prev: Keeping a ledger, Up: Top - -4 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: - - <?xml version="1.0"?> - <ledger> - <entry>...</entry> - <entry>...</entry> - <entry>...</entry>... - </ledger> - - The data stream is enclosed in a `ledger' tag, which contains a -series of one or more entries. Each `entry' describes the entry and -contains a series of one or more transactions: - - <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> - - The date format for `en:date' is always `YYYY/MM/DD'. The -`en:cleared' tag is optional, and indicates whether the transaction has -been cleared or not. There is also an `en:pending' tag, for marking -pending transactions. The `en:code' and `en:payee' tags both contain -whatever text the user wishes. - - After the initial entry data, there must follow a set of transactions -marked with `en:transactions'. Typically these transactions will all -balance each other, but if not they will be automatically balanced into -an account named `<Unknown>'. - - Within the `en:transactions' tag is a series of one or more -`transaction''s, which have the following form: - - <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> - - This is a basic transaction. It may also be begin with `tr:virtual' -and/or `tr:generated' tags, to indicate virtual and auto-generated -transactions. Then follows the `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 -`tr:amount'. Within this tag is a `value' tag, of which there are four -different kinds, each with its own format: - - 1. boolean - - 2. integer - - 3. amount - - 4. balance - - The format of a boolean value is `true' or `false' surrounded by a -`boolean' tag, for example: - - <boolean>true</boolean> - - The format of an integer value is the numerical value surrounded by -an `integer' tag, for example: - - <integer>12036</integer> - - 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: - -*P* - The commodity is prefixed to the value. - -*S* - The commodity is separated from the value by a space. - -*T* - Thousands markers are used to display the amount. - -*E* - The format of the amount is European, with period used as a - thousands marker, and comma used as the decimal point. - - 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: - - <value type="amount"> - <amount> - <commodity flags="PT">$</commodity> - <quantity>90.00</quantity> - </amount> - </value> - - 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: - - <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> - - That is the extent of the XML data format used by Ledger. It will -output such data if the `xml' command is used, and can read the same -data as long as the `expat' library was available when Ledger was built. - - - -Tag Table: -Node: Top1762 -Node: Introduction3440 -Ref: Introduction-Footnote-19380 -Node: Building the program9457 -Node: Getting help10004 -Node: Running Ledger10414 -Node: Usage overview11934 -Ref: Usage overview-Footnote-145404 -Ref: Usage overview-Footnote-245522 -Node: Commands45627 -Node: Options50856 -Node: Basic options51717 -Node: Report filtering53902 -Node: Output customization57782 -Node: Commodity reporting62687 -Node: Environment variables64785 -Node: Format strings65433 -Node: Value expressions70805 -Node: Period expressions77136 -Node: File format78724 -Node: Some typical queries83592 -Node: Budgeting and forecasting87314 -Node: Keeping a ledger90054 -Node: Stating where money goes92763 -Node: Assets and Liabilities95416 -Node: Commodities and Currencies103561 -Node: Accounts and Inventories109722 -Node: Understanding Equity111317 -Node: Dealing with Petty Cash113224 -Node: Working with multiple funds and accounts114321 -Node: Archiving previous years119037 -Node: Virtual transactions121561 -Node: Automated transactions123237 -Node: Using Emacs to Keep Your Ledger126257 -Node: Using GnuCash to Keep Your Ledger129328 -Node: Using timeclock to record billable time130237 -Node: Using XML132997 - -End Tag Table diff --git a/docs/ledger.texi b/docs/ledger.texi deleted file mode 100644 index bd42a3b0..00000000 --- a/docs/ledger.texi +++ /dev/null @@ -1,3960 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@setfilename ledger.info -@settitle Ledger: Command-Line Accounting - -@dircategory User Applications -@copying -Copyright (c) 2003-2006, 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. Perhaps an Emacs mode will appear someday -soon to make editing Ledger's data files much easier. - -Until then, you are 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, 35 megabyte behemoth -to edit their data, and 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/docs/sample.dat b/docs/sample.dat deleted file mode 100644 index 4856a6e2..00000000 --- a/docs/sample.dat +++ /dev/null @@ -1,26 +0,0 @@ -;= acct =~ /^Expenses:Books/ -; (Liabilities:Taxes) -0.10 - -;~ Monthly -; Assets:Bank:Checking $500.00 -; Income:Salary - -2004/05/01 * (22:15) 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 |