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

184
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
@subsubsection The @code{csv} command
The csv command will output print out the desired ledger transactions in
a csv format suitable for import into other programs. You can determine
the transaction to print using all the normal limiting and searching
The @command{csv} command will output print out the desired ledger transactions in
a csv format suitable for import into other programs. You can specify
the transactions to print using all the normal limiting and searching
functions.
@cindex csv conversion
@cindex reading csv
@cindex comma separated variable file reading
@node The convert command, , The csv command, Comma Separated Variable files
@subsubsection The @code{convert} command
Convert reads your Ledger journal then parses a comma separated value
(csv) file into Ledger transactions. Many banks offer csv file
downloads. Unfortunately the file formats, aside form the commas, are
all different. The ledger convert command tried to help as much as it
The @code{convert} command parses a comma separated value
(csv) file and outputs Ledger transactions. Many banks offer csv file
downloads. Unfortunately the file formats, aside the from commas, are
all different. The ledger @code{convert} command tries to help as much as it
can.
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
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
blocks within a code block. For Ledger, this can be used to group
transactions according to type, say, and then bring various sets of
transactions together to generate reports.
The @command{noweb} feature of babel allows us to expand references to
other code blocks within a code block. For Ledger, this can be used to
group transactions according to type, say, and then bring various sets
of transactions together to generate reports.
Using the same transactions used above, we could consider splitting
these into expenses and income, as follows:
@ -4342,9 +4342,9 @@ transactions.
The overall balance of your account and expenditure with a breakdown
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
<<income>> and <<expenses>>= lines.
@code{<<income>>} and @code{<<expenses>>} lines.
@smallexample
#+name: balance
#+begin_src ledger :cmdline bal :noweb yes
@ -4359,7 +4359,7 @@ results generated by incorporating the transactions referred to by the
@end smallexample
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.
@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
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).
@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
@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
commodities. The output file is in the ``dot'' format.
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.
@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
@subsection prices and pricedb
@subsection @code{prices} and @code{pricedb}
The @command{prices} command displays the price history for matching
commodities. The @option{-A} flag is useful with this report, to
@ -4619,7 +4619,7 @@ database files.
@end menu
@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.
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
@subsection commodities
@subsection @command{commodities}
Report all commodities present in the journals under consideration.
@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
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.
@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
filter the payees displayed you must use the prefix:
@smallexample
@ -4711,18 +4711,18 @@ macbook-2:$
@end menu
@node echo, reload, Developer Commands, Developer Commands
@subsection echo
@subsection @command{echo}
This command simply echos its argument back to the output.
@node reload, source, echo, Developer Commands
@subsection reload
@subsection @command{reload}
Forces ledger to reload any journal files. This function exists to
support external programs controlling a running ledger process and does
nothing for a command line user.
@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
it checking for errors, no other reports are generated, and no other
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
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.
@option{--verify} enable additional assertions during run-time. This
causes a significant slowdown. When combined with @option{--debug}
ledger will produce memory trace information.
@item --verify
enable additional assertions during run-time. This causes a significant
slowdown. When combined with @code{--debug} ledger will produce
memory trace information.
@option{--debug "argument"} If Ledger has been built with debug options
this will provide extra data during the run. The following are the
available arguments to debug:
@item --debug "argument"
If Ledger has been built with debug options this will provide extra data
during the run. The following are the available arguments to debug:
@multitable @columnfractions .32 .43 .27
@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}
@end multitable
@option{--trace INTEGER_TRACE_LEVEL}
@item --trace INTEGER_TRACE_LEVEL
Enable tracing. The integer specifies the level of trace desired:
@multitable @columnfractions .3 .7
@item @code{LOG_OFF} @tab 0
@ -4789,15 +4792,16 @@ Enable tracing. The integer specifies the level of trace desired:
@item @code{LOG_ALL} @tab 11
@end multitable
@option{--verbose}
@item --verbose
Print detailed information on the execution of Ledger.
@option{--version}
@item --version
Print version information and exit.
@end table
@node Pre-commands, , Debug Options, Developer Commands
@subsection Pre-Commands
Pre-commands are useful when you aren't sure how a command or option
Pre-commands are useful when you aren't sure how a command or option
will work.
@table @code
@item args
@ -4821,7 +4825,8 @@ it against a model transaction.
Print details of how ledger uses the given formatting description and
apply it against a model transaction.
@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>
Print details of how ledger uses the given value expression description
and apply it against a model transaction.
@ -4885,7 +4890,8 @@ model transaction:
true
@end smallexample
@item template
FIX THIS ENTRY
Shows the insertion template that a "draft" or "xact" sub-command generates.
This is a debugging command.
@end table
@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{} @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{--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{-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
@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{-j} @tab @code{--amount-data} @tab Show only date and value column
@item @code{-J} @tab @code{--total-data} @tab Show only dates and totals
@item @code{-d EXPR} @tab @code{--display EXPR} @tab Limit only the display of certain postings
@item @code{-j} @tab @code{--amount-data} @tab Show only date and value column to format the output for plots
@item @tab @code{--plot-amount-format STR} @tab specify the format for the plot output
@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{-F STR} @tab @code{--format STR} @tab Set reporting format
@item @code{} @tab @code{--balance-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{-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
@ -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}).
@item --master-account <ARGUMENT>
@item --master-account <STRING>
Prepends all account names with the argument.
@smallexample
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.
@item --forecast-while
@item --forecast-while <VEXPR>
Continue forecasting while @code{<VEXPR>} is true.
FIX THIS ENTRY
@item --forecast-years
FIX THIS ENTRY
@item --forecast-years <INT>
Forecast at most @code{N} years in the future.
@item --format <FORMAT STRING>
@ -5563,11 +5567,12 @@ use the given format string to print output.
@item --gain
report on gains using the latest available prices .
report on gains using the latest available prices.
@item --generated
ASK JOHN
Include auto-generated postings (such as those from automated transactions)
in the report, in cases where you normally wouldn't want
them.
@item --group-by <EXPR>
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.
@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
FIX THIS ENTRY
Specify the width of the Meta column used for the @code{--meta} options.
@item --monthly
@ -5657,8 +5662,8 @@ synonymn for @code{--period "monthly"}
suppress any color TTY output.
@item --no-rounding
FIX THIS ENTRY
Don't output <Rounding> postings. Note that this will cause the running total
to often not add up! It's main use is for @code{-j} and @code{-J} reports.
@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
FIX THIS ENTRY
This is a postings predicate that applies after certain
transforms have been executed, such as periodic gathering.
@item --output <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.
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
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
balances.
@item --pivot <metatag>
@item --pivot <VALUED TAG>
Produce a balance pivot report ``around'' the given tag. For example,
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
@end smallexample
@xref{Metadata values}.
@item --plot-amount-format
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
FIX THIS ENTRY
use the price of the commodity purchase for performing calculations
@item --quantity
@ -5757,7 +5763,10 @@ Synonym for @code{--period "quarterly"}.
@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
Account using only real transactions ignoring virtual
@ -5788,7 +5797,7 @@ FIX THIS ENTRY
@item --seed
FIX THIS ENTRY
Sets the random seed for the @code{generate} command. Used as part of development testing.
@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.
@item --truncate
FIX THIS ENTRY
Indicates how truncation should happen when the contents of columns
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
@ -5933,7 +5945,8 @@ report, in ways other than just using regular expressions:
displays only transactions occurring on or before the current 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
means that the running total in the balance report will always start at
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.
@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
to see weekly, monthly, quarterly, etc., posting totals. A period
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
@chapter Value Expressions
Value expressions are an expression language used by Ledger to
calculate values used by the program for many different purposes:
Ledger uses value expressions to make
calculations for many different purposes:
@enumerate
@item
@ -6739,19 +6753,21 @@ In the matching criteria used by automated postings.
@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:
addition to a set of functions and variables.
@smallexample
ledger -d /^Liabilities/?T<0:UT>100 balance
@end smallexample
@c A function's
@c argument is whatever follows it. The following is a display predicate
@c that I use with the @command{balance} command:
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.
@c @smallexample
@c ledger -d /^Liabilities/?T<0:UT>100 balance
@c @end smallexample
@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
constrain which transactions are printed. For example, the following