diff options
| -rw-r--r-- | doc/ledger3.texi | 554 | ||||
| -rwxr-xr-x | test/CheckTexinfo.py | 34 |
2 files changed, 311 insertions, 277 deletions
diff --git a/doc/ledger3.texi b/doc/ledger3.texi index ab3c8823..9597083c 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -5401,7 +5401,7 @@ required to use the basic reporting commands. @node Basic Reporting Commands, Basic Options, Command-Line Quick Reference, Command-Line Quick Reference @subsection Basic Reporting Commands -@ftable @code +@ftable @command @item balance @itemx bal @@ -5443,29 +5443,29 @@ Generate transactions based on previous postings. @node Basic Options, Report Filtering, Basic Reporting Commands, Command-Line Quick Reference @subsection Basic Options -@ftable @code +@ftable @option -@item --help @c option +@item --help @itemx -h Print summary of all options. -@item --version @c option +@item --version @itemx -v Print version information and exit. -@item --file @var{FILE} @c option +@item --file @var{FILE} @itemx -f @var{FILE} Read @file{FILE} as a ledger file. -@item --output @var{FILE} @c option +@item --output @var{FILE} @itemx -o @var{FILE} Redirect output to @file{FILE}. -@item --init-file @var{FILE} @c option +@item --init-file @var{FILE} @itemx -i @var{FILE} Specify an options file. -@item --account @var{STR} @c option +@item --account @var{STR} @itemx -a @var{STR} Specify default account @var{STR} for QIF file postings. @@ -5474,72 +5474,72 @@ Specify default account @var{STR} for QIF file postings. @node Report Filtering, Error Checking and Calculation Options, Basic Options, Command-Line Quick Reference @subsection Report Filtering -@ftable @code +@ftable @option -@item --current @c option +@item --current @itemx -c Display only transactions on or before the current date. -@item --begin @var{DATE} @c option +@item --begin @var{DATE} @itemx -b @var{DATE} Limit the processing to transactions on or after @var{DATE}. -@item --end @var{DATE} @c option +@item --end @var{DATE} @itemx -e @var{DATE} Limit the processing to transactions before @var{DATE}. -@item --period @var{PERIOD_EXPRESSION} @c option +@item --period @var{PERIOD_EXPRESSION} @itemx -p @var{PERIOD_EXPRESSION} Limit the processing to transactions in @var{PERIOD_EXPRESSION}. -@item --period-sort @var{VEXPR} @c option +@item --period-sort @var{VEXPR} Sort postings within each period according to @var{VEXPR}. -@item --cleared @c option +@item --cleared @itemx -C Display only cleared postings. -@item --dc @c option +@item --dc Display register or balance in debit/credit format. -@item --uncleared @c option +@item --uncleared @itemx -U Display only uncleared postings. -@item --real @c option +@item --real @itemx -R Display only real postings. -@item --actual @c option +@item --actual @itemx -L Display only actual postings, not automated ones. -@item --related @c option +@item --related @itemx -r Display related postings. -@item --budget @c option +@item --budget Display how close your postings meet your budget. -@item --add-budget @c option +@item --add-budget Show unbudgeted postings. -@item --unbudgeted @c option +@item --unbudgeted Show only unbudgeted postings. -@item --forecast-while @var{VEXPR} @c option +@item --forecast-while @var{VEXPR} @itemx --forecast @var{VEXPR} Project balances into the future. -@item --limit @var{EXPR} @c option +@item --limit @var{EXPR} @itemx -l @var{EXPR} Limit which postings are used in calculations by @var{EXPR}. -@item --amount @var{EXPR} @c option +@item --amount @var{EXPR} @itemx -t @var{EXPR} Change value expression reported in @command{register} report. -@item --total @var{VEXPR} @c option +@item --total @var{VEXPR} @itemx -T @var{VEXPR} Change the value expression used for ``totals'' column in @command{register} and @command{balance} reports. @@ -5549,21 +5549,21 @@ Change the value expression used for ``totals'' column in @node Error Checking and Calculation Options, Output Customization, Report Filtering, Command-Line Quick Reference @subsection Error Checking and Calculation Options -@ftable @code +@ftable @option -@item --strict @c option +@item --strict Accounts, tags or commodities not previously declared will cause warnings. -@item --pedantic @c option +@item --pedantic Accounts, tags or commodities not previously declared will cause errors. -@item --check-payees @c option +@item --check-payees Enable strict and pedantic checking for payees as well as accounts, commodities and tags. This only works in conjunction with @option{--strict} or @option{--pedantic}. -@item --immediate @c option +@item --immediate Instruct ledger to evaluate calculations immediately rather than lazily. @end ftable @@ -5571,91 +5571,91 @@ Instruct ledger to evaluate calculations immediately rather than lazily. @node Output Customization, Grouping Options, Error Checking and Calculation Options, Command-Line Quick Reference @subsection Output Customization -@ftable @code +@ftable @option -@item --collapse @c option +@item --collapse @itemx -n Collapse transactions with multiple postings. -@item --subtotal @c option +@item --subtotal @itemx -s Report register as a single subtotal. -@item --by-payee @c option +@item --by-payee @itemx -P Report subtotals by payee. -@item --empty @c option +@item --empty @itemx -E Include empty accounts in the report. -@item --weekly @c option +@item --weekly @itemx -W Report posting totals by week. -@item --quarterly @c option +@item --quarterly Report posting totals by quarter. -@item --yearly @c option +@item --yearly @itemx -Y Report posting totals by year. -@item --dow @c option +@item --dow Report posting totals by day of week. -@item --sort @var{VEXPR} @c option +@item --sort @var{VEXPR} @itemx -S @var{VEXPR} Sort a report using @var{VEXPR}. -@item --wide @c option +@item --wide @itemx -w Assume 132 columns instead of 80. -@item --head @var{INT} @c option +@item --head @var{INT} Report the first @var{INT} postings. -@item --tail @var{INT} @c option +@item --tail @var{INT} Report the last @var{INT} postings. -@item --pager @var{FILE} @c option +@item --pager @var{FILE} Direct output to @var{FILE} pager program. -@item --average @c option +@item --average @itemx -A Report the average posting value. -@item --deviation @c option +@item --deviation @itemx -D Report each posting's deviation from the average. -@item --percent @c option +@item --percent @itemx -% Show subtotals in the balance report as percentages. @c @item --totals @c Include running total in the @command{xml} report -@item --pivot @var{TAG} @c option +@item --pivot @var{TAG} Produce a pivot table of the @var{TAG} type specified. -@item --amount-data @c option +@item --amount-data @itemx -j Show only the date and value columns to format the output for plots. -@item --plot-amount-format @var{FORMAT_STRING} @c option +@item --plot-amount-format @var{FORMAT_STRING} Specify the format for the plot output. -@item --total-data @c option +@item --total-data @itemx -J Show only the date and total columns to format the output for plots. -@item --plot-total-format @var{FORMAT_STRING} @c option +@item --plot-total-format @var{FORMAT_STRING} Specify the format for the plot output. -@item --display @var{EXPR} @c option +@item --display @var{EXPR} @itemx -d @var{EXPR} Display only postings that meet the criteria in the @var{EXPR}. -@item --date-format @var{DATE_FORMAT} @c option +@item --date-format @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT} Change the basic date format used in reports. @@ -5666,7 +5666,7 @@ Change the basic date format used in reports. @itemx -F @var{FORMAT_STRING} Set the reporting format for various reports. -@item --anon @c option +@item --anon Print the ledger register with anonymized accounts and payees, useful for filing bug reports. @@ -5675,35 +5675,35 @@ for filing bug reports. @node Grouping Options, Commodity Reporting, Output Customization, Command-Line Quick Reference @subsection Grouping Options -@ftable @code +@ftable @option -@item --by-payee @c option +@item --by-payee @itemx -P Group postings by common payee names. -@item --daily @c option +@item --daily @itemx -D Group postings by day. -@item --weekly @c option +@item --weekly @itemx -W Group postings by week. -@item --monthly @c option +@item --monthly @itemx -M Group postings by month. -@item --quarterly @c option +@item --quarterly Group postings by quarter. -@item --yearly @c option +@item --yearly @itemx -Y Group postings by year. -@item --dow @c option +@item --dow Group by day of weeks. -@item --subtotal @c option +@item --subtotal @itemx -s Group postings together, similar to the balance report. @@ -5712,35 +5712,35 @@ Group postings together, similar to the balance report. @node Commodity Reporting, , Grouping Options, Command-Line Quick Reference @subsection Commodity Reporting -@ftable @code +@ftable @option -@item --price-db @var{FILE} @c option +@item --price-db @var{FILE} Use @file{FILE} for retrieving stored commodity prices. -@item --price-exp @var{INT} @c option +@item --price-exp @var{INT} @itemx -Z @var{INT} Set expected freshness of prices in @var{INT} minutes. -@item --download @c option +@item --download @itemx -Q Download quotes using the script named @file{getquote}. -@item --getquote @var{FILE} @c option +@item --getquote @var{FILE} Sets the path to a user-defined script to download commodity prices. -@item --quantity @c option +@item --quantity @itemx -O Report commodity totals without conversion. -@item --basis @c option +@item --basis @itemx -B Report cost basis. -@item --market @c option +@item --market @itemx -V Report last known market value. -@item --gain @c option +@item --gain @itemx -G Report net gain or loss for commodities that have a price history. @@ -5770,25 +5770,25 @@ GUIs, which would make use of the different scopes by keeping an instance of Ledger running in the background and running multiple sessions with multiple reports per session. -@ftable @code +@ftable @option -@item --args-only @c option +@item --args-only Ignore all environment and init-file settings and use only command-line arguments to control Ledger. Useful for debugging or testing small journal files not associated with your main financial database. -@item --debug @var{CODE} @c option +@item --debug @var{CODE} FIX THIS ENTRY @c FIXME thdox -@item --help @c option +@item --help @itemx -h Display the man page for ledger. -@item --init-file @var{FILE} @c option +@item --init-file @var{FILE} Specify the location of the init file. The default is @file{~/.ledgerrc}. -@item --options @c option +@item --options Display the options in effect for this Ledger invocation, along with their values and the source of those values, for example: @@ -5824,17 +5824,17 @@ with a @samp{$}, the source was an environment variable. If the source is @code{?normalize} the value was set internally by ledger, in a function called @code{normalize_options}. -@item --script @var{FILE} @c option +@item --script @var{FILE} Execute a ledger script. -@item --trace @var{INT} @c option +@item --trace @var{INT} Enable tracing. The @var{INT} specifies the level of trace desired. -@item --verbose @c option +@item --verbose @itemx -v Print detailed information on the execution of Ledger. -@item --verify @c option +@item --verify Enable additional assertions during run-time. This causes a significant slowdown. When combined with @option{--debug @var{CODE}} ledger will produce memory trace information. @@ -5857,7 +5857,7 @@ GUIs, which would make use of the different scopes by keeping an instance of Ledger running in the background and running multiple sessions with multiple reports per session. -@ftable @code +@ftable @option @item --cache @var{FIXME} FIX THIS ENTRY @c FIXME thdox @@ -5868,29 +5868,29 @@ FIX THIS ENTRY @c FIXME thdox @item --day-break FIX THIS ENTRY @c FIXME thdox -@item --decimal-comma @c option +@item --decimal-comma Direct Ledger to parse journals using the European standard comma as a decimal separator, not the usual period. -@item --download @c option +@item --download @itemx -Q Direct Ledger to download prices using the script defined via the option @option{--getquote @var{FILE}}. -@item --explicit @c option +@item --explicit FIX THIS ENTRY @c FIXME thdox -@item --file @var{FILE} @c option +@item --file @var{FILE} @itemx -f @var{FILE} Specify the input @file{FILE} for this invocation. -@item --getquote @var{FILE} @c option +@item --getquote @var{FILE} @cindex getquote @cindex download prices Tell ledger where to find the user defined script to download prices information. -@item --input-date-format @var{DATE_FORMAT} @c option +@item --input-date-format @var{DATE_FORMAT} Specify the input date format for journal entries. For example, @smallexample @@ -5901,7 +5901,7 @@ Would convert the @file{Export.csv} file to ledger format, assuming the dates in the CSV file are like 12/23/2009 (@pxref{Date and Time Format Codes}). -@item --master-account @var{STR} @c option +@item --master-account @var{STR} Prepend all account names with the argument. @smallexample @c command:A76BB56 @@ -5929,19 +5929,19 @@ $ ledger -f drewr3.dat bal --no-total --master-account HUMBUG $ 200.00 Mortgage:Principal @end smallexample -@item --no-aliases @c option +@item --no-aliases Ledger does not expand any aliases if this option is specified. -@item --pedantic @c option +@item --pedantic Accounts, tags or commodities not previously declared will cause errors. @item --permissive FIX THIS ENTRY @c FIXME thdox -@item --price-db @var{FILE} @c option +@item --price-db @var{FILE} Specify the location of the price entry data file. -@item --price-exp @var{INT} @c option +@item --price-exp @var{INT} @itemx -Z @var{INT} @itemx --leeway @var{INT} Set the expected freshness of price quotes, in @var{INT} minutes. That @@ -5950,7 +5950,7 @@ and if @option{--download} is being used, then the Internet will be consulted again for a newer price. Otherwise, the old price is still considered to be fresh enough. -@item --strict @c option +@item --strict Ledger normally silently accepts any account or commodity in a posting, even if you have misspelled a commonly used one. The option @option{--strict} changes that behavior. While running with @@ -5959,12 +5959,12 @@ correct, and if it encounters a new account or commodity (same as a misspelled commodity or account) it will issue a warning giving you the file and line number of the problem. -@item --recursive-aliases @c option +@item --recursive-aliases Normally, ledger only expands aliases once. With this option, ledger tries to expand the result of alias expansion recursively, until no more expansions apply. -@item --time-colon @c option +@item --time-colon The @option{--time-colon} option will display the value for a seconds based commodity as real hours and minutes. @@ -5986,9 +5986,9 @@ GUIs, which would make use of the different scopes by keeping an instance of Ledger running in the background and running multiple sessions with multiple reports per session. -@ftable @code +@ftable @option -@item --abbrev-len @var{INT} @c option +@item --abbrev-len @var{INT} Set the minimum length an account can be abbreviated to if it doesn't fit inside the @code{account-width}. If @var{INT} is zero, then the account name will be truncated on the right. If @var{INT} is greater @@ -5996,54 +5996,54 @@ than @code{account-width} then the account will be truncated on the left, with no shortening of the account names in order to fit into the desired width. -@item --account @var{STR} @c option +@item --account @var{STR} Prepend @var{STR} to all accounts reported. That is, the option @samp{--account Personal} would tack @samp{Personal:} to the beginning of every account reported in a balance report or register report. -@item --account-width @var{INT} @c option +@item --account-width @var{INT} Set the width of the account column in the @command{register} report to @var{INT} characters. -@item --actual @c option +@item --actual @itemx -L Report only real transactions, ignoring all automated or virtual transactions. -@item --add-budget @c option +@item --add-budget Show only unbudgeted postings. -@item --amount @var{EXPR} @c option +@item --amount @var{EXPR} @itemx -t @var{EXPR} Apply the given value expression to the posting amount (@pxref{Value Expressions}). Using @option{--amount @var{EXPR}} you can apply an arbitrary transformation to the postings. -@item --amount-data @c option +@item --amount-data @itemx -j On a register report print only the date and amount of postings. Useful for graphing and spreadsheet applications. -@item --amount-width @var{INT} @c option +@item --amount-width @var{INT} Set the width in characters of the amount column in the @command{register} report. -@item --anon @c option +@item --anon Anonymize registry output, mostly for sending in bug reports. @item --auto-match FIX THIS ENTRY @c FIXME thdox -@item --aux-date @c option +@item --aux-date @itemx --effective Show auxiliary dates for all calculations (@pxref{Effective Dates}). -@item --average @c option +@item --average @itemx -A Print average values over the number of transactions instead of running totals. -@item --balance-format @var{FORMAT_STRING} @c option +@item --balance-format @var{FORMAT_STRING} Specify the format to use for the @command{balance} report (@pxref{Format Strings}). The default is: @@ -6058,16 +6058,16 @@ Strings}). The default is: @item --base FIX THIS ENTRY @c ASK JOHN -@item --basis @c option +@item --basis @itemx -B @itemx --cost Report the cost basis on all posting. -@item --begin @var{DATE} @c option +@item --begin @var{DATE} Specify the start @var{DATE} of all calculations. Transactions before that date will be ignored. -@item --bold-if @var{VEXPR} @c option +@item --bold-if @var{VEXPR} Print the entire line in bold if the given value expression is true (@pxref{Value Expressions}). @@ -6084,7 +6084,7 @@ Only display budgeted items. In a register report this displays transactions in the budget, in a balance report this displays accounts in the budget (@pxref{Budgeting and Forecasting}). -@item --budget-format @var{FORMAT_STRING} @c option +@item --budget-format @var{FORMAT_STRING} Specify the format to use for the @command{budget} report (@pxref{Format Strings}). The default is: @@ -6096,16 +6096,16 @@ Strings}). The default is: "--------------------\n" @end smallexample -@item --by-payee @c option +@item --by-payee @itemx -P Group the register report by payee. -@item --cleared @c option +@item --cleared @itemx -C Consider only transactions that have been cleared for display and calculation. -@item --cleared-format @var{FORMAT_STRING} @c option +@item --cleared-format @var{FORMAT_STRING} FIX THIS ENTRY @c FIXME thdox: to keep? Specify the format to use for the @command{cleared} report (@pxref{Format Strings}). The default is: @@ -6122,26 +6122,26 @@ Strings}). The default is: "---------------- ---------------- ---------\n" @end smallexample -@item --collapse @c option +@item --collapse @itemx -n By default ledger prints all accounts in an account tree. With @option{--collapse} it prints only the top level account specified. -@item --collapse-if-zero @c option +@item --collapse-if-zero Collapse the account display only if it has a zero balance. -@item --color @c option +@item --color @itemx --ansi Use color if the terminal supports it. -@item --columns @var{INT} @c option +@item --columns @var{INT} Specify the width of the @command{register} report in characters. -@item --count @c option +@item --count Direct ledger to report the number of items when appended to the @command{commodities}, @command{accounts} or @command{payees} command. -@item --csv-format @var{FORMAT_STRING} @c option +@item --csv-format @var{FORMAT_STRING} Specify the format to use for the @command{csv} report (@pxref{Format Strings}). The default is: @@ -6156,29 +6156,29 @@ Strings}). The default is: "%(quoted(join(note | xact.note)))\n" @end smallexample -@item --current @c option +@item --current Shorthand for @samp{--limit "date <= today"}. -@item --daily @c option +@item --daily @itemx -D Shorthand for @samp{--period "daily"}. -@item --date @var{EXPR} @c option +@item --date @var{EXPR} Transform the date of the transaction using @var{EXPR}. -@item --date-format @var{DATE_FORMAT} @c option +@item --date-format @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT} Specify the format ledger should use to read and print dates (@pxref{Date and Time Format Codes}). -@item --date-width @var{INT} @c option +@item --date-width @var{INT} Specify the width, in characters, of the date column in the @command{register} report. @item --datetime-format @var{FIXME} FIX THIS ENTRY @c ASK JOHN -@item --dc @c option +@item --dc Display register or balance in debit/credit format If you use @option{--dc} with either the @command{register} (reg) or @command{balance} (bal) commands, you will now get extra columns. @@ -6237,29 +6237,29 @@ And with @option{--dc} it becomes this: $145 $145 0 @end smallexample -@item --depth @var{INT} @c option +@item --depth @var{INT} Limit the depth of the account tree. In a balance report, for example, a @samp{--depth 2} statement will print balances only for accounts with two levels, i.e. @samp{Expenses:Entertainment} but not @samp{Expenses:Entertainment:Dining}. This is a display predicate, which means it only affects display, not the total calculations. -@item --deviation @c option +@item --deviation Report each posting’s deviation from the average. It is only meaningful in the register and prices reports. -@item --display @var{EXPR} @c option +@item --display @var{EXPR} Display only lines that satisfy the expression @var{EXPR}. -@item --display-amount @var{EXPR} @c option +@item --display-amount @var{EXPR} Apply a transformation to the @emph{displayed} amount. This happens after calculations occur. -@item --display-total @var{EXPR} @c option +@item --display-total @var{EXPR} Apply a transformation to the @emph{displayed} total. This happens after calculations occur. -@item --dow @c option +@item --dow @itemx --days-of-week Group transactions by the day of the week. @@ -6270,15 +6270,15 @@ $ ledger reg Expenses --dow --collapse @noindent Will print all Expenses totaled for each day of the week. -@item --empty @c option +@item --empty @itemx -E Include empty accounts in the report and in average calculations. -@item --end @var{DATE} @c option +@item --end @var{DATE} Specify the end @var{DATE} for a transaction to be considered in the report. All transactions on or after this date are ignored. -@item --equity @c option +@item --equity Related to the @command{equity} command (@pxref{The @command{equity} command}). Gives current account balances in the form of a register report. @@ -6286,7 +6286,7 @@ report. @item --exact FIX THIS ENTRY @c ASK JOHN -@item --exchange @var{COMMODITY} @c option +@item --exchange @var{COMMODITY} @itemx -X @var{COMMODITY} Display values in terms of the given @var{COMMODITY}. The latest available price is used. The syntax @@ -6300,44 +6300,44 @@ which is particularly useful for situations where many prices are available for reporting in terms of @var{COMMODITY2}, but only a few should be displayed that way. -@item --flat @c option +@item --flat Force the full names of accounts to be used in the balance report. The balance report will not use an indented tree. -@item --force-color @c option +@item --force-color Output TTY color codes even if the TTY doesn't support them. Useful for TTYs that don't advertise their capabilities correctly. -@item --force-pager @c option +@item --force-pager Force Ledger to paginate its output. -@item --forecast-while @var{VEXPR} @c option +@item --forecast-while @var{VEXPR} @itemx --forecast @var{VEXPR} Continue forecasting while @var{VEXPR} is true. -@item --forecast-years @var{INT} @c option +@item --forecast-years @var{INT} Forecast at most @var{INT} years into the future. -@item --format @var{FORMAT_STRING} @c option +@item --format @var{FORMAT_STRING} @itemx -F @var{FORMAT_STRING} Use the given format string to print output. -@item --gain @c option +@item --gain @itemx -G @itemx --change Report on gains using the latest available prices. -@item --generated @c option +@item --generated 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 @var{EXPR} @c option +@item --group-by @var{EXPR} Group transactions together in the @command{register} report. @var{EXPR} can be anything, although most common would be @code{payee} or @code{commodity}. The @code{tags()} function is also useful here. -@item --group-title-format @var{FORMAT_STRING} @c option +@item --group-title-format @var{FORMAT_STRING} Set the format for the headers that separates the report sections of a grouped report. Only has an effect with a @option{--group-by @var{EXPR}} register report. @@ -6355,19 +6355,19 @@ $ ledger reg Expenses --group-by "payee" --group-title-format "----------------- ... @end smallexample -@item --head @var{INT} @c option +@item --head @var{INT} @itemx --first @var{INT} Print the first @var{INT} entries. Opposite of @option{--tail @var{INT}}. -@item --historical @c option +@item --historical @itemx -H FIX THIS ENTRY @c FIXME thdox -@item --immediate @c option +@item --immediate FIX THIS ENTRY @c FIXME thdox -@item --inject @c option +@item --inject Use @code{Expected} amounts in calculations. In case you know what amount a transaction should be, but the actual transaction has the wrong value you can use metadata to specify the expected amount: @@ -6381,105 +6381,105 @@ wrong value you can use metadata to specify the expected amount: Then using the command @code{ledger reg --inject=Expected Income} would treat the transaction as if the ``Expected Value'' was actual. -@item --invert @c option +@item --invert Change the sign of all reported values. -@item --limit @var{EXPR} @c option +@item --limit @var{EXPR} @itemx -l @var{EXPR} Only transactions that satisfy @var{EXPR} are considered in calculations and for display. -@item --lot-dates @c option +@item --lot-dates Report the date on which each commodity in a balance report was purchased. -@item --lot-notes @c option +@item --lot-notes @itemx --lot-tags Report the tag attached to each commodity in a balance report. -@item --lot-prices @c option +@item --lot-prices Report the price at which each commodity in a balance report was purchased. -@item --lots @c option +@item --lots Report the date and price at which each commodity was purchased in a balance report. @item --lots-actual FIX THIS ENTRY -@item --market @c option +@item --market @itemx -V Use the latest market value for all commodities. -@item --meta @var{TAG} @c option +@item --meta @var{TAG} In the register report, prepend the transaction with the value of the given @var{TAG}. -@item --meta-width @var{INT} @c option +@item --meta-width @var{INT} Specify the width of the Meta column used for the @option{--meta @var{TAG}} options. -@item --monthly @c option +@item --monthly @itemx -M Synonym for @samp{--period "monthly"}. -@item --no-aliases @c option +@item --no-aliases Aliases are completely ignored. -@item --no-color @c option +@item --no-color Suppress any color TTY output. -@item --no-rounding @c option +@item --no-rounding Don't output @samp{<Rounding>} postings. Note that this will cause the running total to often not add up! Its main use is for @option{--amount-data (-j)} and @option{--total-data (-J)} reports. -@item --no-titles @c option +@item --no-titles Suppress the output of group titles. -@item --no-total @c option +@item --no-total Suppress printing the final total line in a balance report. -@item --now @var{DATE} @c option +@item --now @var{DATE} Define the current date in case you want to calculate in the past or future using @option{--current}. -@item --only @var{FIXME} @c option +@item --only @var{FIXME} This is a postings predicate that applies after certain transforms have been executed, such as periodic gathering. -@item --output @var{FILE} @c option +@item --output @var{FILE} Redirect the output of ledger to the file defined in @file{FILE}. -@item --pager @var{FILE} @c option +@item --pager @var{FILE} Specify the pager program to use. -@item --payee @var{VEXPR} @c option +@item --payee @var{VEXPR} Sets a value expression for formatting the payee. In the @command{register} report this prevents the second entry from having a date and payee for each transaction. -@item --payee-width @var{INT} @c option +@item --payee-width @var{INT} Set the number of columns dedicated to the payee in the register report to @var{INT}. -@item --pending @c option +@item --pending Use only postings that are marked pending. -@item --percent @c option +@item --percent @itemx -% Calculate the percentage value of each account in balance reports. Only works for accounts that have a single commodity. -@item --period @var{PERIOD_EXPRESSION} @c option +@item --period @var{PERIOD_EXPRESSION} Define a period expression that sets the time period during which transactions are to be accounted. For a @command{register} report only the transactions that satisfy the period expression with be displayed. For a @command{balance} report only those transactions will be accounted in the final balances. -@item --pivot @var{TAG} @c option +@item --pivot @var{TAG} Produce a balance pivot report @emph{around} the given @var{TAG}. For example, if you have multiple cars and track each fuel purchase in @samp{Expenses:Auto:Fuel} and tag each fuel purchase with a tag @@ -6500,60 +6500,60 @@ $ ledger bal Fuel --pivot "Car" --period "this year" @xref{Metadata values}. -@item --plot-amount-format @var{FORMAT_STRING} @c option +@item --plot-amount-format @var{FORMAT_STRING} Define the output format for an amount data plot. @xref{Visualizing with Gnuplot}. -@item --plot-total-format @var{FORMAT_STRING} @c option +@item --plot-total-format @var{FORMAT_STRING} Define the output format for a total data plot. @xref{Visualizing with Gnuplot}. -@item --prepend-format @var{FORMAT_STRING} @c option +@item --prepend-format @var{FORMAT_STRING} Prepend @var{STR} to every line of the output. -@item --prepend-width @var{INT} @c option +@item --prepend-width @var{INT} Reserve @var{INT} spaces at the beginning of each line of the output. -@item --price @c option +@item --price @itemx -I Use the price of the commodity purchase for performing calculations. -@item --pricedb-format @var{FORMAT_STRING} @c option +@item --pricedb-format @var{FORMAT_STRING} Set the format expected for the historical price file. @item --prices-format @var{FORMAT_STRING} Set the format for the @command{prices} report. -@item --primary-date @c option +@item --primary-date @itemx --actual-dates Show primary dates for all calculations (@pxref{Effective Dates}). -@item --quantity @c option +@item --quantity @itemx -O Report commodity totals (this is the default). -@item --quarterly @c option +@item --quarterly Synonym for @samp{--period "quarterly"}. -@item --raw @c option +@item --raw In the @command{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. This can be useful for minor cleanups, like just aligning amounts. -@item --real @c option +@item --real @itemx -R Account using only real transactions ignoring virtual and automatic transactions. -@item --register-format @var{FORMAT_STRING} @c option +@item --register-format @var{FORMAT_STRING} Define the output format for the @command{register} report. -@item --related @c option +@item --related In a @command{register} report show the related account. This is the other @emph{side} of the transaction. -@item --related-all @c option +@item --related-all Show all postings in a transaction, similar to @option{--related} but show both @emph{sides} of each transaction. @@ -6570,11 +6570,11 @@ FIX THIS ENTRY @itemx --detail FIX THIS ENTRY @c FIXME thdox -@item --seed @var{FIXME} @c option -Set the random seed to @var{FIXME} for the @code{generate} command. +@item --seed @var{INT} +Set the random seed to @var{INT} for the @code{generate} command. Used as part of development testing. -@item --sort @var{VEXPR} @c option +@item --sort @var{VEXPR} @itemx -S @var{VEXPR} Sort the @command{register} report based on the value expression given to sort. @@ -6582,11 +6582,11 @@ to sort. @c @item --sort-all @var{FIXME} @c FIX THIS ENTRY -@item --sort-xacts @var{VEXPR} @c option +@item --sort-xacts @var{VEXPR} @itemx --period-sort @var{VEXPR} Sort the postings within transactions using the given value expression. -@item --start-of-week @var{INT} @c option +@item --start-of-week @var{INT} Tell ledger to use a particular day of the week to start its ``weekly'' summary. @samp{--start-of-week=1} specifies Monday as the start of the week. @@ -6595,7 +6595,7 @@ week. @itemx -s FIX THIS ENTRY -@item --tail @var{INT} @c option +@item --tail @var{INT} @itemx --last @var{INT} Report only the last @var{INT} entries. Only useful in a @command{register} report. @@ -6603,62 +6603,62 @@ a @command{register} report. @item --time-report FIX THIS ENTRY @c FIXME thdox -@item --total @var{VEXPR} @c option +@item --total @var{VEXPR} @itemx -T @var{VEXPR} Define a value expression used to calculate the total in reports. -@item --total-data @c option +@item --total-data @itemx -J Show only dates and totals to format the output for plots. -@item --total-width @var{INT} @c option +@item --total-width @var{INT} Set the width of the total field in the register report. -@item --truncate @var{CODE} @c option +@item --truncate @var{CODE} Indicates how truncation should happen when the contents of columns exceed their width. Valid arguments are @samp{leading}, @samp{middle}, and @samp{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 @c option +@item --unbudgeted Show only unbudgeted postings. -@item --uncleared @c option +@item --uncleared @itemx -U Use only uncleared transactions in calculations and reports. -@item --unrealized @c option +@item --unrealized Show generated unrealized gain and loss accounts in the balance report. -@item --unrealized-gains @var{STR} @c option +@item --unrealized-gains @var{STR} Allow the user to specify what account name should be used for unrealized gains. Defaults to @samp{"Equity:Unrealized Gains"}. Often set in one's @file{~/.ledgerrc} file to change the default. -@item --unrealized-losses @var{STR} @c option +@item --unrealized-losses @var{STR} Allow the user to specify what account name should be used for unrealized gains. Defaults to @samp{"Equity:Unrealized Losses"}. Often set in one's @file{~/.ledgerrc} file to change the default. -@item --unround @c option +@item --unround Perform all calculations without rounding and display results to full precision. -@item --values @c option +@item --values Shows the values used by each tag when used in combination with the @command{tags} command. -@item --weekly @c option +@item --weekly @itemx -W Synonym for @samp{--period "weekly"}. -@item --wide @c option +@item --wide Let the register report use 132 columns instead of 80 (the default). Identical to @samp{--columns "132"}. -@item --yearly @c option +@item --yearly @itemx -Y Synonym for @samp{--period "yearly"}. @@ -6671,31 +6671,31 @@ These are the most basic command options. Most likely, the user will want to set them using environment variables (see @ref{Environment variables}), instead of using actual command-line options: -@ftable @code +@ftable @option -@item --help @c option +@item --help @itemx -h Print a summary of all the options, and what they are used for. This can be a handy way to remember which options do what. -@item --version @c option +@item --version Print the current version of ledger and exits. This is useful for sending bug reports, to let the author know which version of ledger you are using. -@item --file @var{FILE} @c option +@item --file @var{FILE} @itemx -f @var{FILE} Read @file{FILE} as a ledger file. @var{FILE} can be @samp{-} which is a synonym for @samp{/dev/stdin}. This command may be used multiple times. Typically, the environment variable @env{LEDGER_FILE} is set, rather than using this command-line option. -@item --output @var{FILE} @c option +@item --output @var{FILE} @itemx -o @var{FILE} Redirect output from any command to @file{FILE}. By default, all output goes to standard output. -@item --init-file @var{FILE} @c option +@item --init-file @var{FILE} @itemx -i @var{FILE} Causes @file{FILE} to be read by ledger before any other ledger file. This file may not contain any postings, but it may contain option @@ -6712,7 +6712,7 @@ example init file: Option settings on the command-line or in the environment always take precedence over settings in the init file. -@item --account @var{STR} @c option +@item --account @var{STR} @itemx -a @var{STR} Specify the default account which QIF file postings are assumed to relate to. @@ -6725,13 +6725,13 @@ relate to. These options change which postings affect the outcome of a report, in ways other than just using regular expressions: -@ftable @code +@ftable @option -@item --current @c option +@item --current @itemx -c Display only transactions occurring on or before the current date. -@item --begin @var{DATE} @c option +@item --begin @var{DATE} @itemx -b @var{DATE} Constrain the report to transactions on or after @var{DATE}. Only transactions after that date will be calculated, which means that the @@ -6739,12 +6739,12 @@ running total in the balance report will always start at zero with the first matching transaction. (Note: This is different from using @option{--display @var{EXPR}} to constrain what is displayed). -@item --end @var{DATE} @c option +@item --end @var{DATE} @itemx -e @var{DATE} Constrain the report so that transactions on or after @var{DATE} are not considered. -@item --period @var{PERIOD_EXPRESSION} @c option +@item --period @var{PERIOD_EXPRESSION} @itemx -p @var{PERIOD_EXPRESSION} Set the reporting period to @var{STR}. This will subtotal all matching transactions within each period separately, making it easy to see @@ -6753,7 +6753,7 @@ even specify the beginning and end of the report range, using simple terms like @samp{last June} or @samp{next month}. For more details on period expressions, see @ref{Period Expressions}. -@item --period-sort @var{VEXPR} @c option +@item --period-sort @var{VEXPR} Sort the postings within each reporting period using the value expression @var{EXPR}. This is most often useful when reporting monthly expenses, in order to view the highest expense categories at @@ -6764,28 +6764,28 @@ the top of each month: $ ledger -M --period-sort total reg ^Expenses @end smallexample -@item --cleared @c option +@item --cleared @itemx -C Display only postings whose transaction has been marked ``cleared'' (by placing an asterisk to the right of the date). -@item --uncleared @c option +@item --uncleared @itemx -U Display only postings whose transaction has not been marked ``cleared'' (i.e., if there is no asterisk to the right of the date). -@item --real @c option +@item --real @itemx -R Display only real postings, not virtual. (A virtual posting is indicated by surrounding the account name with parentheses or brackets; see @ref{Virtual postings} for more information). -@item --actual @c option +@item --actual @itemx -L Display only actual postings, and not those created by automated transactions. -@item --related @c option +@item --related @itemx -r Display postings that are related to whichever postings would otherwise have matched the filtering criteria. In the register @@ -6815,25 +6815,25 @@ posting that matched: Assets:Checking $-85.00 $-65.00 @end smallexample -@item --budget @c option +@item --budget Useful for displaying how close your postings meet your budget. @option{--add-budget} also shows unbudgeted postings, while @option{--unbudgeted} shows only those. @option{--forecast @var{VEXPR}} is a related option that projects your budget into the future, showing how it will affect future balances. @xref{Budgeting and Forecasting}. -@item --limit @var{EXPR} @c option +@item --limit @var{EXPR} @itemx -l @var{EXPR} Limit which postings take part in the calculations of a report. -@item --amount @var{EXPR} @c option +@item --amount @var{EXPR} @itemx -t @var{EXPR} Change the value expression used to calculate the ``value'' column in the @command{register} report, the amount used to calculate account totals in the @command{balance} report, and the values printed in the @command{equity} report. @xref{Value Expressions}. -@item --total @var{VEXPR} @c option +@item --total @var{VEXPR} @itemx -T @var{VEXPR} Set the value expression used for the ``totals'' column in the @command{register} and @command{balance} reports. @@ -6890,50 +6890,50 @@ Set the value expression used for the ``totals'' column in the These options affect only the output, but not which postings are used to create it: -@ftable @code +@ftable @option -@item --collapse @c option +@item --collapse @itemx -n Cause transactions in a @command{register} report with multiple postings to be collapsed into a single, subtotaled transaction. -@item --subtotal @c option +@item --subtotal @itemx -s Cause all transactions in a @command{register} report to be collapsed into a single, subtotaled transaction. -@item --by-payee @c option +@item --by-payee @itemx -P Report subtotals by payee. -@item --empty @c option +@item --empty @itemx -E Include even empty accounts in the @command{balance} report. -@item --weekly @c option +@item --weekly @itemx -W Report posting totals by the week. The week begins on whichever day of the week begins the month containing that posting. To set a specific begin date, use a period string, such as @samp{weekly from DATE}. -@item --monthly @c option +@item --monthly @itemx -M Report posting totals by month. -@item --yearly @c option +@item --yearly @itemx -Y Report posting totals by year. For more complex periods, use @option{--period}. @c TODO end this sentence -@item --period @var{PERIOD_EXPRESSION} @c option +@item --period @var{PERIOD_EXPRESSION} Option described above. -@item --dow @c option +@item --dow Report posting totals for each day of the week. This is an easy way to see if weekend spending is more than on weekdays. -@item --sort @var{VEXPR} @c option +@item --sort @var{VEXPR} @itemx -S @var{VEXPR} Sort a report by comparing the values determined using the value expression @var{VEXPR}. For example, using @samp{-S "-abs(total)"} in @@ -6941,16 +6941,16 @@ the @command{balance} report will sort account balances from greatest to least, using the absolute value of the total. For more on how to use value expressions, see @ref{Value Expressions}. -@item --pivot @var{TAG} @c option +@item --pivot @var{TAG} Produce a pivot table around the @var{TAG} provided. This requires meta data using valued tags. -@item --wide @c option +@item --wide @itemx -w Cause the default @command{register} report to assume 132 columns instead of 80. -@item --head @var{INT} @c option +@item --head @var{INT} Cause only the first @var{INT} transactions to be printed. This is different from using the command-line utility @file{head}, which would limit to the first @var{INT} postings. @option{--tail @var{INT}} outputs @@ -6959,21 +6959,21 @@ simultaneously. If a negative amount is given, it will invert the meaning of the flag (instead of the first five transactions being printed, for example, it would print all but the first five). -@item --pager @var{FILE} @c option +@item --pager @var{FILE} Tell Ledger to pass its output to the given pager program; very useful when the output is especially long. This behavior can be made the default by setting the @env{LEDGER_PAGER} environment variable. -@item --average @c option +@item --average @itemx -A Report the average posting value. -@item --deviation @c option +@item --deviation @itemx -D Report each posting's deviation from the average. It is only meaningful in the @command{register} and @command{prices} reports. -@item --percent @c option +@item --percent @itemx -% Show account subtotals in the @command{balance} report as percentages of the parent account. @@ -6982,19 +6982,19 @@ the parent account. @c @command{xml} report. @item --amount-data -@itemx -j @c option +@itemx -j Change the @command{register} report so that it prints nothing but the date and the value column, and the latter without commodities. This is only meaningful if the report uses a single commodity. This data can then be fed to other programs, which could plot the date, analyze it, etc. -@item --total-data @c option +@item --total-data @itemx -J Change the @command{register} report so that it prints nothing but the date and total columns, without commodities. -@item --display @var{EXPR} @c option +@item --display @var{EXPR} @itemx -d @var{EXPR} Limit which postings or accounts are actually displayed in a report. They might still be calculated, and be part of the running total of a @@ -7021,7 +7021,7 @@ amount for the reporting range (using @option{--period @var{PERIOD_EXPRESSION} (-p)}), or simply a display restricted to the reporting range (using @option{--display @var{EXPR} (-d)}). -@item --date-format @var{DATE_FORMAT} @c option +@item --date-format @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT} Change the basic date format used by reports. The default uses a date like @samp{2004/08/01}, which represents the default date format of @@ -7030,13 +7030,13 @@ easiest way is to put @option{--date-format @var{DATE_FORMAT}} in the Ledger initialization file @file{~/.ledgerrc} (or the file referred to by @env{LEDGER_INIT}). -@item --format @var{FORMAT_STRING} @c option +@item --format @var{FORMAT_STRING} @itemx -F @var{FORMAT_STRING} Set the reporting format for whatever report ledger is about to make. @xref{Format Strings}. There are also specific format commands for each report type: -@item --balance-format @var{FORMAT_STRING} @c option +@item --balance-format @var{FORMAT_STRING} Define the output format for the @command{balance} report. The default (defined in @file{report.h} is: @@ -7054,7 +7054,7 @@ Define the output format for the @command{balance} report. The default --------------------\n" @end smallexample -@item --cleared-format @var{FORMAT_STRING} @c option +@item --cleared-format @var{FORMAT_STRING} Define the format for the cleared report. The default is: @smallexample @@ -7069,7 +7069,7 @@ Define the format for the cleared report. The default is: ---------------- ---------------- ---------\n" @end smallexample -@item --register-format @var{FORMAT_STRING} @c option +@item --register-format @var{FORMAT_STRING} Define the output format for the @command{register} report. The default (defined in @file{report.h} is: @@ -7121,7 +7121,7 @@ Set the format for @command{csv} reports. The default is: %(quoted(join(note | xact.note)))\n" @end smallexample -@item --plot-amount-format @var{FORMAT_STRING} @c option +@item --plot-amount-format @var{FORMAT_STRING} Set the format for amount plots, using the @option{--amount-data (-j)} option. The default is: @@ -7129,7 +7129,7 @@ option. The default is: "%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_amount)))\n" @end smallexample -@item --plot-total-format @var{FORMAT_STRING} @c option +@item --plot-total-format @var{FORMAT_STRING} Set the format for total plots, using the @option{--total-data (-J)} option. The default is: @@ -7137,14 +7137,14 @@ option. The default is: "%(format_date(date, \"%Y-%m-%d\")) %(quantity(scrub(display_total)))\n" @end smallexample -@item --pricedb-format @var{FORMAT_STRING} @c option +@item --pricedb-format @var{FORMAT_STRING} Set the format expected for the historical price file. The default is: @smallexample "P %(datetime) %(display_account) %(scrub(display_amount))\n" @end smallexample -@item --prices-format @var{FORMAT_STRING} @c option +@item --prices-format @var{FORMAT_STRING} Set the format for the @command{prices} report. The default is: @smallexample @@ -7159,9 +7159,9 @@ Set the format for the @command{prices} report. The default is: These options affect how commodity values are displayed: -@ftable @code +@ftable @option -@item --price-db @var{FILE} @c option +@item --price-db @var{FILE} Set the file that is used for recording downloaded commodity prices. It is always read on startup, to determine historical prices. Other settings can be placed in this file manually, to prevent downloading @@ -7182,7 +7182,7 @@ download script maintain this file. The format of the file can be changed by telling ledger to use the @option{--pricedb-format @var{FORMAT_STRING}} you define. -@item --price-exp @var{INT} @c option +@item --price-exp @var{INT} @itemx -Z @var{INT} Set the expected freshness of price quotes, in @var{INT} minutes. That is, if the last known quote for any commodity is older than this value, @@ -7190,7 +7190,7 @@ and if @option{--download} is being used, then the Internet will be consulted again for a newer price. Otherwise, the old price is still considered to be fresh enough. -@item --download @c option +@item --download @itemx -Q Cause quotes to be automagically downloaded, as needed, by running a script named @file{getquote} and expecting that script to return @@ -7209,21 +7209,21 @@ expressions, and the @option{--amount @var{EXPR} (-t)} and several ``default'' reports, which will satisfy most users' basic reporting needs: -@ftable @code +@ftable @option -@item --quantity @c option +@item --quantity @itemx -O Report commodity totals (this is the default). -@item --basis @c option +@item --basis @itemx -B Report the cost basis for all postings. -@item --market @c option +@item --market @itemx -V Use the last known value for commodities to calculate final values. -@item --gain @c option +@item --gain @itemx -G Report the net gain/loss for all commodities in the report that have a price history. @@ -9246,7 +9246,7 @@ are found. These options are primarily for Ledger developers, but may be of some use to a user trying something new. -@ftable @code +@ftable @option @item --args-only Ignore init files and environment variables for the ledger run. diff --git a/test/CheckTexinfo.py b/test/CheckTexinfo.py index c289da68..eedd975d 100755 --- a/test/CheckTexinfo.py +++ b/test/CheckTexinfo.py @@ -20,6 +20,40 @@ class CheckTexinfo (CheckOptions): self.source_file = join(self.source, 'doc', 'ledger3.texi') self.source_type = 'texinfo' + def find_options(self, filename): + options = set() + state_normal = 0 + state_option_table = 1 + state = state_normal + option = None + opt_doc = str() + item_regex = re.compile('^@item --([-A-Za-z]+)') + itemx_regex = re.compile('^@itemx') + fix_regex = re.compile('FIX') + for line in open(filename): + line = line.strip() + if state == state_normal: + if line == '@ftable @option': + state = state_option_table + elif state == state_option_table: + if line == '@end ftable': + if option and len(opt_doc) and not fix_regex.search(opt_doc): + options.add(option) + state = state_normal + option = None + continue + match = item_regex.match(line) + if match: + if option and len(opt_doc) and not fix_regex.search(opt_doc): + options.add(option) + option = match.group(1) + opt_doc = str() + elif itemx_regex.match(line): + continue + else: + opt_doc += line + return options + if __name__ == "__main__": def getargs(): parser = argparse.ArgumentParser(prog='CheckTexinfo', |