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

formatting and grammar cleanup

Browse source
This commit is contained in:
Craig Earls 2012-10-10 21:21:00 -07:00
parent d7a03c4716
commit 8c7ac50fd8
1 changed files with 100 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

180
doc/ledger3.texi
View file

@ -4054,19 +4054,19 @@ file whose formatting has gotten out of hand.
@node The csv command, The convert command, Comma Separated Variable files, Comma Separated Variable files @node The csv command, The convert command, Comma Separated Variable files, Comma Separated Variable files
@subsubsection The @code{csv} command @subsubsection The @code{csv} command
The csv command will output print out the desired ledger transactions in The @command{csv} command will output print out the desired ledger transactions in
a csv format suitable for import into other programs. You can determine a csv format suitable for import into other programs. You can specify
the transaction to print using all the normal limiting and searching the transactions to print using all the normal limiting and searching
functions. functions.
@cindex csv conversion @cindex csv conversion
@cindex reading csv @cindex reading csv
@cindex comma separated variable file reading @cindex comma separated variable file reading
@node The convert command, , The csv command, Comma Separated Variable files @node The convert command, , The csv command, Comma Separated Variable files
@subsubsection The @code{convert} command @subsubsection The @code{convert} command
Convert reads your Ledger journal then parses a comma separated value The @code{convert} command parses a comma separated value
(csv) file into Ledger transactions. Many banks offer csv file (csv) file and outputs Ledger transactions. Many banks offer csv file
downloads. Unfortunately the file formats, aside form the commas, are downloads. Unfortunately the file formats, aside the from commas, are
all different. The ledger convert command tried to help as much as it all different. The ledger @code{convert} command tries to help as much as it
can. can.
Your banks csv files will have fields in different orders from other Your banks csv files will have fields in different orders from other
@ -4277,12 +4277,12 @@ financial state. Eventually, babel will support passing arguments to
currently. Instead, we can use the concepts of literary programming, as currently. Instead, we can use the concepts of literary programming, as
implemented by the noweb features of babel, to help us. implemented by the noweb features of babel, to help us.
@subsubheading Multiple Ledger source blocks with noweb @subsubheading Multiple Ledger source blocks with @command{noweb}
The noweb feature of babel allows us to expand references to other code The @command{noweb} feature of babel allows us to expand references to
blocks within a code block. For Ledger, this can be used to group other code blocks within a code block. For Ledger, this can be used to
transactions according to type, say, and then bring various sets of group transactions according to type, say, and then bring various sets
transactions together to generate reports. of transactions together to generate reports.
Using the same transactions used above, we could consider splitting Using the same transactions used above, we could consider splitting
these into expenses and income, as follows: these into expenses and income, as follows:
@ -4342,9 +4342,9 @@ transactions.
The overall balance of your account and expenditure with a breakdown The overall balance of your account and expenditure with a breakdown
according to category is specified by passing the :cmdline bal argument according to category is specified by passing the :cmdline bal argument
to Ledger. This code block can now be evaluated (C-c C-c) and the to Ledger. This code block can now be evaluated (@code{C-c C-c}) and the
results generated by incorporating the transactions referred to by the results generated by incorporating the transactions referred to by the
<<income>> and <<expenses>>= lines. @code{<<income>>} and @code{<<expenses>>} lines.
@smallexample @smallexample
#+name: balance #+name: balance
#+begin_src ledger :cmdline bal :noweb yes #+begin_src ledger :cmdline bal :noweb yes
@ -4359,7 +4359,7 @@ results generated by incorporating the transactions referred to by the
@end smallexample @end smallexample
If you want a more detailed breakdown of where your money is and where If you want a more detailed breakdown of where your money is and where
it has been spent, you can specify the -s flag (i.e. :cmdline -s bal) to it has been spent, you can specify the -s flag (i.e. @code{:cmdline -s bal}) to
tell Ledger to include sub-accounts in the report. tell Ledger to include sub-accounts in the report.
@smallexample @smallexample
@ -4384,7 +4384,7 @@ tell Ledger to include sub-accounts in the report.
You can also generate a monthly register (the reg command) by executing You can also generate a monthly register (the reg command) by executing
the following src block. This presents a summary of transactions for the following src block. This presents a summary of transactions for
each monthly period (the -M argument) with a running total in the final each monthly period (the @code{-M} argument) with a running total in the final
column (which should be 0 at the end if all the entries are correct). column (which should be 0 at the end if all the entries are correct).
@smallexample @smallexample
@ -4435,12 +4435,12 @@ examples of more complex operations with a ledger.
@node The pricemap Command, The xml Command, Emacs org mode, Reports in other Formats @node The pricemap Command, The xml Command, Emacs org mode, Reports in other Formats
@subsection The @code{pricemap} Command @subsection The @code{pricemap} Command
If you have the graphviz graph visualization package installed, ledger If you have the @code{graphviz} graph visualization package installed, ledger
can generate a graph of the relationship between your various can generate a graph of the relationship between your various
commodities. The output file is in the ``dot'' format. commodities. The output file is in the ``dot'' format.
This is probably not very interesting, unless you have many different This is probably not very interesting, unless you have many different
commdities valued in terms of each other. For example, multiple commodities valued in terms of each other. For example, multiple
currencies and multiples investments valued in those currencies. currencies and multiples investments valued in those currencies.
@node The xml Command, prices and pricedb, The pricemap Command, Reports in other Formats @node The xml Command, prices and pricedb, The pricemap Command, Reports in other Formats
@ -4595,7 +4595,7 @@ the same data.
@node prices and pricedb, , The xml Command, Reports in other Formats @node prices and pricedb, , The xml Command, Reports in other Formats
@subsection prices and pricedb @subsection @code{prices} and @code{pricedb}
The @command{prices} command displays the price history for matching The @command{prices} command displays the price history for matching
commodities. The @option{-A} flag is useful with this report, to commodities. The @option{-A} flag is useful with this report, to
@ -4619,7 +4619,7 @@ database files.
@end menu @end menu
@node accounts, commodities, Reports about your Journals, Reports about your Journals @node accounts, commodities, Reports about your Journals, Reports about your Journals
@subsection accounts @subsection @code{accounts}
The @command{accounts} reports all of the accounts in the journal. The @command{accounts} reports all of the accounts in the journal.
Following the command with a regular expression will limit the output to Following the command with a regular expression will limit the output to
@ -4627,12 +4627,12 @@ accounts matching the regex.
@node commodities, entry and xact, accounts, Reports about your Journals @node commodities, entry and xact, accounts, Reports about your Journals
@subsection commodities @subsection @command{commodities}
Report all commodities present in the journals under consideration. Report all commodities present in the journals under consideration.
@node entry and xact, payees, commodities, Reports about your Journals @node entry and xact, payees, commodities, Reports about your Journals
@subsection entry and xact @subsection @command{entry} and @command{xact}
The @code{entry} and @command{xact} commands simplify the creation of The @code{entry} and @command{xact} commands simplify the creation of
new transactions. It works on the principle that 80% of all postings new transactions. It works on the principle that 80% of all postings
@ -4686,7 +4686,7 @@ ledger xact 4/9 viva dining "DM 11.50"
backwards compatibility with Ledger 2.X. backwards compatibility with Ledger 2.X.
@node payees, , entry and xact, Reports about your Journals @node payees, , entry and xact, Reports about your Journals
@subsection payees @subsection @code{payees}
The @command{payees} reports all of the unique payees in the journal. To The @command{payees} reports all of the unique payees in the journal. To
filter the payees displayed you must use the prefix: filter the payees displayed you must use the prefix:
@smallexample @smallexample
@ -4711,18 +4711,18 @@ macbook-2:$
@end menu @end menu
@node echo, reload, Developer Commands, Developer Commands @node echo, reload, Developer Commands, Developer Commands
@subsection echo @subsection @command{echo}
This command simply echos its argument back to the output. This command simply echos its argument back to the output.
@node reload, source, echo, Developer Commands @node reload, source, echo, Developer Commands
@subsection reload @subsection @command{reload}
Forces ledger to reload any journal files. This function exists to Forces ledger to reload any journal files. This function exists to
support external programs controlling a running ledger process and does support external programs controlling a running ledger process and does
nothing for a command line user. nothing for a command line user.
@node source, Debug Options, reload, Developer Commands @node source, Debug Options, reload, Developer Commands
@subsection source @subsection @command{source}
The @code{source} command take a journal file as an argument and parses The @code{source} command take a journal file as an argument and parses
it checking for errors, no other reports are generated, and no other it checking for errors, no other reports are generated, and no other
arguments are necessary. Ledger will return success if no errors are arguments are necessary. Ledger will return success if no errors are
@ -4734,16 +4734,19 @@ found.
These options are primarily for Ledger developers, but may be of some These options are primarily for Ledger developers, but may be of some
use to a user trying something new. use to a user trying something new.
@option{--args-only} ignore init @table @code
@item --args-only
ignore init
files and environment variables for the ledger run. files and environment variables for the ledger run.
@option{--verify} enable additional assertions during run-time. This @item --verify
causes a significant slowdown. When combined with @option{--debug} enable additional assertions during run-time. This causes a significant
ledger will produce memory trace information. slowdown. When combined with @code{--debug} ledger will produce
memory trace information.
@option{--debug "argument"} If Ledger has been built with debug options @item --debug "argument"
this will provide extra data during the run. The following are the If Ledger has been built with debug options this will provide extra data
available arguments to debug: during the run. The following are the available arguments to debug:
@multitable @columnfractions .32 .43 .27 @multitable @columnfractions .32 .43 .27
@item @code{account.display} @tab @code{expr.calc.when} @tab @code{org.next_amount} @item @code{account.display} @tab @code{expr.calc.when} @tab @code{org.next_amount}
@ -4772,7 +4775,7 @@ available arguments to debug:
@item @code{expr.calc} @tab @code{option.names} @item @code{expr.calc} @tab @code{option.names}
@end multitable @end multitable
@option{--trace INTEGER_TRACE_LEVEL} @item --trace INTEGER_TRACE_LEVEL
Enable tracing. The integer specifies the level of trace desired: Enable tracing. The integer specifies the level of trace desired:
@multitable @columnfractions .3 .7 @multitable @columnfractions .3 .7
@item @code{LOG_OFF} @tab 0 @item @code{LOG_OFF} @tab 0
@ -4789,11 +4792,12 @@ Enable tracing. The integer specifies the level of trace desired:
@item @code{LOG_ALL} @tab 11 @item @code{LOG_ALL} @tab 11
@end multitable @end multitable
@option{--verbose} @item --verbose
Print detailed information on the execution of Ledger. Print detailed information on the execution of Ledger.
@option{--version} @item --version
Print version information and exit. Print version information and exit.
@end table
@node Pre-commands, , Debug Options, Developer Commands @node Pre-commands, , Debug Options, Developer Commands
@subsection Pre-Commands @subsection Pre-Commands
@ -4821,7 +4825,8 @@ it against a model transaction.
Print details of how ledger uses the given formatting description and Print details of how ledger uses the given formatting description and
apply it against a model transaction. apply it against a model transaction.
@item generate @item generate
FIX THIS ENTRY Randomly generates syntactically valid Ledger data from a seed. Used by the
GenerateTests harness for development testing
@item parse <VALUE EXPR> @item parse <VALUE EXPR>
Print details of how ledger uses the given value expression description Print details of how ledger uses the given value expression description
and apply it against a model transaction. and apply it against a model transaction.
@ -4885,7 +4890,8 @@ model transaction:
true true
@end smallexample @end smallexample
@item template @item template
FIX THIS ENTRY Shows the insertion template that a "draft" or "xact" sub-command generates.
This is a debugging command.
@end table @end table
@node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, Top @node Command-line Syntax, Budgeting and Forecasting, Reporting Commands, Top
@ -5032,21 +5038,21 @@ commands.
@item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80 @item @code{-w} @tab @code{--wide} @tab Assume 132 columns instead of 80
@item @code{} @tab @code{--head N} @tab Report the first N postings @item @code{} @tab @code{--head N} @tab Report the first N postings
@item @code{} @tab @code{--tail N} @tab Report the last N postings @item @code{} @tab @code{--tail N} @tab Report the last N postings
@item @code{} @tab @code{--pager prog} @tab Direct output @code{prog} pager program @item @code{} @tab @code{--pager PATH} @tab Direct output to @code{PATH} pager program
@item @code{-A} @tab @code{--average} @tab Reports average posting value @item @code{-A} @tab @code{--average} @tab Reports average posting value
@item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average @item @code{-D} @tab @code{--deviation} @tab Reports each posting deviation from the average
@item @code{-%} @tab @code{--percent} @tab Show subtotals in the balance report as percentages @item @code{-%} @tab @code{--percent} @tab Show subtotals in the balance report as percentages
@c @item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report @c @item @code{} @tab @code{--totals} @tab Include running total in the @code{xml} report
@item @code{} @tab @code{--pivot TAG} @tab produce a pivot table of the tag type specified @item @code{} @tab @code{--pivot TAG} @tab produce a pivot table of the tag type specified
@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column @item @code{-j} @tab @code{--amount-data} @tab Show only date and value column to format the output for plots
@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals @item @tab @code{--plot-amount-format STR} @tab specify the format for the plot output
@item @code{-d EXPR} @tab @code{--display EXPR} @tab Limit only the display of certain postings @item @code{-J} @tab @code{--total-data} @tab Show only dates and totals to format the output for plots
@item @tab @code{--plot-total-format STR} @tab specify the format for the plot output
@item @code{-d EXPR} @tab @code{--display EXPR} @tab Display only posting that meet the criteris in the EXPR
@item @code{-y STR} @tab @code{--date-format STR} @tab Change the basic date format used in reports @item @code{-y STR} @tab @code{--date-format STR} @tab Change the basic date format used in reports
@item @code{-F STR} @tab @code{--format STR} @tab Set reporting format @item @code{-F STR} @tab @code{--format STR} @tab Set reporting format
@item @code{} @tab @code{--balance-format STR} @tab @item @code{} @tab @code{--balance-format STR} @tab
@item @code{} @tab @code{--register-format STR} @tab @item @code{} @tab @code{--register-format STR} @tab
@item @code{-j register} @tab @code{--plot-amount-format STR} @tab format the output of a amount plots
@item @code{-J register} @tab @code{--plot-total-format STR} @tab format the output of a total plot
@item @code{} @tab @code{--prices-format STR} @tab @item @code{} @tab @code{--prices-format STR} @tab
@item @code{-w register} @tab @code{--wide-register-format STR} @tab @item @code{-w register} @tab @code{--wide-register-format STR} @tab
@item @code{} @tab @code{--anon} @tab Print the ledger register with anonymized accounts and payees, useful for filing bug reports @item @code{} @tab @code{--anon} @tab Print the ledger register with anonymized accounts and payees, useful for filing bug reports
@ -5196,7 +5202,7 @@ Would convert the @file{Export.csv} file to ledger format, assuming the
the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time Format Codes}). the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time Format Codes}).
@item --master-account <ARGUMENT> @item --master-account <STRING>
Prepends all account names with the argument. Prepends all account names with the argument.
@smallexample @smallexample
21:51:39 ~/ledger (next)> ledger -f test/input/drewr3.dat bal --master-account HUMBUG 21:51:39 ~/ledger (next)> ledger -f test/input/drewr3.dat bal --master-account HUMBUG
@ -5549,13 +5555,11 @@ correctly.
force Ledger to paginate its output. force Ledger to paginate its output.
@item --forecast-while @item --forecast-while <VEXPR>
Continue forecasting while @code{<VEXPR>} is true.
FIX THIS ENTRY @item --forecast-years <INT>
Forecast at most @code{N} years in the future.
@item --forecast-years
FIX THIS ENTRY
@item --format <FORMAT STRING> @item --format <FORMAT STRING>
@ -5566,8 +5570,9 @@ use the given format string to print output.
report on gains using the latest available prices. report on gains using the latest available prices.
@item --generated @item --generated
Include auto-generated postings (such as those from automated transactions)
ASK JOHN in the report, in cases where you normally wouldn't want
them.
@item --group-by <EXPR> @item --group-by <EXPR>
group transaction together in the register group transaction together in the register
@ -5640,13 +5645,13 @@ Report the date and price at which each commodity was purchased in a balance rep
Use the latest market value for all commodities. Use the latest market value for all commodities.
@item --meta @item --meta <TAG>
FIX THIS ENTRY In the register report, prepend the transaction with the value of the given tag.
@item --meta-width @item --meta-width
FIX THIS ENTRY Specify the width of the Meta column used for the @code{--meta} options.
@item --monthly @item --monthly
@ -5657,8 +5662,8 @@ synonymn for @code{--period "monthly"}
suppress any color TTY output. suppress any color TTY output.
@item --no-rounding @item --no-rounding
Don't output <Rounding> postings. Note that this will cause the running total
FIX THIS ENTRY to often not add up! It's main use is for @code{-j} and @code{-J} reports.
@item --no-titles @item --no-titles
@ -5673,7 +5678,8 @@ Define the current date in case to you to do calculate in the past or future usi
@item --only @item --only
FIX THIS ENTRY This is a postings predicate that applies after certain
transforms have been executed, such as periodic gathering.
@item --output <PATH> @item --output <PATH>
Redriect the output of ledger to the file defined in @file{PATH}. Redriect the output of ledger to the file defined in @file{PATH}.
@ -5700,7 +5706,7 @@ Use only postings that are marked pending
Calculate the percentage value of each account in a blance reports. Calculate the percentage value of each account in a blance reports.
Only works for account that have a single commoditiy. Only works for account that have a single commoditiy.
@item --period <period expression> @item --period <PERIOD EXPRESSION>
Define a period expression the sets the time period during which Define a period expression the sets the time period during which
transactions are to be accounted. For a register report only th transactions are to be accounted. For a register report only th
@ -5708,7 +5714,7 @@ transactions that satisfy the period expression with be displayed. For
a balance report only those transactions will be accounted in the final a balance report only those transactions will be accounted in the final
balances. balances.
@item --pivot <metatag> @item --pivot <VALUED TAG>
Produce a balance pivot report ``around'' the given tag. For example, Produce a balance pivot report ``around'' the given tag. For example,
if you have multiple cars and track each fuel purchase in if you have multiple cars and track each fuel purchase in
@ -5726,6 +5732,7 @@ ledger bal Fuel --pivot "Car" --period "this year"
$ 3533.95 $ 3533.95
@end smallexample @end smallexample
@xref{Metadata values}.
@item --plot-amount-format @item --plot-amount-format
Define the output format for a amount data plot. @xref{Visualizing with Gnuplot}. Define the output format for a amount data plot. @xref{Visualizing with Gnuplot}.
@ -5744,8 +5751,7 @@ Reserve @code{N} spaces at the beginning of each line of the output
@item --price @item --price
use the price of the commodity purchase for performing calculations
FIX THIS ENTRY
@item --quantity @item --quantity
@ -5757,7 +5763,10 @@ Synonym for @code{--period "quarterly"}.
@item --raw @item --raw
FIX THIS ENTRY In the print report, show transactions using the exact same syntax as
specified by the user in their data file. Don't do any massaging or
interpreting. Can be useful for minor cleanups, like just aligning
amounts.
@item --real @item --real
Account using only real transactions ignoring virtual Account using only real transactions ignoring virtual
@ -5788,7 +5797,7 @@ FIX THIS ENTRY
@item --seed @item --seed
FIX THIS ENTRY Sets the random seed for the @code{generate} command. Used as part of development testing.
@item --sort-all @item --sort-all
@ -5826,8 +5835,11 @@ Define a vlaue expression used to calulate the total in reports.
Set the width of the total field in the register report. Set the width of the total field in the register report.
@item --truncate @item --truncate
Indicates how truncation should happen when the contents of columns
FIX THIS ENTRY exceed their width. Valid arguments are @code{leading}, @code{middle},
and @code{trailing}. The default is smarter than any of these three, as
it considers sub-names within the account name (that style is called
``abbreviate''.
@item --unbudgeted @item --unbudgeted
@ -5933,7 +5945,8 @@ report, in ways other than just using regular expressions:
displays only transactions occurring on or before the current date. displays only transactions occurring on or before the current date.
@item --begin DATE @item --begin DATE
@item -b DATE constrains the report to transactions on or after @item -b DATE
constrains the report to transactions on or after
@var{DATE}. Only transactions after that date will be calculated, which @var{DATE}. Only transactions after that date will be calculated, which
means that the running total in the balance report will always start at means that the running total in the balance report will always start at
zero with the first matching transaction. (Note: This is different from zero with the first matching transaction. (Note: This is different from
@ -5945,7 +5958,8 @@ constrains the report so that transactions on or after @var{DATE} are
not considered. The ending date is inclusive. not considered. The ending date is inclusive.
@item --period STR @item --period STR
@item -p STR sets the reporting period to @var{STR}. This will subtotal @item -p STR
sets the reporting period to @var{STR}. This will subtotal
all matching transactions within each period separately, making it easy all matching transactions within each period separately, making it easy
to see weekly, monthly, quarterly, etc., posting totals. A period to see weekly, monthly, quarterly, etc., posting totals. A period
string can even specify the beginning and end of the report range, using string can even specify the beginning and end of the report range, using
@ -6723,8 +6737,8 @@ ledger --forecast "d<[2010]" bal ^assets ^liabilities
@node Value Expressions, Format Strings, Budgeting and Forecasting, Top @node Value Expressions, Format Strings, Budgeting and Forecasting, Top
@chapter Value Expressions @chapter Value Expressions
Value expressions are an expression language used by Ledger to Ledger uses value expressions to make
calculate values used by the program for many different purposes: calculations for many different purposes:
@enumerate @enumerate
@item @item
@ -6739,19 +6753,21 @@ In the matching criteria used by automated postings.
@end enumerate @end enumerate
Value expressions support most simple math and logic operators, in Value expressions support most simple math and logic operators, in
addition to a set of one letter functions and variables. A function's addition to a set of functions and variables.
argument is whatever follows it. The following is a display predicate
that I use with the @command{balance} command:
@smallexample @c A function's
ledger -d /^Liabilities/?T<0:UT>100 balance @c argument is whatever follows it. The following is a display predicate
@end smallexample @c that I use with the @command{balance} command:
The effect is that account totals are displayed only if: 1) A @c @smallexample
Liabilities account has a total less than zero; or 2) the absolute @c ledger -d /^Liabilities/?T<0:UT>100 balance
value of the account's total exceeds 100 units of whatever commodity @c @end smallexample
contains. If it contains multiple commodities, only one of them must
exceed 100 units. @c The effect is that account totals are displayed only if: 1) A
@c Liabilities account has a total less than zero; or 2) the absolute
@c value of the account's total exceeds 100 units of whatever commodity
@c contains. If it contains multiple commodities, only one of them must
@c exceed 100 units.
Display predicates are also very handy with register reports, to Display predicates are also very handy with register reports, to
constrain which transactions are printed. For example, the following constrain which transactions are printed. For example, the following