Initial commit of new documentation structure

doc/L3-Introduction.texi

@@ -0,0 +1,161 @@
+@c -*-texinfo-*-
+
+@ledgerprog@ 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 journal 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 journal.  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 journal,
+so we'll describe double-entry accounting in terms of that.
+
+A checkbook journal 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 journal is to
+know how much money is available to spend.  That's really the aim of
+all journals.
+
+What computers add is the ability to walk through these postings,
+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 journal, 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 journal, is a journal that keeps track
+of all your accounts, not just checking.  In such a journal, you record
+not only who gets paid---in the case of a debit---but where the money
+came from.  In a checkbook journal, its assumed that all the money
+comes from your checking account.  But in a general journal, you write
+posting 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 journal 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 journal for both.  In this general
+journal you need to record a payment to Pacific Bell for your monthly
+phone bill, and a transfer (via check) from your brokerage account to
+your checking account.  The Pacific Bell bill is $23.00, let's say, and
+you want to pay it from your checking account.  In the general journal
+you need to say where the money came from, in addition to where it's
+going to.  These transactions might look like this:
+
+@smallexample
+9/29        Pacific Bell                $23.00     $23.00
+            Checking                   $-23.00          0
+9/30        Checking                   $100.00    $100.00
+      (123) Brokerage                 $-100.00          0
+@end smallexample
+
+The posting must balance to $0: $23 went to Pacific Bell, $23 came from
+Checking.  The next entry shows check number 123 written against your
+brokerage account, transfering money to your checking account.  There is
+nothing left over to be accounted for, since the money has simply moved
+from one account to another in both cases.  This is the basis of
+double-entry accounting: money never pops in or out of existence; it is
+always a posting from one account to another.
+
+Keeping a general journal is the same as keeping two separate journals:
+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 journal books, if you
+deal with multiple accounts.
+
+Here is a good place for an aside on the use of the word `account'.
+Most private people consider an account to be something that holds money
+at an institution for them.  @ledgerprog@ uses a more general definition
+of the word.  An account is anywhere money can go.  Other finance
+programs use ``categories'', @ledgerprog@ uses accounts. So, for
+example, if you buy some groceries at Trader Joe's then more groceries
+at Whole Foods Markets you might assign the transactions like this
+@smallexample
+2011/03/15   Trader Joe's
+      Expenses:Groceries   $100.00
+      Assets:Checking
+2011/03/15   Whole Food Market
+      Expenses:Groceries   $75.00
+      Assets:Checking
+@end smallexample
+In both cases the money goes to the ``Groceries'' account, even though
+the payees were different.  You can set up your accounts in any way you
+choose.
+
+Enter the beauty of computerized accounting.  The purpose of the
+@ledgerprog@ program is to make general journal accounting simple, by keeping
+track of the balances for you.  Your only job is to enter the
+postings.  If a posting does not balance, @ledgerprog@ displays an
+error and indicates the incorrect posting.@footnote{In some
+special cases, it automatically balances this transaction for you.}
+
+In summary, there are two aspects of @ledgerprog@ use: updating the journal
+data file, and using the @ledgerprog@ tool to view the summarized result of
+your transactions.
+
+And just for the sake of example---as a starting point for those who
+want to dive in head-first---here are the journal transactions from above,
+formatted as the @ledgerprog program wishes to see them:
+
+@smallexample
+2004/09/29 Pacific Bell
+     Expenses:Pacific Bell              $23.00
+     Assets: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
+
+An important difference between @ledgerprog@ and other finance packages is
+that journal will never alter your input file.  You can create and edit
+that file in any way you prefer, but journal is only for analyzing the
+data, not for altering it.
+
+@section More introduction
+
+
+@section Building the program
+
+@ledgerprog@ 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
+
+@section Getting help
+
+If you need help on how to use @ledgerprog, or run into problems, you can
+join the @ledgerprog@ mailing list at the following Web address:
+
+@example
+http://groups.google.com/group/ledger-cli
+@end example
+
+You can also find help at the @samp{#ledger} channel on the IRC server
+@samp{irc.freenode.net}.
+
+@node Quick Reference, Ledger Tutorial, Introduction, Top

doc/L3-Journal.texi

@@ -0,0 +1,323 @@
+@c -*-texinfo-*-
+The most important part of accounting is keeping a good journal.  If you
+have a good journal, tools can be written to work whatever mathematical
+tricks you need to better understand your spending patterns.  Without a
+good journal, no tool, however smart, can help you.
+
+The @ledgerprog@ program aims at making journal transactions as simple as
+possible.  Since it is a command-line tool, it does not provide a user
+interface for keeping a journal.  If you like, you may use GnuCash to
+maintain your journal, in which case @ledgerprog@ 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
+journal, read on.  @ledgerprog@ has been designed to make data transactions as
+simple as possible, by keeping the journal format easy, and also by
+automagically determining as much information as possible based on the
+nature of your transactions.
+
+For example, you do not need to tell @ledgerprog@ about the accounts you
+use.  Any time @ledgerprog@ sees a posting involving an account it knows
+nothing about, it will create it@footnote{This also means if you
+misspell an account it will end up getting counted separately from what
+you intended.  The provided Emacs major mode provides for automatically
+filling in account names.}.  If you use a commodity that is new to
+@ledgerprog@, 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
+posting.
+
+@section The Most Basic Entry
+
+Here is the Pacific Bell example from above, given as a @ledgerprog@
+posting, with the additional of a check number:
+
+@smallexample
+9/29 (1023) 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 @ledgerprog@'s scheme of things.  In fact, since
+@ledgerprog@ 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 (1023) Pacific Bell
+    Expenses:Utilities:Phone                   $23.00
+    Assets:Checking
+@end smallexample
+
+For this transaction, @ledgerprog@ will figure out that $-23.00 must come from
+@samp{Assets:Checking} in order to balance the transaction.
+
+Also note the structure of the account entries.  There is an implied
+hierarchy established by separating with colons.  See
+(@pxref{Structuring Your Accounts}) for details and suggestions regarding
+your accounts.
+
+
+
+@strong{The format is very flexible and it isn't necessary that you
+indent and space out things exactly as shown. The only requirements are
+that the start of the transaction (the date typically) is at the
+beginning of the first line of the transaction, and the accounts are
+indented by at least one space.  If you omit the leading spaces in the
+account lines @ledgerprog@ will not count the transaction and will not
+give an error.  There must be at least two spaces, or a tab, between the
+amount and the account.  If you do not have adequate separation between
+the amount and the account @ledgerprog@ will give an error and stop
+calculating}
+
+@section Commodities
+
+@ledgerprog@ is agnostic when it comes to how you value your accounts.
+Dollars, Euros, Pounds, Francs, etc. are just ``commodities''.  Holdings
+in stocks, bonds, mutual funds and other financial instrument can be
+label using whatever is convenient for you (stock ticker symbols are
+suggested for publicly traded assets).@footnote{you can track ANYTHING,
+even time. As long as it cannot be created or destroyed inside your
+accounting system.}
+
+This is fundamentally different than many common accounting packages,
+which assume the same currency throughout all of your accounts.  This
+means if you typically operate in Euros, but travel to the US and has
+some expenses, you would have to do the currency conversion BEFORE you
+made the entry into your financial system.  With ledger this is not
+required.  In the same journal you can have entries in any or all
+commodities you actually hold.  You can use the reporting capabilities
+to convert all commodities to a single commodity for reporting purposes
+without ever changing the underlying entry.
+
+For example, the following entries reflect transaction made for a
+business trip to Europe from the US:
+
+@smallexample
+2011/09/23   Cash in Munich
+    Assets:Cash  50.00 Euros
+    Assets:Checking  $-66.00
+
+2011/09/24  Dinner in Munich
+    Expenses:Business:Travel  35.00 Euro
+    Assets:Cash
+@end smallexample
+
+This says that $66.00 came out of checking and turned into 50 Euros. The
+implied exchange rate was $1.32.  Then 35 Euros was spent on Dinner in Munich.
+
+
+
+@section Structuring your Accounts
+
+There really are no requirements for how you do this, but to preserve
+your sanity we suggest some very basic structure to your accounting
+system.
+
+At the highest level you have five sorts of accounts: Expenses, Assets,
+Income, Liabilities and Equity.  Briefly, you can think of these as places money goes,
+places money sits, places money comes from and money you owe.
+
+Starting the structure off this way will make it simpler for you to get
+answers to the questions you really need to ask about your finances.
+
+@section Transaction Notes and Tags
+@ledgerprog@ 3.0 supports entry and transaction ``notes'', which may  
+contain new metadata and tag markers.  Here's an example:
+
+@smallexample
+   2004/05/27 (100) Credit card company
+       ; This is an entry note!
+       ; Sample: Value
+       Liabilities:MasterCard         $20.00
+       ; This is a transaction note!
+       ; Sample: Another Value
+       ; :MyTag:
+       Assets:Bank:Checking
+       ; :AnotherTag:
+@end smallexample
+
+An indented paragraph starting with `;' is parsed as a persistent note  
+for its preceding category.  These notes will get printed back to you  
+with the ``print'' command.  They are accessible to value expressions  
+using the ``note'' variable.
+
+Further, any occurrence of ``:foo:'' in a note will cause a metadata tag  
+for "foo" to be registered for that entry.  You can then search for  
+such transactions using:
+
+@smallexample
+   ledger reg %foo
+   ldeger reg tag foo
+@end smallexample
+
+Also, if any word in the note ends (but does not start) with a colon,  
+the remainder of that line will be taken to be the metadata value for  
+that tag.  That is:
+
+@smallexample
+   ; :foo:bar:baz:  <-- These are three tags
+   ; name: value    <-- this is a tag with a value
+@end smallexample
+
+Tags with value can be searched for just like tags.  In addition, you  
+can further limit your tag search by looking for only those tags that  
+have specific values:
+
+@smallexample
+   ledger reg %name=value
+   ledger reg tag name=value
+@end smallexample
+
+The group-by and sort functions also support tags:
+@smallexample
+ledger --group-by "tag('foo')" bal 
+@end smallexample
+Will produce a balalnce summary of all transanction with tag `foo' group by transactions wiht the same value for `foo'.
+
+@smallexample
+ledger reg --sort "tag('foo')" %foo
+@end smallexample
+Produces a register view with the transaction have tag `foo' sorted by the tags value.
+
+Comments that occur before an entry, or which starts at column  
+zero, are always ignored and are neither searched nor printed back.
+
+
+
+@node File format,  , Value expressions, Quick Reference
+@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 a transaction.  It may be followed
+by any number of lines, each beginning with whitespace, to denote the
+transaction's account postings.  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 transaction is ``cleared'', which can mean whatever the user
+wants it to mean.  If @samp{!} appears after the date, it indicates d
+the transaction 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 posting.  Following these is the payee, or a description of
+the posting.
+
+The format of each following posting is:
+
+@example
+  ACCOUNT  AMOUNT  [; NOTE]
+@end example
+
+The @samp{ACCOUNT} may be surrounded by parentheses if it is a virtual
+postings, or square brackets if it is a virtual postings that
+must balance.  The @samp{AMOUNT} can be followed by a per-unit
+posting cost, by specifying @samp{@@ AMOUNT}, or a complete
+posting cost with @samp{@@@@ AMOUNT}.  Lastly, the @samp{NOTE} may
+specify an actual and/or effective date for the posting by using
+the syntax @samp{[ACTUAL_DATE]} or @samp{[=EFFECTIVE_DATE]} or
+@samp{[ACTUAL_DATE=EFFECtIVE_DATE]}.
+
+@item =
+An automated transaction.  A value expression must appear after the equal
+sign.
+
+After this initial line there should be a set of one or more
+postings, just as if it were normal transaction.  If the amounts of the
+postings have no commodity, they will be applied as modifiers to
+whichever real posting is matched by the value expression.
+
+@item ~
+A period transaction.  A period expression must appear after the tilde.
+
+After this initial line there should be a set of one or more
+postings, just as if it were normal transaction.
+
+@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 journal file.
+
+@item !account
+The account name is given is taken to be the parent of all
+postings 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. Comments will not be returned in a ``print'' response.
+@item indented ; 
+If the semi colon is indented and occurs inside a transaction, it is
+parsed as a persistent note for its preceding category.  These notes or
+tags can be used to augment to reporting and filtering capabilities of
+@ledgerprog.
+@item Y
+If a line begins with a capital Y, it denotes the year used for all
+subsequent transactions 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 transactions 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{transaction} 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 @ledgerprog@ to read
+timelog files.  See the timeclock's documentation for more info on the
+syntax of its timelog files.
+@end table

doc/L3-JournalFormat.texi

@@ -1,80 +1,3 @@
-\input texinfo  @c -*-texinfo-*-
-
-@setfilename ledger.info
-@settitle Ledger: Command-Line Accounting
-
-@dircategory User Applications
-@copying
-Copyright (c) 2003-2010, 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 UTF-8
-
-@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,  , (dir), (dir)
-@top Overview
-
-@insertcopying
-@end ifnottex
-
-@ifnottex
-@section Copyright
-@insertcopying
-@end ifnottex
-
-@chapter Introduction
-
-@chapter Principles of accounting
-
-@chapter Keeping a journal
-
-@chapter Basic reporting commands
-
-@chapter Command-line syntax
-
-@chapter Journal data format
 
 This chapter offers a complete description of the journal data format,
 suitable for implementors in other languages to follow.  For users,
@@ -121,6 +44,10 @@ amount of the first posting is typically positive.  Consider:
     Assets:Checking
 @end example
 
+@emph{Note:} It is important to note that there must be at least two spaces between
+the end of the post and the beginning of the amount (including and
+commdity designator).
+
 @section Specifying amounts
 
 The heart of a journal is the amounts it records, and this fact is
@@ -310,13 +237,3 @@ If a transaction uses only one commodity, this commodity is also
 considered a primary.  In fact, when Ledger goes about ensures that
 all transactions balance to zero, it only ever asks this of primary
 commodities.
-
-@chapter Report queries
-
-@chapter Value expressions
-
-@chapter Format strings
-
-@chapter Extending with Python
-
-@bye

doc/L3-Main.texi

@@ -0,0 +1,96 @@
+\input texinfo  @c -*-texinfo-*-
+
+@setfilename ledger.info
+@settitle Ledger: Command-Line Accounting
+
+@dircategory User Applications
+@copying
+Copyright (c) 2003-2010, 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 UTF-8
+
+@iftex
+@finalout
+@end iftex
+
+@macro ledgerprog
+  @sc{ledger}
+@end macro
+
+
+@titlepage
+@title @ledgerprog: Command-Line Accounting
+@author John Wiegley
+@end titlepage
+
+@direntry
+* Ledger: (ledger).           Command-Line Accounting
+@end direntry
+
+@contents
+
+@ifnottex
+@node Top,  , (dir), (dir)
+@top Overview
+
+@insertcopying
+@end ifnottex
+
+@ifnottex
+@section Copyright
+@insertcopying
+@end ifnottex
+
+
+@chapter Introduction
+
+@include Introduction3.texi
+
+@chapter Principles of accounting
+@include Principles3.texi
+@chapter Keeping a journal
+@include Journal3.texi
+@chapter Basic reporting commands
+
+@chapter Command-line syntax
+@include Syntax3.texi
+@chapter Journal data format
+@include JournalFormat3.texi
+
+@chapter Report queries
+
+@chapter Value expressions
+
+@chapter Format strings
+
+@chapter Extending with Python
+
+@bye

doc/L3-Principles.texi

@@ -0,0 +1,2 @@
+@c -*-texinfo-*-
+