formatting and grammar cleanup

1 files changed, 100 insertions, 84 deletions

diff --git a/doc/ledger3.texi b/doc/ledger3.texi
index 08be7551..4cc28f43 100644
--- a/doc/ledger3.texi
+++ b/doc/ledger3.texi
@@ -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
-
-FIX THIS ENTRY
-
-@item --forecast-years
+@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 --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:
+
+@c @smallexample
+@c ledger -d /^Liabilities/?T<0:UT>100 balance
+@c @end smallexample
 
-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 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