From 6b5ff2aebfc55cb9cd2f8e621663d3b749179a66 Mon Sep 17 00:00:00 2001 From: thdox Date: Thu, 22 Jan 2015 00:57:20 +0100 Subject: Add documentation for --no-pager option. Minor updates to --pager documentation. [ci skip] --- doc/ledger.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index fb434880..9fecc19b 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -622,8 +622,8 @@ Shorthand for Aliases are completely ignored. .It Fl \-no-color Suppress any color TTY output. -.\".It Fl \-no-pager -Suppress any color TTY output. +.It Fl \-no-pager +Disables the pager on TTY output. .It Fl \-no-rounding Don't output .Nm -- cgit v1.2.3 From 97a6761ca7da2957e870d3698dcfef9272e41ed7 Mon Sep 17 00:00:00 2001 From: thdox Date: Thu, 22 Jan 2015 01:35:14 +0100 Subject: Add documentation for option --permissive. --- doc/ledger.1 | 3 ++- doc/ledger3.texi | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index fb434880..9aac44e5 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -679,7 +679,8 @@ For a balance report only those transactions will be accounted in the final balances. .It Fl \-period-sort Sort the posting within transactions using the given value expression. -.\".It Fl \-permissive +.It Fl \-permissive +Quiet balance assertions. .It Fl \-pivot Ar STR Produce a balance pivot report .Nm around diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 9597083c..a05f15db 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -5936,7 +5936,7 @@ Ledger does not expand any aliases if this option is specified. Accounts, tags or commodities not previously declared will cause errors. @item --permissive -FIX THIS ENTRY @c FIXME thdox +Quiet balance assertions. @item --price-db @var{FILE} Specify the location of the price entry data file. -- cgit v1.2.3 From 185656e191d5e0b3424f528b33956d2b4f917234 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Mon, 19 Jan 2015 17:27:43 +0100 Subject: [doc] Add tests to value and format expressions and change formatting for value expressions using @defun, @defvar. --- doc/ledger.1 | 20 +- doc/ledger3.texi | 576 ++++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 506 insertions(+), 90 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 03cd9dac..8aa0f474 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -956,6 +956,7 @@ Character position where entry for posting begins. Return the transaction code, the string between the parenthesis after the date. .It Nm comment .It Nm commodity +Return the commodity of the posting amount. .It Nm cost .It Nm count .It Nm date @@ -970,7 +971,14 @@ Line number where entry for posting ends. Character position where entry for posting ends. .It Nm filename The name of the ledger data file from whence the posting came. -.It Nm format_date +.It Fn format_date date format +Return the +.Ar date +as a string using +.Ar format . +See +.Xr strftime 3 +for format string details. .It Nm get_at .It Nm has_meta .It Nm has_tag @@ -983,11 +991,19 @@ The name of the ledger data file from whence the posting came. .It Nm options .It Nm partial_account .It Nm payee +.It Fn percent value_a value_b +Return the percentage of +.Ar value_a +in relation to +.Ar value_b . .It Nm pending .It Nm post .It Nm print .It Nm quantity -.It Nm quoted +.It Fn quoted expression +Surround +.Ar expression +with double-quotes. .It Nm real .It Nm rounded .It Nm scrub diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 55d65c82..b98664f9 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -2,6 +2,7 @@ @setfilename ledger3.info @include version.texi +@set FIXME:UNDOCUMENTED @sc{undocumented}! Please help by contributing documentation for this feature. @settitle Ledger: Command-Line Accounting @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with @@ -5323,13 +5324,13 @@ with Ledger 2.X. @findex stats @findex stat -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @node @command{select}, , @command{stats}, Reports about your Journals @subsection @command{select} @findex select -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @node Command-Line Syntax, Budgeting and Forecasting, Reporting Commands, Top @chapter Command-Line Syntax @@ -5465,6 +5466,9 @@ Redirect output to @file{FILE}. @itemx -i @var{FILE} Specify an options file. +@item --import @var{FILE} +@value{FIXME:UNDOCUMENTED} + @item --account @var{STR} @itemx -a @var{STR} Specify default account @var{STR} for QIF file postings. @@ -5782,7 +5786,7 @@ or testing small journal files not associated with your main financial database. @item --debug @var{CODE} -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @item --help @itemx -h @@ -5843,10 +5847,10 @@ slowdown. When combined with @option{--debug @var{CODE}} ledger will produce memory trace information. @item --verify-memory -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @item --version -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @end ftable @@ -5863,13 +5867,26 @@ sessions with multiple reports per session. @ftable @option @item --cache @var{FIXME} -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @item --check-payees -FIX THIS ENTRY @c FIXME thdox +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 --day-break -FIX THIS ENTRY @c FIXME thdox +Break up @command{register} report of @ref{timelog} entries that span multiple +days by day. +@c see test/baseline/opt-day-break.dat +@c @smallexample @c input: +@c i 2015/ +@c @end smallexample +@c @smallexample @c command: +@c $ ledger reg --day-break +@c @end smallexample +@c @smallexample @c output: +@c @end smallexample +@value{FIXME:UNDOCUMENTED} @item --decimal-comma Direct Ledger to parse journals using the European standard comma as @@ -5881,7 +5898,8 @@ Direct Ledger to download prices using the script defined via the option @option{--getquote @var{FILE}}. @item --explicit -FIX THIS ENTRY @c FIXME thdox +@c see test/baseline/opt-explicit.test +@value{FIXME:UNDOCUMENTED} @item --file @var{FILE} @itemx -f @var{FILE} @@ -5975,7 +5993,7 @@ For example 8100 seconds by default will be displayed as 2.25 whereas with the @option{--time-colon} option they will be displayed as 2:15. @item --value-expr @var{FIXME} -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @end ftable @@ -6035,7 +6053,9 @@ Set the width in characters of the amount column in the Anonymize registry output, mostly for sending in bug reports. @item --auto-match -FIX THIS ENTRY @c FIXME thdox +@c Automatically match accounts from ledger journal when using convert command +@c see test/baseline/opt-auto-match.dat +@value{FIXME:UNDOCUMENTED} @item --aux-date @itemx --effective @@ -6059,7 +6079,10 @@ Strings}). The default is: @end smallexample @item --base -FIX THIS ENTRY @c ASK JOHN +@c Report commodity in the base commodity s instead of h +@c Does this apply to other commodities too? +@c see test/baseline/opt-base.test/ +@value{FIXME:UNDOCUMENTED} @item --basis @itemx -B @@ -6109,7 +6132,7 @@ Consider only transactions that have been cleared for display and calculation. @item --cleared-format @var{FORMAT_STRING} -FIX THIS ENTRY @c FIXME thdox: to keep? +@c FIXME thdox: to keep? Specify the format to use for the @command{cleared} report (@pxref{Format Strings}). The default is: @@ -6178,8 +6201,11 @@ Specify the format ledger should use to read and print dates 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 --datetime-format @var{DATETIME_FORMAT} +@c Specify the format ledger should use to print datetimes in +@c @command{balance} @option{--timelog-report} reports. +@c see test/baseline/opt-datetime-format.test +@value{FIXME:UNDOCUMENTED} @item --dc Display register or balance in debit/credit format If you use @@ -6287,7 +6313,7 @@ command}). Gives current account balances in the form of a register report. @item --exact -FIX THIS ENTRY @c ASK JOHN +@value{FIXME:UNDOCUMENTED} @item --exchange @var{COMMODITY} @itemx -X @var{COMMODITY} @@ -6365,10 +6391,10 @@ Print the first @var{INT} entries. Opposite of @option{--tail @item --historical @itemx -H -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @item --immediate -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @item --inject Use @code{Expected} amounts in calculations. In case you know @@ -6409,7 +6435,8 @@ Report the date and price at which each commodity was purchased in a balance report. @item --lots-actual -FIX THIS ENTRY +@c see test/baseline/opt-lots-actual.test +@value{FIXME:UNDOCUMENTED} @item --market @itemx -V @@ -6564,17 +6591,22 @@ Show all postings in a transaction, similar to @option{--related} but show both @emph{sides} of each transaction. @item --revalued -FIX THIS ENTRY +@c see test/baeline/opt-revalued.test +@value{FIXME:UNDOCUMENTED} @item --revalued-only -FIX THIS ENTRY +@c see test/baeline/opt-revalued-only.test +@value{FIXME:UNDOCUMENTED} @item --revalued-total @var{FIXME} -FIX THIS ENTRY +@value{FIXME:UNDOCUMENTED} @item --rich-data @itemx --detail -FIX THIS ENTRY @c FIXME thdox +@c When generating ledger transaction from csv using the convert command +@c add CSV, Imported, and UUID meta-data. +@c see test/baeline/opt-rich-data.test +@value{FIXME:UNDOCUMENTED} @item --seed @var{INT} Set the random seed to @var{INT} for the @code{generate} command. @@ -6585,8 +6617,8 @@ Used as part of development testing. Sort the @command{register} report based on the value expression given to sort. -@c @item --sort-all @var{FIXME} -@c FIX THIS ENTRY +@item --sort-all @var{FIXME} +@value{FIXME:UNDOCUMENTED} @item --sort-xacts @var{VEXPR} @itemx --period-sort @var{VEXPR} @@ -6599,7 +6631,7 @@ week. @item --subtotal @itemx -s -FIX THIS ENTRY +@value{FIXME:UNDOCUMENTED} @item --tail @var{INT} @itemx --last @var{INT} @@ -6607,7 +6639,9 @@ Report only the last @var{INT} entries. Only useful in a @command{register} report. @item --time-report -FIX THIS ENTRY @c FIXME thdox +@c Display begin and end time for each timelog entry in balance reports +@c see test/baseline/opt-time-report.test +@value{FIXME:UNDOCUMENTED} @item --total @var{VEXPR} @itemx -T @var{VEXPR} @@ -7614,6 +7648,7 @@ $ ledger --forecast "d<[2010]" bal ^assets ^liabilities @chapter Time Keeping @findex --day-break +@anchor{timelog} Ledger directly supports ``timelog'' entries, which have this form: @smallexample @c input:validate @@ -7945,8 +7980,6 @@ will match both all the three examples below: Expenses:Phone $-50.00 @end smallexample - - @item (EXPR) A sub-expression is nested in parenthesis. This can be useful passing more complicated arguments to functions, or for overriding the natural @@ -7974,61 +8007,337 @@ expect (@pxref{Pre-Commands}). @node Miscellaneous, , Complex expressions, Complex expressions @subsection Miscellaneous -@table @code -@item abs--> U -@item amount_expr -@item ansify_if -@item ceiling -Return the next integer toward +infinity -@item code -Return the transaction code, the string between the parenthesis after -the date. -@item commodity -@item date -@item display_amount --> t -@item display_total --> T -@item floor -Return the next integer toward -infinity -@item format -@item format_date -@item format_datetime -@item get_at -@item is_seq -@item join -@item justify -@item market --> P -@item nail_down -@item now --> d m -@item options -@item percent -@item print -@item quantity -@item quoted -@item round -@item rounded -@item roundto -Return value rounded to n digits. Does not affect formatting. -@item scrub -@item should_bold -@item strip --> S -@item to_amount -@item to_balance -@item to_boolean -@item to_date -@item to_datetime -@item to_int -@item to_mask -@item to_sequence -@item to_spring -@item today -@item top_amount -@item total_expr -@item trim -@item truncated -@item unround -@item unrounded -@item value_date -@end table +The following Ledger journal data (saved as @file{expr.dat}) is used to explain the behaviour of the +functions and variables below: +@anchor{expr.dat} +@smallexample @c input:3406FC1 +2015/01/16 * (C0D3) Payee + Assets:Cash ¤ -123,45 + ; Payee: PiggyBank + Expenses:Office Supplies +@end smallexample + +@defun abs value +@defunx U value +Return the absolute value of the given @var{value}, e.g. @var{amount}. +@end defun +@smallexample @c command:3406FC1 +$ ledger -f expr.dat --format "%(account) %(abs(amount))\n" reg assets +@end smallexample +@smallexample @c output:3406FC1 +Assets:Cash ¤ 123,45 +@end smallexample + +@defun amount_expr +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun ansify_if value color bool +Render the given @var{expression} as a string, applying the proper ANSI escape +codes to display it in the given @var{color} if @var{bool} is true. It +typically checks the value of the option @option{--color}. Since ANSI escape +codes include non-printable character sequences, such as escape @kbd{^[} +the following example may not appear as the final result on the commandline. +@end defun +@smallexample @c command:4D836EE,with_input:3406FC1 +$ ledger -f expr.dat --format "%(ansify_if(account, blue, options.color))\n" reg +@end smallexample +@smallexample @c output:4D836EE +Assets:Cash +Expenses:Office Supplies +@end smallexample + +@defun ceiling value +Return the next integer of @var{value} toward @math{+}infinity. +@end defun +@smallexample @c command:FF9C18C,with_input:3406FC1 +$ ledger -f expr.dat --format "%(account) %(ceiling(amount))\n" reg +@end smallexample +@smallexample @c output:FF9C18C +Assets:Cash ¤ -123,00 +Expenses:Office Supplies ¤ 124,00 +@end smallexample + +@defvar code +Return the transaction code, the string between the parenthesis after the date. +@smallexample @c command:46FCFD3,with_input:3406FC1 +$ ledger -f expr.dat --format "%(account) %(code)\n" reg assets +@end smallexample +@smallexample @c output:46FCFD3 +Assets:Cash C0D3 +@end smallexample +@end defvar + +@defvar commodity +Return the commodity of the posting amount. +@end defvar +@smallexample @c command:2CD27D7,with_input:3406FC1 +$ ledger -f expr.dat --format "%(account) %(commodity)\n" reg +@end smallexample +@smallexample @c output:2CD27D7 +Assets:Cash ¤ +Expenses:Office Supplies ¤ +@end smallexample + +@defvar date +Return the date of the posting. +@end defvar +@smallexample @c command:67EBA45,with_input:3406FC1 +$ ledger -f expr.dat --format "%(date) %(account)\n" reg assets +@end smallexample +@smallexample @c output:67EBA45 +2015/01/16 Assets:Cash +@end smallexample + +@defvar display_amount +@defvarx t +@value{FIXME:UNDOCUMENTED} +@end defvar + +@c FIXME +@defvar display_total +@defvarx T +@value{FIXME:UNDOCUMENTED} +@end defvar + +@defun floor value +Return the next integer of @var{value} toward @math{-}infinity. +@end defun +@smallexample @c command:4FDC7C5,with_input:3406FC1 +$ ledger -f expr.dat --format "%(account) %(floor(amount))\n" reg +@end smallexample +@smallexample @c output:4FDC7C5 +Assets:Cash ¤ -124,00 +Expenses:Office Supplies ¤ 123,00 +@end smallexample + +@defun format +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun format_date date format +Return the @var{date} as a string using @var{format}. See strftime (3) +for format string details. +@end defun +@smallexample @c command:9605B13,with_input:3406FC1 +$ ledger -f expr.dat --format "%(format_date(date, '%A, %B %d. %Y'))\n" reg assets +@end smallexample +@smallexample @c output:9605B13 +Friday, January 16. 2015 +@end smallexample + +@defun format_datetime +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun get_at +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun is_seq +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun join +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun justify value first_width latter_width right_justify colorize +Right or left justify the string representing @var{value}. The width +of the field in the first line is given by @var{first_width}. For +subsequent lines the width is given by @var{latter_width}. If +@var{latter_width=-1}, then @var{first_width} is use for all lines. +If @var{right_justify=true} then the field is right justify within +the width of the field. If it is @var{false}, then the field is left +justified and padded to the full width of the field. If +@var{colorize} is true, then ledger will honor color settings. +@end defun +@smallexample @c command:082FB27,with_input:3406FC1 +$ ledger -f expr.dat --format "»%(justify(account, 30, 30, true))«\n" reg +@end smallexample +@smallexample @c output:082FB27 +» Assets:Cash« +» Expenses:Office Supplies« +@end smallexample + +@defun market +@defunx P +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun nail_down +@value{FIXME:UNDOCUMENTED} +@end defun + +@defvar now +@defvarx d +@defvarx m +@value{FIXME:UNDOCUMENTED} +@end defvar + +@defvar options +A variable that allows access to the values of the given command-line options +using the long option names, e.g. to see whether @option{--daily} or @option{-D} +was given use @code{option.daily}. +@smallexample @c command:C1FC7A7,with_input:3406FC1 +$ ledger -f expr.dat -X $ -D --format "%(options.daily) %(options.exchange)\n" reg assets +@end smallexample +@smallexample @c output:C1FC7A7 +true $ +@end smallexample +@end defvar + +@defun percent value_a value_b +Return the percentage of @var{value_a} in relation to @var{value_b} (used as 100%) +@end defun +@smallexample @c command:04959BF,with_input:3406FC1 +$ ledger -f expr.dat --format "%(percent(amount, 200))\n" reg +@end smallexample +@smallexample @c output:04959BF +-61.73% +61.73% +@end smallexample + +@defun print +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun quantity +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun quoted expression +Surround @var{expression} with double-quotes. +@end defun +@smallexample @c command:EAD8AA7,with_input:3406FC1 +$ ledger -f expr.dat --format "%(quoted(account)) %(quoted(amount))\n" reg +@end smallexample +@smallexample @c output:EAD8AA7 +"Assets:Cash" "¤ -123,45" +"Expenses:Office Supplies" "¤ 123,45" +@end smallexample + +@defun round +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun rounded +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun roundto value n +Return @var{value} rounded to @var{n} digits. Does not affect formatting. +@end defun +@smallexample @c command:B4DFB9F,with_input:3406FC1 +$ ledger -f expr.dat --format "%(account) %(roundto(amount, 1))\n" reg +@end smallexample +@smallexample @c output:B4DFB9F +Assets:Cash ¤ -123,40 +Expenses:Office Supplies ¤ 123,50 +@end smallexample + +@defun scrub +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun should_bold +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun strip +@defunx S +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun to_amount +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun to_balance +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun to_boolean +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun to_date +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun to_datetime +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun to_int value +@defunx int value +Return the integer value for @var{value}. +@end defun +@smallexample @c command:0B0CBA1,with_input:3406FC1 +$ ledger -f expr.dat --format "%(1 + to_int('1'))\n%(2,5 + int(2,5))\n" reg assets +@end smallexample +@smallexample @c output:0B0CBA1 +2 +4.5 +@end smallexample + +@defun to_mask +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun to_sequence +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun to_string value +@defunx str value +Convert @var{value} to a character string. +@end defun + +@defvar today +Return today's date. +@end defvar +@smallexample @c command:F2FDF4B,with_input:3406FC1 +$ ledger -f expr.dat --now 2015/01/01 --format "%(today)\n" reg assets +@end smallexample +@smallexample @c output:F2FDF4B +2015/01/01 +@end smallexample + +@defun top_amount +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun total_expr +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun trim value +Trim leading and trailing whitespace from @var{value}. +@end defun +@smallexample @c command:377BBAB,with_input:3406FC1 +$ ledger -f expr.dat --format "»%(trim(' Trimmed '))«\n" reg assets +@end smallexample +@smallexample @c output:377BBAB +»Trimmed« +@end smallexample + +@defun truncated +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun unround +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun unrounded +@value{FIXME:UNDOCUMENTED} +@end defun + +@defun value_date +@value{FIXME:UNDOCUMENTED} +@end defun + @node Format Strings, Extending with Python, Value Expressions, Top @chapter Format Strings @@ -8115,12 +8424,19 @@ or an expression enclosed in parentheses or brackets. @findex --amount @var{EXPR} @findex --total @var{VEXPR} +For demonstration purposes the journal data from @ref{expr.dat} is used. The allowable expressions are: @table @code @item % Inserts a percent sign. +@smallexample @c command:6F90EFC,with_input:3406FC1 +$ ledger -f expr.dat --format "%%\n" reg assets +@end smallexample +@smallexample @c output:6F90EFC +% +@end smallexample @item t Inserts the results of the value expression specified by @@ -8138,6 +8454,12 @@ parentheses. To insert five times the total value of an account, for example, one could say @samp{%12(5*O)}. Note: It's important to put the five first in that expression, so that the commodity doesn't get stripped from the total. +@smallexample @c command:494256E,with_input:3406FC1 +$ ledger -f expr.dat --format "%12(5*O)\n" reg assets +@end smallexample +@smallexample @c output:494256E + ¤ -617,25 +@end smallexample @item [DATEFMT] Inserts the result of formatting a posting's date with a date @@ -8147,20 +8469,52 @@ example: @samp{%[%Y/%m/%d %H:%M:%S]}. @item S Insert the path name of the file from which the transaction's data was read. Only sensible in a @command{register} report. +@c Note: Unable to test this properly since the output depends on +@c where the ledger source tree resides in the filesystem. +@smallexample +$ ledger -f ~/journal.dat --format "%S\n" reg assets +@end smallexample +@smallexample +/home/jwiegley/journal.dat +@end smallexample @item B Inserts the beginning character position of that transaction within the file. +@smallexample @c command:2B669C9,with_input:3406FC1 +$ ledger -f expr.dat --format "%B\n" reg assets +@end smallexample +@smallexample @c output:2B669C9 +26 +@end smallexample @item b Inserts the beginning line of that transaction within the file. +@smallexample @c command:F6E356F,with_input:3406FC1 +$ ledger -f expr.dat --format "%b\n" reg assets +@end smallexample +@smallexample @c output:F6E356F +2 +@end smallexample @item E Inserts the ending character position of that transaction within the file. +@smallexample @c command:0E55246,with_input:3406FC1 +$ ledger -f expr.dat --format "%E\n" reg assets +@end smallexample +@smallexample @c output:0E55246 +90 +@end smallexample @item e Inserts the ending line of that transaction within the file. +@smallexample @c command:A26F4C0,with_input:3406FC1 +$ ledger -f expr.dat --format "%e\n" reg assets +@end smallexample +@smallexample @c output:A26F4C0 +3 +@end smallexample @item D Returns the date according to the default format. @@ -8179,9 +8533,23 @@ character if all of the member postings have the same state. @item C Inserts the transaction code. This is the value specified between parentheses on the first line of the transaction. +@smallexample @c command:C1CAAF3,with_input:3406FC1 +$ ledger -f expr.dat --format "%C\n" reg assets +@end smallexample +@c Note: The output needs a space character at the end +@c for this test to pass +@smallexample @c output:C1CAAF3 +(C0D3) +@end smallexample @item P Inserts the payee related to a posting. +@smallexample @c command:F41A9BB,with_input:3406FC1 +$ ledger -f expr.dat --format "%P\n" reg assets +@end smallexample +@smallexample @c output:F41A9BB +PiggyBank +@end smallexample @c @item a @c Inserts the optimal short name for an account. This is normally @@ -8191,6 +8559,13 @@ Inserts the payee related to a posting. @item A Inserts the full name of an account. +@smallexample @c command:29A70DD,with_input:3406FC1 +$ ledger -f expr.dat --format "%A\n" reg +@end smallexample +@smallexample @c output:29A70DD +Assets:Cash +Expenses:Office Supplies +@end smallexample @c @item W @c This is the same as @code{%A}, except that it first displays the @@ -8207,12 +8582,25 @@ Inserts the full name of an account. @item N Inserts the note associated with a posting, if one exists. +@smallexample @c command:E6DC93A,with_input:3406FC1 +$ ledger -f expr.dat --format "%N\n" reg assets +@end smallexample +@smallexample @c output:E6DC93A + Payee: PiggyBank +@end smallexample @item / The @samp{%/} construct is special. It separates a format string between what is printed for the first posting of a transaction, and what is printed for all subsequent postings. If not used, the same format string is used for all postings. +@smallexample @c command:E80897D,with_input:3406FC1 +$ ledger -f expr.dat --format "%P\n%/%A\n" reg +@end smallexample +@smallexample @c output:E80897D +PiggyBank +Expenses:Office Supplies +@end smallexample @end table @@ -9323,7 +9711,7 @@ slowdown. When combined with @option{--debug @var{CODE}} ledger will produce memory trace information. @item --verify-memory -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @item --version Print version information and exit. @@ -9421,7 +9809,7 @@ true @end smallexample @item script -FIX THIS ENTRY @c FIXME thdox +@value{FIXME:UNDOCUMENTED} @item template Shows the insertion template that the @command{xact} sub-command @@ -9706,11 +10094,23 @@ to the main body of the documentation. @node Invoking Ledger, Ledger Files, Cookbook, Cookbook @subsection Invoking Ledger -@smallexample + +@smallexample @c command:validate $ ledger --group-by "tag('trip')" bal -$ ledger reg --sort "tag('foo')" %foo +@end smallexample +@c FIXME: The following example fails to validate due to: +@c While applying is_realzero to : +@c Error: Cannot determine if an uninitialized value is really zero +@c @smallexample @c command:validate +@c $ ledger reg --sort "tag('foo')" %foo +@c @end smallexample +@smallexample @c command:validate $ ledger cleared VWCU NFCU Tithe Misentry +@end smallexample +@smallexample @c command:validate $ ledger register Joint --uncleared +@end smallexample +@smallexample @c command:validate $ ledger register Checking --sort d -d 'd>[2011/04/01]' until 2011/05/25 @end smallexample -- cgit v1.2.3 From 18e5fa969f0f2e6ed86d1534ffbcbf09201c5f93 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Fri, 23 Jan 2015 07:56:03 +0100 Subject: [doc] Change FILES section into a Pathname list [ci skip] --- doc/ledger.1 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 8aa0f474..f14fc54d 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -1067,8 +1067,10 @@ and displays information about how it was parsed. See the section on .Sx DRAFTS . .El .Sh FILES -~/.ledgerrc +.Bl -tag -width -indent +.It Pa ~/.ledgerrc Your personal ledger initializations. +.El .Sh SEE ALSO .Xr beancount 1 , .Xr hledger 1 -- cgit v1.2.3 From 2d33ddf12f0548e57770319a424ce147b5d14e82 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Fri, 23 Jan 2015 08:13:01 +0100 Subject: [doc] Use ASCII single quote as apostrophe [ci skip] --- doc/ledger.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index f14fc54d..3e646bc0 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -439,7 +439,7 @@ but not This is a display predicate, which means it only affects display, not the total calculations. .It Fl \-deviation Pq Fl D -Report each posting’s deviation from the average. It is only meaningful +Report each posting's deviation from the average. It is only meaningful in the register and prices reports. .It Fl \-display Ar EXPR Pq Fl d Display lines that satisfy the expression -- cgit v1.2.3 From 91862091c0141a87bc75f836e6cd9ac2c633b561 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Fri, 23 Jan 2015 08:33:49 +0100 Subject: [doc] Replace .Nm with .Ic where appropriate According to mdoc (7) "The `.Nm' macro is used for the document title or subject name. It has the peculiarity of remembering the first argument it was called with, which should always be the subject name of the page." Therefore it should only be used the print `ledger` in the manpage For the Ledger commands register, balance, etc The .Ic (internal command) is much better suited. [ci skip] --- doc/ledger.1 | 160 ++++++++++++++++++++++++++++++----------------------------- 1 file changed, 82 insertions(+), 78 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 3e646bc0..b48d3e6d 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -33,12 +33,12 @@ dataset without reparsing. .Pp The following is a complete list of reporting commands accepted by Ledger: .Bl -tag -width accounts -.It Nm accounts Oo Ar report-query Oc +.It Ic accounts Oo Ar report-query Oc Lists all accounts for postings matching the .Ar report-query . .El .Bl -tag -width balance -.It Nm balance Oo Ar report-query Oc +.It Ic balance Oo Ar report-query Oc Produces a balance report showing totals for all matching accounts, and aggregate totals for parents of those accounts. Options most commonly used with this command are: @@ -60,11 +60,11 @@ Suppress the summary total shown at the bottom of the report (when not zero). .El .Pp The synonyms -.Nm bal +.Ic bal and -.Nm b +.Ic b are also accepted. -.It Nm budget Oo Ar report-query Oc +.It Ic budget Oo Ar report-query Oc A special balance report which includes three extra columns: the amount budgeted during the reporting period, how spending differed from the budget, and the percentage of budget spent (exceeds 100% if you go over budget). @@ -73,23 +73,23 @@ Note that budgeting requires one or more periodic transactions .Dc to be defined in your data file(s). See the manual for more information. -.It Nm cleared Oo Ar report-query Oc +.It Ic cleared Oo Ar report-query Oc A special balance report which adds two extra columns: the cleared balance for each account, and the date of the most recent cleared posting in that account. For this accounting to be meaningful, the cleared flag must be set on at least one posting. See the manual for more information. -.It Nm commodities Oo Ar report-query Oc +.It Ic commodities Oo Ar report-query Oc Lists all commodities for postings matching the .Ar report-query . -.It Nm convert +.It Ic convert Reads data from a CSV (comma-separated values) file and generates Ledger transactions. -.It Nm csv Oo Ar report-query Oc +.It Ic csv Oo Ar report-query Oc Report of postings matching the .Ar report-query in CSV format (comma-separated values). Useful for exporting data to a spreadsheet for further analysis or charting. -.It Nm entry Oo Ar entry-template Oc +.It Ic entry Oo Ar entry-template Oc Generate and display a new, properly formatted Ledger transaction by comparing the .Ar entry-template @@ -99,14 +99,14 @@ section .Sx ENTRIES . .Pp The synonym -.Nm xact +.Ic xact is also accepted. -.It Nm emacs Oo Ar query Oc +.It Ic emacs Oo Ar query Oc Outputs posting and transaction data in a format readily consumed by the Emacs editor, in a series of Lisp forms. This is used by the .Li ledger.el Emacs mode to process reporting data from Ledger. -.It Nm equity Oo Ar report-query Oc +.It Ic equity Oo Ar report-query Oc Prints a series of transactions that balance current totals for accounts matching the .Ar report-query @@ -114,38 +114,38 @@ in a special account called .Li Equity:Opening Balances . The purpose of this report is to close the books for a prior year, while using these equity transactions to carry forward those balances. -.It Nm org +.It Ic org Produces a journal file suitable for use in the Emacs org mode. -.It Nm payees Oo Ar report-query Oc +.It Ic payees Oo Ar report-query Oc Lists all payees for postings matching the .Ar report-query . -.It Nm pricemap +.It Ic pricemap Produces a file which can be used to generate a graph with graphviz showing the relationship of commodities in the Ledger file. -.It Nm prices Oo Ar report-query Oc +.It Ic prices Oo Ar report-query Oc Reports prices for all commodities in postings matching the .Ar report-query . The prices are reported with the granularity of a single day. -.It Nm pricedb Oo Ar report-query Oc +.It Ic pricedb Oo Ar report-query Oc Reports prices for all commodities in postings matching the .Ar report-query . Prices are reported down to the second, using the same format as the .Li ~/.pricedb file. -.It Nm print Oo Ar report-query Oc +.It Ic print Oo Ar report-query Oc Prints out the full transactions of any matching postings using the same format as they would appear in a data file. This can be used to extract subsets from a Ledger file to transfer to other files. -.It Nm push Oo Ar options Oc +.It Ic push Oo Ar options Oc In the .Tn REPL , this command pushes a set of command-line options, so that they will apply to all subsequent reports. -.It Nm pop +.It Ic pop In the .Tn REPL , pops any option settings that have been pushed. -.It Nm register Oo Ar report-query Oc +.It Ic register Oo Ar report-query Oc List all postings matching the .Ar report-query . This is one of the most common commands, and can be used to provide a variety @@ -162,10 +162,10 @@ Render all values in the given .Ar commodity , if a price conversion rate can be determined. Rates are always displayed relative to the date of the posting they are calculated for. This means a -.Nm register +.Ic register report is a historical value report. For current values, it may be preferable to use the -.Nm balance +.Ic balance report. .It Fl \-gain Pq Fl G Show any gains (or losses) in commodity values over time. @@ -227,28 +227,28 @@ Group postings by year. Group postings by the day of the week on which they took place. .It Fl \-subtotal Pq Fl s Group all postings together. This is very similar to the totals shown by the -.Nm balance +.Ic balance report. .El .Pp The synonyms -.Nm reg +.Ic reg and -.Nm r +.Ic r are also accepted. -.It Nm server +.It Ic server This command requires that Python support be active. If so, it starts up an HTTP server listening for requests on port 9000. This provides an alternate interface to creating and viewing reports. Note that this is very much a work-in-progress, and will not be fully functional until a later version. -.It Nm select Oo Ar sql-query Oc +.It Ic select Oo Ar sql-query Oc List all postings matching the .Ar sql-query . This command allows to generate SQL-like queries. -.It Nm source +.It Ic source Parses a journal file and checks it for errors. Ledger will return success if no errors are found. -.It Nm stats Oo Ar report-query Oc +.It Ic stats Oo Ar report-query Oc Provides summary information about all the postings matching .Ar report-query . It provides information such as: @@ -268,7 +268,7 @@ Days since last posting .It More... .El -.It Nm xml Oo Ar report-query Oc +.It Ic xml Oo Ar report-query Oc Outputs data relating to the current report in XML format. It includes all accounts and commodities involved in the report, plus the postings and the transactions they are contained in. See the manual for more information. @@ -300,7 +300,7 @@ would tack to the beginning of every account reported in a balance report or register report. .It Fl \-account-width Ar INT Set the width of the account column in the -.Nm register +.Ic register report to .Ar INT @@ -320,7 +320,7 @@ On a register report print only the dates and amount of postings. Useful for graphing and spreadsheet applications. .It Fl \-amount-width Ar INT Set the width in characters of the amount column in the -.Nm register +.Ic register report. .It Fl \-anon Anonymize registry output, mostly for sending in bug reports. @@ -336,7 +336,7 @@ Print average values over the number of transactions instead of running totals. .It Fl \-balance-format Ar FMT Specify the format to use for the -.Nm balance +.Ic balance report. .\".It Fl \-base .It Fl \-basis Pq Fl B @@ -351,12 +351,13 @@ that date will be ignored. .It Fl \-bold-if Ar EXPR Print the entire line in bold if the given value expression is true. .It Fl \-budget -Only display budgeted items. In a register report this -displays transaction in the budget, in a balance report this displays -accounts in the budget. +Only display budgeted items. In a +.Ic register +report this displays transaction in the budget, in a balance report this +displays accounts in the budget. .It Fl \-budget-format Ar FMT Specify the format to use for the -.Nm budget +.Ic budget report. .It Fl \-by-payee Pq Fl P Group postings in the register report by common payee names. @@ -368,7 +369,7 @@ commodities and tags. Display only cleared postings. .It Fl \-cleared-format Ar FMT Specify the format to use for the -.Nm cleared +.Ic cleared report .It Fl \-collapse Pq Fl n By default ledger prints all accounts in an account tree. With @@ -382,7 +383,7 @@ Alias for .Fl \-ansi .It Fl \-columns Ar INT Specify the width of the -.Nm register +.Ic register report in characters. .It Fl \-cost Report the cost basis on all posting. @@ -390,14 +391,14 @@ Alias for .Fl \-basis . .It Fl \-count Direct ledger to report the number of items when appended to the -.Nm commodities , -.Nm accounts +.Ic commodities , +.Ic accounts or -.Nm payees +.Ic payees commands. .It Fl \-csv-format Ar FMT Specify the format to use for the -.Nm csv +.Ic csv report .It Fl \-current Pq Fl c Shorthand for @@ -413,14 +414,17 @@ Specify the format ledger should use to print dates. .\" .It Fl \-datetime-format Ar FMT .It Fl \-date-width Ar INT Specify the width, in characters, of the date column in the -.Nm register +.Ic register report. .\".It Fl \-day-break .It Fl \-dc Display register or balance in debit/credit format If you use .Fl \-dc -with either the register (reg) or balance (bal) commands, -you will now get separate columns for debits and credits. +with either the +.Ic register +or +.Ic balance +commands, you will now get separate columns for debits and credits. .It Fl \-debug Ar STR If Ledger has been built with debug options this will provide extra data during the run. @@ -479,7 +483,7 @@ for a transaction to be considered in the report. .It Fl \-equity Related to the -.Nm equity +.Ic equity command. Gives current account balances in the form of a register report. .\".It Fl \-exact @@ -530,7 +534,7 @@ transactions) in the report, in cases where you normally wouldn't want them. .It Fl \-group-by Ar EXPR Group transaction together in the -.Nm register +.Ic register report. .Ar EXPR can be anything, although most common would be @@ -655,7 +659,7 @@ Specify the pager program to use as .Ar STR . .It Fl \-payee Sets a value expression for formatting the payee. In the -.Nm register +.Ic register report this prevents the second entry from having a date and payee for each transaction. .It Fl \-payee-width Ar INT @@ -672,7 +676,7 @@ Only works for account that have a single commodity. .It Fl \-period Ar PERIOD Pq Fl p Define a period expression that sets the time period during which transactions are to be accounted. For a -.Nm register +.Ic register report only the transactions that satisfy the period expression with be displayed. For a balance report only those transactions will be accounted in the @@ -715,7 +719,7 @@ Alias for .Fl \-leeway Ar INT Pq Fl Z .It Fl \-prices-format Ar FMT Set the format for the -.Nm prices +.Ic prices report. .It Fl \-pricedb-format Ar FMT Set the format expected for the historical price file. @@ -729,7 +733,7 @@ Shorthand for .Fl \-period Ar "quarterly" . .It Fl \-raw In the -.Nm print +.Ic 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 @@ -742,7 +746,7 @@ Causes ledger to try to expand aliases recursively, i.e. try to expand the result of an earlier expansion again, until no more expansions apply. .It Fl \-register-format Ar FMT Define the output format for the -.Nm register +.Ic register report. .It Fl \-related Pq Fl r In a register report show the related account. This is the other @@ -762,7 +766,7 @@ of each transaction. Set the random seed to .Ar INT for the -.Nm generate +.Ic generate command. Used as part of development testing. .It Fl \-script Ar FILE Execute a ledger script. @@ -835,7 +839,7 @@ Perform all calculations without rounding and display results to full precision. .It Fl \-values Shows the values used by each tag when used in combination with the -.Nm tags +.Ic tags command. .\".It Fl \-value-expr Ar EXPR .It Fl \-verbose @@ -863,26 +867,26 @@ will work. The difference between a pre-command and a regular command is that pre-commands ignore the journal data file completely, nor is the user's init file read. .Bl -tag -width -indent -.It Nm args / query +.It Ic args / query Evaluate the given arguments and report how Ledger interprets it against the following model transaction. -.It Nm eval +.It Ic eval Evaluate the given value expression against the model transaction. -.It Nm format +.It Ic format Print details of how ledger uses the given formatting description and apply it against a model transaction. -.It Nm parse / expr +.It Ic parse / expr Print details of how ledger uses the given value expression description and apply it against a model transaction. -.It Nm generate +.It Ic generate Randomly generates syntactically valid Ledger data from a seed. Used by the GenerateTests harness for development testing. -.It Nm period +.It Ic period Evaluate the given period and report how Ledger interprets it. -.It Nm script -.It Nm template +.It Ic script +.It Ic template Shows the insertion template that the -.Nm xact +.Ic xact sub-command generates. This is a debugging command. .El .Sh QUERIES @@ -896,12 +900,12 @@ Thus, to report the current balance for all assets and liabilities, you would use: .Pp .Dl ledger bal asset liab -.It Nm payee Ar regex Pq \&@ Ns Ar regex +.It Ic payee Ar regex Pq \&@ Ns Ar regex Query on the payee, rather than the account. -.It Nm tag Ar regex Pq \&% Ns Ar regex -.It Nm note Ar regex Pq \&= Ns Ar regex +.It Ic tag Ar regex Pq \&% Ns Ar regex +.It Ic note Ar regex Pq \&= Ns Ar regex Query on anything found in an item's note. -.It Nm code Ar regex Pq \&# Ns Ar regex +.It Ic code Ar regex Pq \&# Ns Ar regex Query on the xact's optional code (which can be any string the user wishes). .It Ar term Nm and Ar term Query terms are joined by an implicit OR operator. You can change this to AND @@ -1025,42 +1029,42 @@ with double-quotes. In addition to the regular reporting commands, Ledger also accepts several debug commands: .Bl -tag -width balance -.It Nm args Oo Ar report-query Oc +.It Ic args Oo Ar report-query Oc Accepts a .Ar report-query as its argument and displays it back to the user along with a complete analysis of how Ledger interpreted it. Useful if you want to understand how report queries are translated into value expressions. -.It Nm eval Oo Ar value-expression Oc +.It Ic eval Oo Ar value-expression Oc Evaluates the given .Ar value-expression and prints the result. For more on value expressions, see the section .Sx EXPRESSIONS . -.It Nm format Oo Ar format-string Oc +.It Ic format Oo Ar format-string Oc Accepts a .Ar format-string and displays an analysis of how it was parsed, and what it would look like applied to a sample transaction. For more on format strings, see the section .Sx FORMATS . -.It Nm generate +.It Ic generate Generates 50 randomly composed yet valid Ledger transactions. -.It Nm parse Oo Ar value-expression Oc +.It Ic parse Oo Ar value-expression Oc Parses the given .Ar value-expression and display an analysis of the expression tree and its evaluated value. For more on value expressions, see the section .Sx EXPRESSIONS . -.It Nm python Oo Ar file Oc +.It Ic python Oo Ar file Oc Invokes a Python interpreter to read the given .Ar file . What is special about this is that the ledger module is builtin, not read from disk, so it doesn't require Ledger to be installed anywhere, or the shared library variants to be built. -.It Nm reload +.It Ic reload Used only in the .Tn REPL , it causes an immediate reloading of all data files for the current session. -.It Nm template Oo Ar draft-template Oc +.It Ic template Oo Ar draft-template Oc Accepts a .Ar draft-template and displays information about how it was parsed. See the section on -- cgit v1.2.3 From 0f04246e43df92935318336de3c5d5300cb60578 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Fri, 23 Jan 2015 13:02:25 +0100 Subject: [doc] Improve quoting in manpage [ci skip] --- doc/ledger.1 | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index b48d3e6d..ecec1bba 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -186,9 +186,7 @@ Show postings only for the given .It Fl \-related Pq Fl r Show postings that are related to those that would have been shown. It has the effect of displaying the -.Do -other side -.Dc +.Qq other side of the values. .It Fl \-sort Ar value-expression Pq Fl S Sort postings by evaluating the given @@ -294,7 +292,7 @@ desired width. Prepend .Ar STR to all accounts reported. That is, the option -.Nm --account Personal +.Fl \-account Ar \*q'Personal'\*q would tack .Nm Personal: to the beginning of every account reported in a balance report or register report. @@ -405,7 +403,7 @@ Shorthand for .Fl \-limit Ar "'date <= today'" . .It Fl \-daily Pq Fl D Shorthand for -.Fl \-period Ar "daily" . +.Fl \-period Ar daily . .It Fl \-date Ar EXPR Transform the date of the transaction using .Ar EXPR . @@ -621,7 +619,7 @@ Specify the width of the Meta column used for the options. .It Fl \-monthly Pq Fl M Shorthand for -.Fl \-period Ar "monthly" . +.Fl \-period Ar monthly . .It Fl \-no-aliases Aliases are completely ignored. .It Fl \-no-color @@ -687,7 +685,7 @@ Sort the posting within transactions using the given value expression. Quiet balance assertions. .It Fl \-pivot Ar STR Produce a balance pivot report -.Nm around +.Qq around the given .Ar TAG . .It Fl \-plot-amount-format Ar FMT @@ -730,7 +728,7 @@ Show primary dates for all calculations. Alias for Report commodity totals (this is the default). .It Fl \-quarterly Shorthand for -.Fl \-period Ar "quarterly" . +.Fl \-period Ar quarterly . .It Fl \-raw In the .Ic print @@ -776,10 +774,13 @@ Sort the register report based on the value expression given to sort. .It Fl \-sort-xacts Sort the posting within transactions using the given value expression. .It Fl \-start-of-week Ar STR -Tell ledger to use a particular day of the week to start its "weekly" +Tell ledger to use a particular day of the week to start its +.Qq weekly summary. .Ar STR -can be day names, their abbreviations like "Mon", or the weekday number +can be day names, their abbreviations like +.Qq Mon , +or the weekday number starting at 0 for Sunday. .It Fl \-strict Accounts, tags or commodities not previously declared will cause warnings. @@ -812,7 +813,8 @@ and .Nm trailing . The default is smarter than any of these three, as it considers sub-names within the account name (that style is -called "abbreviate"). +called +.Qq abbreviate ) . .It Fl \-unbudgeted Show only un-budgeted postings. .It Fl \-uncleared Pq Fl U @@ -854,12 +856,12 @@ ledger will produce memory trace information. Print version information and exit. .It Fl \-weekly Pq Fl W Shorthand for -.Fl \-period Ar "weekly" . +.Fl \-period Ar weekly . .It Fl \-wide Pq Fl w Assume 132 columns instead of 80. .It Fl \-yearly Pq Fl Y Shorthand for -.Fl \-period Ar "yearly" . +.Fl \-period Ar yearly . .El .Sh PRE-COMMANDS Pre-commands are useful when you aren't sure how a command or option -- cgit v1.2.3 From 76340864654c97902e1358e4f8ec56768cd625ec Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Fri, 23 Jan 2015 13:07:05 +0100 Subject: [doc] Replace Nm with more appropriate macros in manpage such as Fl, Ar, Ev, Em, etc. [ci skip] --- doc/ledger.1 | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index ecec1bba..0c2e63bf 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -294,7 +294,7 @@ Prepend to all accounts reported. That is, the option .Fl \-account Ar \*q'Personal'\*q would tack -.Nm Personal: +.Ar Personal: to the beginning of every account reported in a balance report or register report. .It Fl \-account-width Ar INT Set the width of the account column in the @@ -310,7 +310,7 @@ transactions used. Show only un-budgeted postings. .It Fl \-amount Ar EXPR Pq Fl t Apply the given value expression to the posting amount. Using -.Nm --amount Ar EXPR +.Fl \-amount Ar EXPR you can apply an arbitrary transformation to the postings. .It Fl \-amount-data Pq Fl j @@ -448,12 +448,12 @@ Display lines that satisfy the expression .Ar EXPR . .It Fl \-display-amount Ar EXPR Apply a transformation to the -.Nm displayed +.Em displayed amount. This occurs after calculations occur. .It Fl \-display-total Ar EXPR Apply a transformation to the -.Nm displayed +.Em displayed total. This occurs after calculations occur. .It Fl \-dow @@ -463,15 +463,14 @@ Alias for .It Fl \-download Cause quotes to be automagically downloaded, as needed, by running a script named -.Nm getquote +.Em getquote and expecting that script to return -a value understood by ledger. A sample implementation of -a -.Nm getquote +a value understood by ledger. A sample implementation of a +.Em getquote script, implemented in Perl, is provided in the distribution. Downloaded quote price are then appended to the price database, usually specified using the environment variable -.Nm LEDGER_PRICE_DB . +.Ev LEDGER_PRICE_DB . .It Fl \-empty Pq Fl E Include empty accounts in report. .It Fl \-end Ar DATE Pq Fl e @@ -536,11 +535,11 @@ Group transaction together in the report. .Ar EXPR can be anything, although most common would be -.Nm payee +.Ar payee or -.Nm commodity . +.Ar commodity . The -.Nm tags() +.Fn tags function is also useful here. .It Fl \-group-title-format Ar FMT Set the format for the headers that separate reports section of @@ -566,7 +565,7 @@ Instruct ledger to evaluate calculations immediately rather than lazily. .\".It Fl \-import .It Fl \-init-file Ar FILE Pq Fl i Causes -.Nm FILE +.Ar FILE to be read by ledger before any other ledger file. This file may not contain any postings, but it may contain option settings. To specify options in the init file, use the same syntax as @@ -628,7 +627,7 @@ Suppress any color TTY output. Disables the pager on TTY output. .It Fl \-no-rounding Don't output -.Nm +.Li Qq postings. Note that this will cause the running total to often not add up! It's main use is for .Fl \-amount-data Pq Fl j @@ -748,13 +747,13 @@ Define the output format for the report. .It Fl \-related Pq Fl r In a register report show the related account. This is the other -.Nm side +.Em side of the transaction. .It Fl \-related-all Show all postings in a transaction, similar to .Fl \-related but show -.Nm both sides +.Em both sides of each transaction. .\".It Fl \-revalued .\".It Fl \-revalued-only @@ -805,12 +804,13 @@ Set the width of the total field in the register report. Enable tracing. The .Ar INT specifies the level of trace desired. -.It Fl \-truncate Ar CODE +.It Fl \-truncate Ar STR Indicates how truncation should happen when the contents of columns exceed their width. Valid arguments are -.Nm leading , Nm middle , +.Ar leading , +.Ar middle , and -.Nm trailing . +.Ar trailing . The default is smarter than any of these three, as it considers sub-names within the account name (that style is called -- cgit v1.2.3 From 37777c284cd3cdb97a8d01b0633d30ed0d461f82 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Fri, 23 Jan 2015 13:10:14 +0100 Subject: [doc] Correct Ar placholders in manpage [ci skip] --- doc/ledger.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 0c2e63bf..815eae47 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -682,7 +682,7 @@ final balances. Sort the posting within transactions using the given value expression. .It Fl \-permissive Quiet balance assertions. -.It Fl \-pivot Ar STR +.It Fl \-pivot Ar TAG Produce a balance pivot report .Qq around the given @@ -693,7 +693,7 @@ Define the output format for an amount data plot. Define the output format for a total data plot. .It Fl \-prepend-format Ar FMT Prepend -.Ar STR +.Ar FMT to every line of the output. .It Fl \-prepend-width Ar INT Reserve -- cgit v1.2.3 From ce4511a22025eacfd5e035f2af639aac7cbd823d Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Fri, 23 Jan 2015 13:41:12 +0100 Subject: [doc] Replace Nm with Sy, Cm, Pa in manpage [ci skip] --- doc/ledger.1 | 138 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 69 insertions(+), 69 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 815eae47..12874d31 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -130,7 +130,7 @@ The prices are reported with the granularity of a single day. Reports prices for all commodities in postings matching the .Ar report-query . Prices are reported down to the second, using the same format as the -.Li ~/.pricedb +.Pa ~/.pricedb file. .It Ic print Oo Ar report-query Oc Prints out the full transactions of any matching postings using the same @@ -276,7 +276,7 @@ transactions they are contained in. See the manual for more information. .It Fl \-abbrev-len Ar INT Set the minimum length an account can be abbreviated to if it doesn't fit inside the -.Nm account-width . +.Sy account-width . If .Ar INT is zero, then the @@ -284,7 +284,7 @@ account name will be truncated on the right. If .Ar INT is greater than -.Nm account-width +.Sy 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. @@ -435,9 +435,9 @@ a .Fl \-depth 2 statement will print balances only for account with two levels, i.e. -.Nm Expenses:Entertainment +.Sy Expenses:Entertainment but not -.Nm Expenses:entertainment:Dining . +.Sy Expenses:entertainment:Dining . This is a display predicate, which means it only affects display, not the total calculations. .It Fl \-deviation Pq Fl D @@ -825,16 +825,16 @@ report. .It Fl \-unrealized-gains Allow the user to specify what account name should be used for unrealized gains. Defaults to -.Nm "Equity:Unrealized Gains" . +.Sy "Equity:Unrealized Gains" . Often set in one's -.Nm ~/.ledgerrc +.Pa ~/.ledgerrc file to change the default. .It Fl \-unrealized-losses Allow the user to specify what account name should be used for unrealized gains. Defaults to -.Nm "Equity:Unrealized Losses" . +.Sy "Equity:Unrealized Losses" . Often set in one's -.Nm ~/.ledgerrc +.Pa ~/.ledgerrc file to change the default. .It Fl \-unround Perform all calculations without rounding and display results to full @@ -909,16 +909,16 @@ Query on the payee, rather than the account. Query on anything found in an item's note. .It Ic code Ar regex Pq \&# Ns Ar regex Query on the xact's optional code (which can be any string the user wishes). -.It Ar term Nm and Ar term +.It Ar term Cm and Ar term Query terms are joined by an implicit OR operator. You can change this to AND by using that keyword. For example, to show food expenditures occurring at Shakee's Pizza, you could say: .Pp -.Dl ledger reg food and @Shakee -.It Ar term Nm or Ar term +.Dl Li ledger reg food and @Shakee +.It Ar term Cm or Ar term When you wish to be more explicit, use the OR operator. -.It Nm show -.It Nm not Ar term +.It Ic show +.It Cm not Ar term Reverse the logical meaning of the following term. This can be used with parentheses to great effect: .Pp @@ -935,12 +935,12 @@ interpret parentheses, you should always escape them: .It Fn abs value Return the absolute value of the given .Ar value . -.It Nm account -.It Nm account_base -.It Nm account_amount -.It Nm actual -.It Nm amount -.It Nm amount_expr +.It Sy account +.It Sy account_base +.It Sy account_amount +.It Sy actual +.It Sy amount +.It Sy amount_expr .It Fn ansify_if value color bool Render the given .Ar value @@ -949,33 +949,33 @@ as a string, applying the proper ANSI escape codes to display it in the given if .Ar bool is true. It typically checks the value of the option -.Nm Fl \-color , +.Fl \-color , for example: -.Dl ansify_if(amount, "blue", options.color) -.It Nm beg_line +.Dl Li ansify_if(amount, "blue", options.color) +.It Sy beg_line Line number where entry for posting begins. -.It Nm beg_pos +.It Sy beg_pos Character position where entry for posting begins. -.It Nm calculated -.It Nm cleared -.It Nm code +.It Sy calculated +.It Sy cleared +.It Sy code Return the transaction code, the string between the parenthesis after the date. -.It Nm comment -.It Nm commodity +.It Sy comment +.It Sy commodity Return the commodity of the posting amount. -.It Nm cost -.It Nm count -.It Nm date +.It Sy cost +.It Sy count +.It Sy date Return the date of the posting. -.It Nm depth -.It Nm depth_spacer -.It Nm display_amount -.It Nm display_total -.It Nm end_line +.It Sy depth +.It Sy depth_spacer +.It Sy display_amount +.It Sy display_total +.It Sy end_line Line number where entry for posting ends. -.It Nm end_pos +.It Sy end_pos Character position where entry for posting ends. -.It Nm filename +.It Sy filename The name of the ledger data file from whence the posting came. .It Fn format_date date format Return the @@ -985,45 +985,45 @@ as a string using See .Xr strftime 3 for format string details. -.It Nm get_at -.It Nm has_meta -.It Nm has_tag -.It Nm is_seq -.It Nm join -.It Nm market -.It Nm meta -.It Nm note -.It Nm null -.It Nm options -.It Nm partial_account -.It Nm payee +.It Sy get_at +.It Sy has_meta +.It Sy has_tag +.It Sy is_seq +.It Sy join +.It Sy market +.It Sy meta +.It Sy note +.It Sy null +.It Sy options +.It Sy partial_account +.It Sy payee +.It Sy pending .It Fn percent value_a value_b Return the percentage of .Ar value_a in relation to .Ar value_b . -.It Nm pending -.It Nm post -.It Nm print -.It Nm quantity +.It Sy post +.It Sy print +.It Sy quantity .It Fn quoted expression Surround .Ar expression with double-quotes. -.It Nm real -.It Nm rounded -.It Nm scrub -.It Nm status -.It Nm strip -.It Nm subcount -.It Nm tag -.It Nm today -.It Nm total -.It Nm total_expr -.It Nm truncate -.It Nm uncleared -.It Nm virtual -.It Nm xact +.It Sy real +.It Sy rounded +.It Sy scrub +.It Sy status +.It Sy strip +.It Sy subcount +.It Sy tag +.It Sy today +.It Sy total +.It Sy total_expr +.It Sy truncate +.It Sy uncleared +.It Sy virtual +.It Sy xact .El .Sh ENTRIES .Sh FORMATS -- cgit v1.2.3 From d8bbc400058f99c711360ac47d237c12fe9bf48b Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Fri, 23 Jan 2015 15:16:14 +0100 Subject: [doc] Use .Nm instead of [Ll]edger in manpage [ci skip] --- doc/ledger.1 | 182 ++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 135 insertions(+), 47 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 12874d31..257070d0 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -5,17 +5,19 @@ .Nm ledger .Nd Command-line, double-entry account reporting tool .Sh SYNOPSIS -ledger +.Nm .Op Ar command .Op Ar options .Op Ar arguments .Sh DESCRIPTION -Ledger is a command-line accounting tool based on the power and completeness +.Nm +is a command-line accounting tool based on the power and completeness of double-entry accounting. It is only a reporting tool, which means it never modifies your data files, but it does offers a large selection of reports, and different ways to customize them to your liking. .Sh COMMANDS -Ledger accepts several top-level commands, each of which generates a different +.Nm +accepts several top-level commands, each of which generates a different kind of basic report. Most of them accept a .Ar report-query argument, in order to determine what should be reported. To understand the @@ -26,12 +28,15 @@ see the section on In its most basic form, simply specifying one or more strings produces a report for all accounts containing those strings. .Pp -If no command is given, Ledger enters a +If no command is given, +.Nm +enters a .Tn REPL , or command loop, allowing several commands to be executed against the same dataset without reparsing. .Pp -The following is a complete list of reporting commands accepted by Ledger: +The following is a complete list of reporting commands accepted by +.Nm : .Bl -tag -width accounts .It Ic accounts Oo Ar report-query Oc Lists all accounts for postings matching the @@ -82,7 +87,8 @@ one posting. See the manual for more information. Lists all commodities for postings matching the .Ar report-query . .It Ic convert -Reads data from a CSV (comma-separated values) file and generates Ledger +Reads data from a CSV (comma-separated values) file and generates +.Nm transactions. .It Ic csv Oo Ar report-query Oc Report of postings matching the @@ -90,7 +96,9 @@ Report of postings matching the in CSV format (comma-separated values). Useful for exporting data to a spreadsheet for further analysis or charting. .It Ic entry Oo Ar entry-template Oc -Generate and display a new, properly formatted Ledger transaction by comparing +Generate and display a new, properly formatted +.Nm +transaction by comparing the .Ar entry-template to the transactions in your data file(s). For more information on draft @@ -104,8 +112,9 @@ is also accepted. .It Ic emacs Oo Ar query Oc Outputs posting and transaction data in a format readily consumed by the Emacs editor, in a series of Lisp forms. This is used by the -.Li ledger.el -Emacs mode to process reporting data from Ledger. +.Pa ledger.el +Emacs mode to process reporting data from +.Nm . .It Ic equity Oo Ar report-query Oc Prints a series of transactions that balance current totals for accounts matching the @@ -121,7 +130,9 @@ Lists all payees for postings matching the .Ar report-query . .It Ic pricemap Produces a file which can be used to generate a graph with graphviz showing -the relationship of commodities in the Ledger file. +the relationship of commodities in the +.Nm +file. .It Ic prices Oo Ar report-query Oc Reports prices for all commodities in postings matching the .Ar report-query . @@ -135,7 +146,9 @@ file. .It Ic print Oo Ar report-query Oc Prints out the full transactions of any matching postings using the same format as they would appear in a data file. This can be used to extract -subsets from a Ledger file to transfer to other files. +subsets from a +.Nm +file to transfer to other files. .It Ic push Oo Ar options Oc In the .Tn REPL , @@ -244,7 +257,9 @@ List all postings matching the .Ar sql-query . This command allows to generate SQL-like queries. .It Ic source -Parses a journal file and checks it for errors. Ledger will return success +Parses a journal file and checks it for errors. +.Nm +will return success if no errors are found. .It Ic stats Oo Ar report-query Oc Provides summary information about all the postings matching @@ -323,7 +338,9 @@ report. .It Fl \-anon Anonymize registry output, mostly for sending in bug reports. .It Fl \-args-only -Ignore init files and environment variables for the ledger run. +Ignore init files and environment variables for the +.Nm +run. .\".It Fl \-auto-match .It Fl \-aux-date Show auxiliary dates for all calculations. @@ -370,7 +387,9 @@ Specify the format to use for the .Ic cleared report .It Fl \-collapse Pq Fl n -By default ledger prints all accounts in an account tree. With +By default +.Nm +prints all accounts in an account tree. With .Fl \-collapse it prints only the top level account specified. .It Fl \-collapse-if-zero @@ -388,7 +407,9 @@ Report the cost basis on all posting. Alias for .Fl \-basis . .It Fl \-count -Direct ledger to report the number of items when appended to the +Direct +.Nm +to report the number of items when appended to the .Ic commodities , .Ic accounts or @@ -408,7 +429,9 @@ Shorthand for Transform the date of the transaction using .Ar EXPR . .It Fl \-date-format Ar DATEFMT Pq Fl y -Specify the format ledger should use to print dates. +Specify the format +.Nm +should use to print dates. .\" .It Fl \-datetime-format Ar FMT .It Fl \-date-width Ar INT Specify the width, in characters, of the date column in the @@ -424,10 +447,14 @@ or .Ic balance commands, you will now get separate columns for debits and credits. .It Fl \-debug Ar STR -If Ledger has been built with debug options this will provide extra +If +.Nm +has been built with debug options this will provide extra data during the run. .It Fl \-decimal-comma -Direct Ledger to parse journals using the European standard comma as +Direct +.Nm +to parse journals using the European standard comma as decimal separator, vice a period. .It Fl \-depth Ar INT Limit the depth of the account tree. In a balance report, for example, @@ -465,7 +492,9 @@ Cause quotes to be automagically downloaded, as needed, by running a script named .Em getquote and expecting that script to return -a value understood by ledger. A sample implementation of a +a value understood by +.Nm . +A sample implementation of a .Em getquote script, implemented in Perl, is provided in the distribution. Downloaded quote price are then appended to the price @@ -492,7 +521,9 @@ The latest available price is used. .It Fl \-file Ar FILE Read .Ar FILE -as a ledger file. +as a +.Nm +file. .\".It Fl \-full-help .It Fl \-first Ar INT Print the first @@ -508,7 +539,9 @@ balance report will not use an indented tree. Output TTY color codes even if the TTY doesn't support them. Useful for TTYs that don't advertise their capabilities correctly. .It Fl \-force-pager -Force Ledger to paginate its output. +Force +.Nm +to paginate its output. .It Fl \-forecast-while Ar EXPR Continue forecasting while .Ar VEXPR @@ -556,17 +589,25 @@ Alias for .It Fl \-help 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. This help screen -is also printed if ledger is run without a command. +is also printed if +.Nm +is run without a command. .\".It Fl \-help-calc .\".It Fl \-help-comm .\".It Fl \-help-disp .It Fl \-immediate -Instruct ledger to evaluate calculations immediately rather than lazily. +Instruct +.Nm +to evaluate calculations immediately rather than lazily. .\".It Fl \-import .It Fl \-init-file Ar FILE Pq Fl i Causes .Ar FILE -to be read by ledger before any other ledger file. +to be read by +.Nm +before any other +.Nm +file. This file may not contain any postings, but it may contain option settings. To specify options in the init file, use the same syntax as the command-line, but put each option on its own line. @@ -627,7 +668,7 @@ Suppress any color TTY output. Disables the pager on TTY output. .It Fl \-no-rounding Don't output -.Li Qq +.Qq Li postings. Note that this will cause the running total to often not add up! It's main use is for .Fl \-amount-data Pq Fl j @@ -646,10 +687,14 @@ future using This is a postings predicate that applies after certain transforms have been executed, such as periodic gathering. .It Fl \-options -Display the options in effect for this Ledger invocation, along with +Display the options in effect for this +.Nm +invocation, along with their values and the source of those values. .It Fl \-output Ar FILE Pq Fl o -Redirect the output of ledger to the file defined in +Redirect the output of +.Nm +to the file defined in .Ar FILE . .It Fl \-pager Ar STR Specify the pager program to use as @@ -739,7 +784,9 @@ amounts. Account using only real transactions ignoring virtual and automatic transactions. .It Fl \-recursive-aliases -Causes ledger to try to expand aliases recursively, i.e. try to expand +Causes +.Nm +to try to expand aliases recursively, i.e. try to expand the result of an earlier expansion again, until no more expansions apply. .It Fl \-register-format Ar FMT Define the output format for the @@ -766,18 +813,22 @@ for the .Ic generate command. Used as part of development testing. .It Fl \-script Ar FILE -Execute a ledger script. +Execute a +.Nm +script. .It Fl \-sort Ar EXPR Pq Fl S Sort the register report based on the value expression given to sort. .\".It Fl \-sort-all .It Fl \-sort-xacts Sort the posting within transactions using the given value expression. .It Fl \-start-of-week Ar STR -Tell ledger to use a particular day of the week to start its +Tell +.Nm +to use a particular day of the week to start its .Qq weekly summary. .Ar STR -can be day names, their abbreviations like +can be day names, their abbreviations like .Qq Mon , or the weekday number starting at 0 for Sunday. @@ -845,12 +896,14 @@ Shows the values used by each tag when used in combination with the command. .\".It Fl \-value-expr Ar EXPR .It Fl \-verbose -Print detailed information on the execution of Ledger. +Print detailed information on the execution of +.Nm . .It Fl \-verify Enable additional assertions during run-time. This causes a significant slowdown. When combined with .Fl \-debug Ar CODE -ledger will produce memory trace information. +.Nm +will produce memory trace information. .\".It Fl \-verify-memory .It Fl \-version Print version information and exit. @@ -870,21 +923,31 @@ is that pre-commands ignore the journal data file completely, nor is the user's init file read. .Bl -tag -width -indent .It Ic args / query -Evaluate the given arguments and report how Ledger interprets it against +Evaluate the given arguments and report how +.Nm +interprets it against the following model transaction. .It Ic eval Evaluate the given value expression against the model transaction. .It Ic format -Print details of how ledger uses the given formatting description and +Print details of how +.Nm +uses the given formatting description and apply it against a model transaction. .It Ic parse / expr -Print details of how ledger uses the given value expression description +Print details of how +.Nm +uses the given value expression description and apply it against a model transaction. .It Ic generate -Randomly generates syntactically valid Ledger data from a seed. Used +Randomly generates syntactically valid +.Nm +data from a seed. Used by the GenerateTests harness for development testing. .It Ic period -Evaluate the given period and report how Ledger interprets it. +Evaluate the given period and report how +.Nm +interprets it. .It Ic script .It Ic template Shows the insertion template that the @@ -922,13 +985,13 @@ When you wish to be more explicit, use the OR operator. Reverse the logical meaning of the following term. This can be used with parentheses to great effect: .Pp -.Dl ledger reg food and @Shakee and not dining +.Dl Li ledger reg food and @Shakee and not dining .It \&( Ar term No \&) If you wish to mix OR and AND operators, it is often helpful to surround logical units with parentheses. \fBNOTE\fR: Because of the way some shells interpret parentheses, you should always escape them: .Pp -.Dl ledger bal \e\\\&( assets or liab \e\\\&) and not food +.Dl Li ledger bal \e\\\&( assets or liab \e\\\&) and not food .El .Sh EXPRESSIONS .Bl -tag -width "partial_account" @@ -976,7 +1039,9 @@ Line number where entry for posting ends. .It Sy end_pos Character position where entry for posting ends. .It Sy filename -The name of the ledger data file from whence the posting came. +The name of the +.Nm +data file from whence the posting came. .It Fn format_date date format Return the .Ar date @@ -1028,14 +1093,18 @@ with double-quotes. .Sh ENTRIES .Sh FORMATS .Sh DEBUG COMMANDS -In addition to the regular reporting commands, Ledger also accepts several +In addition to the regular reporting commands, +.Nm +also accepts several debug commands: .Bl -tag -width balance .It Ic args Oo Ar report-query Oc Accepts a .Ar report-query as its argument and displays it back to the user along with a complete -analysis of how Ledger interpreted it. Useful if you want to understand how +analysis of how +.Nm +interpreted it. Useful if you want to understand how report queries are translated into value expressions. .It Ic eval Oo Ar value-expression Oc Evaluates the given @@ -1049,7 +1118,9 @@ and displays an analysis of how it was parsed, and what it would look like applied to a sample transaction. For more on format strings, see the section .Sx FORMATS . .It Ic generate -Generates 50 randomly composed yet valid Ledger transactions. +Generates 50 randomly composed yet valid +.Nm +transactions. .It Ic parse Oo Ar value-expression Oc Parses the given .Ar value-expression @@ -1059,8 +1130,12 @@ more on value expressions, see the section .It Ic python Oo Ar file Oc Invokes a Python interpreter to read the given .Ar file . -What is special about this is that the ledger module is builtin, not read from -disk, so it doesn't require Ledger to be installed anywhere, or the shared +What is special about this is that the +.Nm +module is builtin, not read from +disk, so it doesn't require +.Nm +to be installed anywhere, or the shared library variants to be built. .It Ic reload Used only in the @@ -1072,10 +1147,23 @@ Accepts a and displays information about how it was parsed. See the section on .Sx DRAFTS . .El +.Sh ENVIRONMENT +Every option to +.Nm +may be set using an environment variable. If +an option has a long name for example, +.Fl \-account , +setting the environment variable +.Ev LEDGER_ACCOUNT +will have the same effect as specifying that option on the command-line. +Options on the command-line always take precedence over environment variable +settings, however. .Sh FILES .Bl -tag -width -indent .It Pa ~/.ledgerrc -Your personal ledger initializations. +Your personal +.Nm +initializations. .El .Sh SEE ALSO .Xr beancount 1 , -- cgit v1.2.3 From 6a96a4e68ae3ffe04a21ad5bd01b4ab80fde9639 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Fri, 23 Jan 2015 15:49:59 +0100 Subject: [doc] Use Tn for HTTP and XML in manpage [ci skip] --- doc/ledger.1 | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 257070d0..6e610753 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -249,7 +249,8 @@ and are also accepted. .It Ic server This command requires that Python support be active. If so, it starts up an -HTTP server listening for requests on port 9000. This provides an alternate +.Tn HTTP +server listening for requests on port 9000. This provides an alternate interface to creating and viewing reports. Note that this is very much a work-in-progress, and will not be fully functional until a later version. .It Ic select Oo Ar sql-query Oc @@ -282,7 +283,9 @@ Days since last posting More... .El .It Ic xml Oo Ar report-query Oc -Outputs data relating to the current report in XML format. It includes all +Outputs data relating to the current report in +.Tn XML +format. It includes all accounts and commodities involved in the report, plus the postings and the transactions they are contained in. See the manual for more information. .El -- cgit v1.2.3 From f9f2440451ba8dd0c14e4f8738c2f9b68a86399c Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 24 Jan 2015 08:07:54 +0100 Subject: [doc] Change wording in manpage [ci skip] --- doc/ledger.1 | 87 +++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 51 insertions(+), 36 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 6e610753..a905473a 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -13,8 +13,8 @@ .Nm is a command-line accounting tool based on the power and completeness of double-entry accounting. It is only a reporting tool, which means it never -modifies your data files, but it does offers a large selection of reports, and -different ways to customize them to your liking. +modifies your data files, but it does offer a large selection of reports, and +different ways to customize them to your needs. .Sh COMMANDS .Nm accepts several top-level commands, each of which generates a different @@ -32,7 +32,7 @@ If no command is given, .Nm enters a .Tn REPL , -or command loop, allowing several commands to be executed against the same +or command loop, allowing several commands to be executed on the same dataset without reparsing. .Pp The following is a complete list of reporting commands accepted by @@ -116,13 +116,13 @@ editor, in a series of Lisp forms. This is used by the Emacs mode to process reporting data from .Nm . .It Ic equity Oo Ar report-query Oc -Prints a series of transactions that balance current totals for +Prints a transaction with a series of postings that balance current totals for accounts matching the .Ar report-query in a special account called .Li Equity:Opening Balances . The purpose of this report is to close the books for a prior year, while using -these equity transactions to carry forward those balances. +these equity postings to carry forward those balances. .It Ic org Produces a journal file suitable for use in the Emacs org mode. .It Ic payees Oo Ar report-query Oc @@ -200,7 +200,7 @@ Show postings only for the given Show postings that are related to those that would have been shown. It has the effect of displaying the .Qq other side -of the values. +of the postings. .It Fl \-sort Ar value-expression Pq Fl S Sort postings by evaluating the given .Ar value-expression . @@ -404,7 +404,9 @@ Alias for .It Fl \-columns Ar INT Specify the width of the .Ic register -report in characters. +report in characters. By default +.Nm +will use all available columns in your terminal. .It Fl \-cost Report the cost basis on all posting. Alias for @@ -461,16 +463,14 @@ to parse journals using the European standard comma as decimal separator, vice a period. .It Fl \-depth Ar INT Limit the depth of the account tree. In a balance report, for example, -a -.Fl \-depth 2 -statement will print balances only for account with -two levels, i.e. +.Fl \-depth Ar 2 +will print balances only for accounts with two levels, i.e. .Sy Expenses:Entertainment but not -.Sy Expenses:entertainment:Dining . -This is a display predicate, which -means it only affects display, not the total calculations. -.It Fl \-deviation Pq Fl D +.Sy Expenses:Entertainment:Dining . +This is a display predicate, which means it only affects display, +not the total calculations. +.It Fl \-deviation Report each posting's deviation from the average. It is only meaningful in the register and prices reports. .It Fl \-display Ar EXPR Pq Fl d @@ -522,17 +522,14 @@ Display values in terms of the given The latest available price is used. .\".It Fl \-explicit .It Fl \-file Ar FILE -Read -.Ar FILE -as a -.Nm -file. +Read journal data from +.Ar FILE . .\".It Fl \-full-help .It Fl \-first Ar INT Print the first .Ar INT entries. Opposite of -.Fl \-tail Ar INT . +.Fl \-last Ar INT . Alias for .Fl \-head . .It Fl \-flat @@ -673,7 +670,7 @@ Disables the pager on TTY output. Don't output .Qq Li postings. Note that this will cause the -running total to often not add up! It's main use is for +running total to often not add up! Its main use is for .Fl \-amount-data Pq Fl j and .Fl \-total-data Pq Fl J @@ -683,9 +680,15 @@ Suppress the output of group titles. .It Fl \-no-total Suppress printing the final total line in a balance report. .It Fl \-now Ar DATE -Define the current date in case to you to do calculate in the past or -future using -.Fl \-current . +Use +.Ar DATE +as the current date. This affects the output when using +.Fl \-period , +.Fl \-begin , +.Fl \-end , +or +.Fl \-current +to decide which dates lie in the past or future. .It Fl \-only Ar EXPR This is a postings predicate that applies after certain transforms have been executed, such as periodic gathering. @@ -697,11 +700,12 @@ their values and the source of those values. .It Fl \-output Ar FILE Pq Fl o Redirect the output of .Nm -to the file defined in +to .Ar FILE . .It Fl \-pager Ar STR -Specify the pager program to use as -.Ar STR . +Use +.Ar STR +as the pager program. .It Fl \-payee Sets a value expression for formatting the payee. In the .Ic register @@ -845,8 +849,8 @@ Report only the last entries. Only useful on a register report. Alias for .Fl \-last Ar INT .It Fl \-time-colon -Display the value for a seconds based commodity as real hours and minutes, -thus 8100 seconds will be displayed as 2:15h instead of 2.25h. +Display the value for commodities based on seconds as hours and minutes. +Thus 8100s will be displayed as 2:15h instead of 2.25h. .\".It Fl \-time-report .It Fl \-total Ar EXPR Pq Fl T Define a value expression used to calculate the total in reports. @@ -860,7 +864,9 @@ Enable tracing. The specifies the level of trace desired. .It Fl \-truncate Ar STR Indicates how truncation should happen when the contents of columns -exceed their width. Valid arguments are +exceed their width. Valid arguments for +.Ar STR +are .Ar leading , .Ar middle , and @@ -914,7 +920,7 @@ Print version information and exit. Shorthand for .Fl \-period Ar weekly . .It Fl \-wide Pq Fl w -Assume 132 columns instead of 80. +Assume 132 columns instead of the TTY width. .It Fl \-yearly Pq Fl Y Shorthand for .Fl \-period Ar yearly . @@ -928,8 +934,17 @@ the user's init file read. .It Ic args / query Evaluate the given arguments and report how .Nm -interprets it against -the following model transaction. +interprets it against the following model transaction: +.Bd -literal -offset indent +2004/05/27 Book Store + ; This note applies to all postings. :SecondTag: + Expenses:Books 20 BOOK @ $10 + ; Metadata: Some Value + ; Typed:: $100 + $200 + ; :ExampleTag: + ; Here follows a note describing the posting. + Liabilities:MasterCard $-200.00 +.Ed .It Ic eval Evaluate the given value expression against the model transaction. .It Ic format @@ -955,7 +970,7 @@ interprets it. .It Ic template Shows the insertion template that the .Ic xact -sub-command generates. This is a debugging command. +command generates. This is a debugging command. .El .Sh QUERIES The syntax for reporting queries can get somewhat complex. It is a series of @@ -1154,7 +1169,7 @@ and displays information about how it was parsed. See the section on Every option to .Nm may be set using an environment variable. If -an option has a long name for example, +an option has a long name, for example .Fl \-account , setting the environment variable .Ev LEDGER_ACCOUNT -- cgit v1.2.3 From fccb30004496e2ac2beab1ffe58ffb1ceea5f1be Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 24 Jan 2015 08:09:26 +0100 Subject: [doc] Comment empty items in manpage [ci skip] --- doc/ledger.1 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index a905473a..10dc3c02 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -966,7 +966,7 @@ by the GenerateTests harness for development testing. Evaluate the given period and report how .Nm interprets it. -.It Ic script +.\".It Ic script .It Ic template Shows the insertion template that the .Ic xact @@ -1108,8 +1108,8 @@ with double-quotes. .It Sy virtual .It Sy xact .El -.Sh ENTRIES -.Sh FORMATS +.\".Sh ENTRIES +.\".Sh FORMATS .Sh DEBUG COMMANDS In addition to the regular reporting commands, .Nm -- cgit v1.2.3 From 141e7787f5734c5b6bf3f73ef7f89d203a0485ed Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 24 Jan 2015 08:17:30 +0100 Subject: [doc] Minor typographical changes in manpage [ci skip] --- doc/ledger.1 | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 10dc3c02..38ae6628 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -489,7 +489,7 @@ calculations occur. .It Fl \-dow Group transactions by the days of the week. Alias for -.Fl \-days-of-week +.Fl \-days-of-week . .It Fl \-download Cause quotes to be automagically downloaded, as needed, by running a script named @@ -516,7 +516,7 @@ Related to the command. Gives current account balances in the form of a register report. .\".It Fl \-exact -.It Fl \-exchange Ar COMMODITY Oo , COMM, ... Oc Pq Fl X +.It Fl \-exchange Ar COMMODITY Oo , Ar COMMODITY, ... Oc Pq Fl X Display values in terms of the given .Ar COMMODITY . The latest available price is used. @@ -616,7 +616,9 @@ Use .Ar STR 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 STR to specify the expected amount. +wrong value you can use metadata +.Ar STR +to specify the expected amount. .It Fl \-input-date-format Ar DATEFMT Specify the input date format for journal entries. .It Fl \-invert @@ -650,9 +652,10 @@ Use the latest market value for all commodities. .It Fl \-master-account Ar STR Prepend all account names with .Ar STR -.It Fl \-meta Ar EXPR +.It Fl \-meta Ar STR In the register report, prepend the transaction with the value of the given -.Ar TAG . +tag +.Ar STR . .It Fl \-meta-width Ar INT Specify the width of the Meta column used for the .Fl \-meta Ar TAG @@ -719,7 +722,7 @@ report to Accounts, tags or commodities not previously declared will cause errors. .It Fl \-pending Use only postings that are marked pending. -.It Fl \-percent Pq Fl \b'%' +.It Fl \-percent Pq Fl % Calculate the percentage value of each account in a balance reports. Only works for account that have a single commodity. .It Fl \-period Ar PERIOD Pq Fl p @@ -931,7 +934,7 @@ will work. The difference between a pre-command and a regular command is that pre-commands ignore the journal data file completely, nor is the user's init file read. .Bl -tag -width -indent -.It Ic args / query +.It Ic args No / Ic query Evaluate the given arguments and report how .Nm interprets it against the following model transaction: @@ -952,7 +955,7 @@ Print details of how .Nm uses the given formatting description and apply it against a model transaction. -.It Ic parse / expr +.It Ic parse No / Ic expr Print details of how .Nm uses the given value expression description @@ -983,16 +986,18 @@ Thus, to report the current balance for all assets and liabilities, you would use: .Pp .Dl ledger bal asset liab -.It Ic payee Ar regex Pq \&@ Ns Ar regex +.It Ic payee Ar regex Pq Ic \&@ Ns Ar regex Query on the payee, rather than the account. -.It Ic tag Ar regex Pq \&% Ns Ar regex -.It Ic note Ar regex Pq \&= Ns Ar regex +.It Ic tag Ar regex Pq Ic \&% Ns Ar regex +.It Ic note Ar regex Pq Ic \&= Ns Ar regex Query on anything found in an item's note. -.It Ic code Ar regex Pq \&# Ns Ar regex +.It Ic code Ar regex Pq Ic \&# Ns Ar regex Query on the xact's optional code (which can be any string the user wishes). .It Ar term Cm and Ar term Query terms are joined by an implicit OR operator. You can change this to AND -by using that keyword. For example, to show food expenditures occurring at +by using the +.Cm and +keyword. For example, to show food expenditures occurring at Shakee's Pizza, you could say: .Pp .Dl Li ledger reg food and @Shakee -- cgit v1.2.3 From bc16de720e9bc9429ba9660c354e429750c307fc Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 24 Jan 2015 08:19:30 +0100 Subject: [doc] Improve documentation for option aliases in mapnpage. [ci skip] --- doc/ledger.1 | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 38ae6628..89188c0b 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -192,7 +192,8 @@ Invert the value of amounts shown. .It Fl \-market Pq Fl V Show current market values for all amounts. This is determined in a somewhat magical fashion. It is probably more straightforward to use -.Fl \-exchange Ar commodity Pq Fl X . +.Fl \-exchange +option. .It Fl \-period Ar time-period Pq Fl p Show postings only for the given .Ar time-period . @@ -234,7 +235,7 @@ Group postings by month. Group postings by fiscal quarter. .It Fl \-yearly Pq Fl Y Group postings by year. -.It Fl \-dow +.It Fl \-days-of-week Group postings by the day of the week on which they took place. .It Fl \-subtotal Pq Fl s Group all postings together. This is very similar to the totals shown by the @@ -340,6 +341,10 @@ Set the width in characters of the amount column in the report. .It Fl \-anon Anonymize registry output, mostly for sending in bug reports. +.It Fl \-ansi +Use color if the terminal supports it. +Alias for +.Fl \-color .It Fl \-args-only Ignore init files and environment variables for the .Nm @@ -443,6 +448,10 @@ Specify the width, in characters, of the date column in the .Ic register report. .\".It Fl \-day-break +.It Fl \-days-of-week +Group transactions by the days of the week. +Alias for +.Fl \-dow . .It Fl \-dc Display register or balance in debit/credit format If you use .Fl \-dc @@ -503,6 +512,9 @@ script, implemented in Perl, is provided in the distribution. Downloaded quote price are then appended to the price database, usually specified using the environment variable .Ev LEDGER_PRICE_DB . +.It Fl \-effective +Show auxiliary dates for all calculations. Alias for +.Fl \-aux-date . .It Fl \-empty Pq Fl E Include empty accounts in report. .It Fl \-end Ar DATE Pq Fl e @@ -626,9 +638,9 @@ Change the sign of all reported values. .It Fl \-last Ar INT Report only the last .Ar INT -entries. Only useful on a register -report. -Alias for +entries. Opposite of +.Fl \-first Ar Int . +Only useful on a register report. Alias for .Fl \-tail . .It Fl \-leeway Ar INT Pq Fl Z Alias for @@ -768,7 +780,7 @@ 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. Alias for -.Fl \-leeway Ar INT Pq Fl Z +.Fl \-leeway . .It Fl \-prices-format Ar FMT Set the format for the .Ic prices -- cgit v1.2.3 From 2664343b15489b86750ea2a5e08ae29debd87cf3 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 24 Jan 2015 08:20:26 +0100 Subject: [doc] Fix typo in manpage [ci skip] --- doc/ledger.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 89188c0b..f24c7825 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -584,7 +584,7 @@ can be anything, although most common would be or .Ar commodity . The -.Fn tags +.Fn tag function is also useful here. .It Fl \-group-title-format Ar FMT Set the format for the headers that separate reports section of -- cgit v1.2.3 From eca8ffc016b36429ae925c3442777e2f10525a18 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 24 Jan 2015 08:21:29 +0100 Subject: [doc] Improve examples in manpage [ci skip] --- doc/ledger.1 | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index f24c7825..e6049122 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -208,7 +208,7 @@ Sort postings by evaluating the given Note that a comma-separated list of expressions is allowed, in which case each sorting term is used in order to determine the final ordering. For example, to search by date and then amount, one would use: -.Li -S 'date, amount' . +.Dl ledger reg --sort 'date, amount' .It Fl \-tail Ar number Only show the last .Ar number @@ -257,7 +257,8 @@ work-in-progress, and will not be fully functional until a later version. .It Ic select Oo Ar sql-query Oc List all postings matching the .Ar sql-query . -This command allows to generate SQL-like queries. +This command allows to generate SQL-like queries, e.g.: +.Dl Li ledger select 'date,amount where account==\*qIncome:Salary\*q' .It Ic source Parses a journal file and checks it for errors. .Nm @@ -1026,7 +1027,7 @@ If you wish to mix OR and AND operators, it is often helpful to surround logical units with parentheses. \fBNOTE\fR: Because of the way some shells interpret parentheses, you should always escape them: .Pp -.Dl Li ledger bal \e\\\&( assets or liab \e\\\&) and not food +.Dl Li ledger bal \e( assets or liab \e) and not food .El .Sh EXPRESSIONS .Bl -tag -width "partial_account" -- cgit v1.2.3 From 8c48ca879b895d7df23528889581795db7e2c1f0 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 24 Jan 2015 11:00:03 +0100 Subject: [doc] Change wording in manpage [ci skip] --- doc/ledger.1 | 123 +++++++++++++++++++++++++++++------------------------------ 1 file changed, 61 insertions(+), 62 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index e6049122..b083b2f1 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -35,17 +35,17 @@ enters a or command loop, allowing several commands to be executed on the same dataset without reparsing. .Pp -The following is a complete list of reporting commands accepted by -.Nm : +The following is a complete list of accepted reporting commands: .Bl -tag -width accounts .It Ic accounts Oo Ar report-query Oc -Lists all accounts for postings matching the +List all accounts for postings that match the .Ar report-query . .El .Bl -tag -width balance .It Ic balance Oo Ar report-query Oc -Produces a balance report showing totals for all matching accounts, and -aggregate totals for parents of those accounts. Options most commonly used +Print a balance report showing totals for postings that match +.Ar report-query , +and aggregate totals for parents of those accounts. Options most commonly used with this command are: .Bl -tag -compact -width "--collapse (-n)" .It Fl \-basis Pq Fl B @@ -55,13 +55,13 @@ report which is guaranteed to always balance to zero, when no is specified. Only show totals for the top-most accounts. .It Fl \-empty Pq Fl E -Also show accounts whose total is zero. +Show accounts whose total is zero. .It Fl \-flat Rather than display a hierarchical tree, flatten the report to show subtotals for only accounts matching .Ar report-query . .It Fl \-no-total -Suppress the summary total shown at the bottom of the report (when not zero). +Suppress the summary total shown at the bottom of the report. .El .Pp The synonyms @@ -84,7 +84,7 @@ each account, and the date of the most recent cleared posting in that account. For this accounting to be meaningful, the cleared flag must be set on at least one posting. See the manual for more information. .It Ic commodities Oo Ar report-query Oc -Lists all commodities for postings matching the +List all commodities for postings matching the .Ar report-query . .It Ic convert Reads data from a CSV (comma-separated values) file and generates @@ -110,13 +110,13 @@ The synonym .Ic xact is also accepted. .It Ic emacs Oo Ar query Oc -Outputs posting and transaction data in a format readily consumed by the Emacs +Output posting and transaction data in a format readily consumed by the Emacs editor, in a series of Lisp forms. This is used by the .Pa ledger.el Emacs mode to process reporting data from .Nm . .It Ic equity Oo Ar report-query Oc -Prints a transaction with a series of postings that balance current totals for +Print a transaction with a series of postings that balance current totals for accounts matching the .Ar report-query in a special account called @@ -124,27 +124,27 @@ in a special account called The purpose of this report is to close the books for a prior year, while using these equity postings to carry forward those balances. .It Ic org -Produces a journal file suitable for use in the Emacs org mode. +Produce a journal file suitable for use in the Emacs org mode. .It Ic payees Oo Ar report-query Oc -Lists all payees for postings matching the +List all payees for postings matching the .Ar report-query . .It Ic pricemap -Produces a file which can be used to generate a graph with graphviz showing +Produce a file which can be used to generate a graph with graphviz showing the relationship of commodities in the .Nm file. .It Ic prices Oo Ar report-query Oc -Reports prices for all commodities in postings matching the +Report prices for all commodities in postings matching the .Ar report-query . The prices are reported with the granularity of a single day. .It Ic pricedb Oo Ar report-query Oc -Reports prices for all commodities in postings matching the +Report prices for all commodities in postings matching the .Ar report-query . Prices are reported down to the second, using the same format as the .Pa ~/.pricedb file. .It Ic print Oo Ar report-query Oc -Prints out the full transactions of any matching postings using the same +Print out the full transactions of any matching postings using the same format as they would appear in a data file. This can be used to extract subsets from a .Nm @@ -152,12 +152,17 @@ file to transfer to other files. .It Ic push Oo Ar options Oc In the .Tn REPL , -this command pushes a set of command-line options, so that they will apply to -all subsequent reports. +push a set of command-line +.Ar options , +so that they will apply to all subsequent reports. .It Ic pop In the .Tn REPL , -pops any option settings that have been pushed. +pop any option settings that have been +.Sm off +.Ic push +ed. +.Sm on .It Ic register Oo Ar report-query Oc List all postings matching the .Ar report-query . @@ -258,14 +263,14 @@ work-in-progress, and will not be fully functional until a later version. List all postings matching the .Ar sql-query . This command allows to generate SQL-like queries, e.g.: -.Dl Li ledger select 'date,amount where account==\*qIncome:Salary\*q' +.Dl Li ledger select date,amount from posts where account=~/Income/ .It Ic source -Parses a journal file and checks it for errors. +Parse a journal file and checks it for errors. .Nm will return success if no errors are found. .It Ic stats Oo Ar report-query Oc -Provides summary information about all the postings matching +Provide summary information about all the postings matching .Ar report-query . It provides information such as: .Bl -bullet -offset indent -compact @@ -282,10 +287,10 @@ Uncleared postings .It Days since last posting .It -More... +Posts in the last 7 and 30 days and this month .El .It Ic xml Oo Ar report-query Oc -Outputs data relating to the current report in +Output data relating to the current report in .Tn XML format. It includes all accounts and commodities involved in the report, plus the postings and the @@ -308,14 +313,17 @@ than then the account will be truncated on the left, with no shortening of the account names in order to fit into the desired width. -.It Fl \-account Ar STR +.It Fl \-account Ar EXPR Prepend -.Ar STR +.Ar EXPR to all accounts reported. That is, the option .Fl \-account Ar \*q'Personal'\*q would tack .Ar Personal: -to the beginning of every account reported in a balance report or register report. +and +.Fl \-account Ar \*qtag('VAT')\*q +would tack the value of the VAT tag to the beginning of every account +reported in a balance report or register report. .It Fl \-account-width Ar INT Set the width of the account column in the .Ic register @@ -396,11 +404,7 @@ Specify the format to use for the .Ic cleared report .It Fl \-collapse Pq Fl n -By default -.Nm -prints all accounts in an account tree. With -.Fl \-collapse -it prints only the top level account specified. +Print only the top level accounts. .It Fl \-collapse-if-zero Collapse the account display only if it has a zero balance. .It Fl \-color @@ -614,10 +618,8 @@ Instruct to evaluate calculations immediately rather than lazily. .\".It Fl \-import .It Fl \-init-file Ar FILE Pq Fl i -Causes +Read .Ar FILE -to be read by -.Nm before any other .Nm file. @@ -822,9 +824,7 @@ of the transaction. .It Fl \-related-all Show all postings in a transaction, similar to .Fl \-related -but show -.Em both sides -of each transaction. +but show both sides of each transaction. .\".It Fl \-revalued .\".It Fl \-revalued-only .\".It Fl \-revalued-total Ar EXPR @@ -845,11 +845,11 @@ Sort the register report based on the value expression given to sort. .It Fl \-sort-xacts Sort the posting within transactions using the given value expression. .It Fl \-start-of-week Ar STR -Tell -.Nm -to use a particular day of the week to start its -.Qq weekly -summary. +Use +.Ar STR +as the particular day of the week to start when using the +.Fl \-weekly +option. .Ar STR can be day names, their abbreviations like .Qq Mon , @@ -916,7 +916,7 @@ file to change the default. Perform all calculations without rounding and display results to full precision. .It Fl \-values -Shows the values used by each tag when used in combination with the +Show the values used by each tag when used in combination with the .Ic tags command. .\".It Fl \-value-expr Ar EXPR @@ -1135,36 +1135,35 @@ also accepts several debug commands: .Bl -tag -width balance .It Ic args Oo Ar report-query Oc -Accepts a -.Ar report-query -as its argument and displays it back to the user along with a complete -analysis of how +Display complete analysis of how .Nm -interpreted it. Useful if you want to understand how -report queries are translated into value expressions. +interpreted the given +.Ar report-query . +Useful if you want to understand how report queries are translated into value +expressions. .It Ic eval Oo Ar value-expression Oc -Evaluates the given +Evaluate the given .Ar value-expression and prints the result. For more on value expressions, see the section .Sx EXPRESSIONS . .It Ic format Oo Ar format-string Oc -Accepts a +Display an analysis of how .Ar format-string -and displays an analysis of how it was parsed, and what it would look like -applied to a sample transaction. For more on format strings, see the section +was parsed, and what it would look like applied to a sample transaction. For +more on format strings, see the section .Sx FORMATS . .It Ic generate -Generates 50 randomly composed yet valid +Generate 50 randomly composed yet valid .Nm transactions. .It Ic parse Oo Ar value-expression Oc -Parses the given +Parse the given .Ar value-expression and display an analysis of the expression tree and its evaluated value. For more on value expressions, see the section .Sx EXPRESSIONS . .It Ic python Oo Ar file Oc -Invokes a Python interpreter to read the given +Invoke a Python interpreter to read the given .Ar file . What is special about this is that the .Nm @@ -1174,13 +1173,13 @@ disk, so it doesn't require to be installed anywhere, or the shared library variants to be built. .It Ic reload -Used only in the -.Tn REPL , -it causes an immediate reloading of all data files for the current session. +Reload all data files for the current session immediately. +Can only be used in the +.Tn REPL . .It Ic template Oo Ar draft-template Oc -Accepts a +Display information about how .Ar draft-template -and displays information about how it was parsed. See the section on +was parsed. See the section on .Sx DRAFTS . .El .Sh ENVIRONMENT -- cgit v1.2.3 From 690e6b6cbefdc80e9f361722bc4933958e4ee23f Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 24 Jan 2015 11:43:00 +0100 Subject: [doc] Add documentation of some expressions to manpage. [ci skip] --- doc/ledger.1 | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 69 insertions(+), 11 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index b083b2f1..71eff0e7 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -1035,11 +1035,20 @@ interpret parentheses, you should always escape them: Return the absolute value of the given .Ar value . .It Sy account +Return the posting's account. .It Sy account_base -.It Sy account_amount +Return the base account, i.e. everything after the last account delimiter ':'. +.\".It Sy account_amount .It Sy actual +.\" Is there a difference between real and actual? +Return the true if the transaction is real, i.e not a automated or virtual +transaction, false otherwise. .It Sy amount +Return the amount of the posting. .It Sy amount_expr +Return the calculated amount of the posting according to the +.Fl \-amount +option. .It Fn ansify_if value color bool Render the given .Ar value @@ -1056,7 +1065,12 @@ Line number where entry for posting begins. .It Sy beg_pos Character position where entry for posting begins. .It Sy calculated +.It Fn ceiling value +Return the next integer of +.Ar value +toward +infinity. .It Sy cleared +Return the true if the posting was cleared, false otherwise. .It Sy code Return the transaction code, the string between the parenthesis after the date. .It Sy comment @@ -1083,48 +1097,92 @@ Return the .Ar date as a string using .Ar format . -See +Refer to .Xr strftime 3 for format string details. .It Sy get_at .It Sy has_meta -.It Sy has_tag -.It Sy is_seq -.It Sy join -.It Sy market +.It Fn has_tag tag +Return the true if the posting has metadata named +.Ar tag , +false otherwise. +.It Fn is_seq +.It Fn join value +Replace all newlines in +.Ar value +with +.Li \en . +.It Fn market value datetime +Return the price of +.Ar value +at +.Ar datetime . +Note that +.Ar datetime +must be surrounded by brackets in order to be parsed correctly, e.g. +.Bq 2012/03/23 . .It Sy meta .It Sy note .It Sy null .It Sy options -.It Sy partial_account +A variable that allows access to the values of the given command-line options +using the long option names, e.g. to see whether +.Fl \-daily Pq Fl -D +was given use +.Sy option.daily . +.\" .It Sy partial_account .It Sy payee +Return the payee of the posting. .It Sy pending +Return true if the posting is marked as pending, false otherwise. .It Fn percent value_a value_b Return the percentage of .Ar value_a in relation to .Ar value_b . .It Sy post +.\" A variable scope .It Sy print -.It Sy quantity +.It Fn quantity value +Return the quantity of +.Ar value +for values that have a per-unit cost. .It Fn quoted expression Surround .Ar expression with double-quotes. .It Sy real +.\" Is there a difference between real and actual? +Return the true if the transaction is real, i.e not a automated or virtual +transaction, false otherwise. .It Sy rounded +.It Fn roundto value n +Return +.Ar value +rounded to +.Ar n +digits. Does not affect formatting. .It Sy scrub .It Sy status .It Sy strip -.It Sy subcount -.It Sy tag +.\".It Sy subcount +.It Fn tag name +Return the value of tag named +.Ar name . .It Sy today +Return today’s date. .It Sy total +Return the total of the posting. .It Sy total_expr -.It Sy truncate +Return the calculated total of the posting according to the +.Fl \-total +option. +.It Fn truncate .It Sy uncleared .It Sy virtual +Return the true if the transaction is virtual, e.g automated, false otherwise. .It Sy xact +.\" A variable scope .El .\".Sh ENTRIES .\".Sh FORMATS -- cgit v1.2.3 From 370e44d61e3e3b49e2a498b365f1273e1e7a35ff Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Sat, 24 Jan 2015 12:46:38 +0100 Subject: [doc] Change wording in manpage [ci skip] --- doc/ledger.1 | 42 ++++++++++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 14 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 71eff0e7..c89d415a 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -287,7 +287,11 @@ Uncleared postings .It Days since last posting .It -Posts in the last 7 and 30 days and this month +Posts in the last 7 days +.It +Posts in the last 30 days +.It +Posts this month .El .It Ic xml Oo Ar report-query Oc Output data relating to the current report in @@ -323,7 +327,11 @@ would tack and .Fl \-account Ar \*qtag('VAT')\*q would tack the value of the VAT tag to the beginning of every account -reported in a balance report or register report. +reported in a +.Ic balance +or +.Ic register +report. .It Fl \-account-width Ar INT Set the width of the account column in the .Ic register @@ -412,9 +420,11 @@ Use color if the terminal supports it. Alias for .Fl \-ansi .It Fl \-columns Ar INT -Specify the width of the +Make the .Ic register -report in characters. By default +report +.Ar INT +characters wide. By default .Nm will use all available columns in your terminal. .It Fl \-cost @@ -431,9 +441,11 @@ or .Ic payees commands. .It Fl \-csv-format Ar FMT -Specify the format to use for the +Format .Ic csv report +according to +.Ar FMT . .It Fl \-current Pq Fl c Shorthand for .Fl \-limit Ar "'date <= today'" . @@ -444,9 +456,11 @@ Shorthand for Transform the date of the transaction using .Ar EXPR . .It Fl \-date-format Ar DATEFMT Pq Fl y -Specify the format -.Nm -should use to print dates. +Print dates using +.Ar DATEFMT . +Refer to +.Xr strftime 3 +for details on the format string syntax. .\" .It Fl \-datetime-format Ar FMT .It Fl \-date-width Ar INT Specify the width, in characters, of the date column in the @@ -486,7 +500,9 @@ This is a display predicate, which means it only affects display, not the total calculations. .It Fl \-deviation Report each posting's deviation from the average. It is only meaningful -in the register and prices reports. +in the +.Ic register No and Ic prices +reports. .It Fl \-display Ar EXPR Pq Fl d Display lines that satisfy the expression .Ar EXPR . @@ -613,9 +629,7 @@ is run without a command. .\".It Fl \-help-comm .\".It Fl \-help-disp .It Fl \-immediate -Instruct -.Nm -to evaluate calculations immediately rather than lazily. +Evaluate calculations immediately rather than lazily. .\".It Fl \-import .It Fl \-init-file Ar FILE Pq Fl i Read @@ -638,11 +652,11 @@ to specify the expected amount. Specify the input date format for journal entries. .It Fl \-invert Change the sign of all reported values. -.It Fl \-last Ar INT +.It Fl \-last Ar INT . Report only the last .Ar INT entries. Opposite of -.Fl \-first Ar Int . +.Fl \-first Ar INT . Only useful on a register report. Alias for .Fl \-tail . .It Fl \-leeway Ar INT Pq Fl Z -- cgit v1.2.3 From 19f4f587f0a527056707465bdd9b441a53236711 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Tue, 27 Jan 2015 11:33:39 +0100 Subject: [doc] Add some expression documentation to manpage Comment undocumented expressions, so the are reported by test/CheckManpage.py. --- doc/ledger.1 | 98 ++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 66 insertions(+), 32 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index c89d415a..2374971b 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -466,7 +466,10 @@ for details on the format string syntax. Specify the width, in characters, of the date column in the .Ic register report. -.\".It Fl \-day-break +.It Fl \-day-break +Break up +.Ic register +report of timelog entries that span multiple days by day. .It Fl \-days-of-week Group transactions by the days of the week. Alias for @@ -1055,7 +1058,7 @@ Return the base account, i.e. everything after the last account delimiter ':'. .\".It Sy account_amount .It Sy actual .\" Is there a difference between real and actual? -Return the true if the transaction is real, i.e not a automated or virtual +Return true if the transaction is real, i.e not a automated or virtual transaction, false otherwise. .It Sy amount Return the amount of the posting. @@ -1078,30 +1081,38 @@ for example: Line number where entry for posting begins. .It Sy beg_pos Character position where entry for posting begins. -.It Sy calculated +.\".It Sy calculated .It Fn ceiling value Return the next integer of .Ar value toward +infinity. .It Sy cleared -Return the true if the posting was cleared, false otherwise. +Return true if the posting was cleared, false otherwise. .It Sy code Return the transaction code, the string between the parenthesis after the date. -.It Sy comment -.It Sy commodity -Return the commodity of the posting amount. -.It Sy cost -.It Sy count +.\".It Sy comment +.It Fn commodity value +Return the commodity of +.Ar value +or the posting amount when +.Ar value +was not specified. +.\".It Sy cost +.\".It Sy count .It Sy date Return the date of the posting. -.It Sy depth -.It Sy depth_spacer -.It Sy display_amount -.It Sy display_total +.\".It Sy depth +.\".It Sy depth_spacer +.\".It Sy display_amount +.\".It Sy display_total .It Sy end_line Line number where entry for posting ends. .It Sy end_pos Character position where entry for posting ends. +.It Fn floor value +Return the next integer of +.Ar value +toward -infinity. .It Sy filename The name of the .Nm @@ -1114,13 +1125,13 @@ as a string using Refer to .Xr strftime 3 for format string details. -.It Sy get_at -.It Sy has_meta +.\".It Fn get_at +.\".It Fn has_meta .It Fn has_tag tag -Return the true if the posting has metadata named +Return true if the posting has metadata named .Ar tag , false otherwise. -.It Fn is_seq +.\".It Fn is_seq .It Fn join value Replace all newlines in .Ar value @@ -1135,18 +1146,24 @@ Note that .Ar datetime must be surrounded by brackets in order to be parsed correctly, e.g. .Bq 2012/03/23 . -.It Sy meta -.It Sy note -.It Sy null +.\".It Sy meta +.I.\"t Sy note +.\".It Sy null .It Sy options A variable that allows access to the values of the given command-line options using the long option names, e.g. to see whether -.Fl \-daily Pq Fl -D +.Fl \-daily Pq Fl D was given use .Sy option.daily . .\" .It Sy partial_account .It Sy payee Return the payee of the posting. +.It Fn percent value_a value_b +Return the percentage of +.Ar value_a +in relation to +.Ar value_b +(used as 100%). .It Sy pending Return true if the posting is marked as pending, false otherwise. .It Fn percent value_a value_b @@ -1154,9 +1171,9 @@ Return the percentage of .Ar value_a in relation to .Ar value_b . -.It Sy post +.\".It Sy post .\" A variable scope -.It Sy print +.\".It Sy print .It Fn quantity value Return the quantity of .Ar value @@ -1167,22 +1184,36 @@ Surround with double-quotes. .It Sy real .\" Is there a difference between real and actual? -Return the true if the transaction is real, i.e not a automated or virtual +Return true if the transaction is real, i.e not a automated or virtual transaction, false otherwise. -.It Sy rounded +.\".It Sy rounded .It Fn roundto value n Return .Ar value rounded to .Ar n digits. Does not affect formatting. -.It Sy scrub -.It Sy status -.It Sy strip +.\".It Sy scrub +.\".It Sy status +.\".It Sy strip .\".It Sy subcount .It Fn tag name Return the value of tag named .Ar name . +.\".It Fn to_amount value +.\".It Fn to_balance value +.\".It Fn to_boolean value +.\".It Fn to_date value +.\".It Fn to_datetime value +.It Fn to_int value +Return the integer value for +.Ar value . +.\".It Fn to_mask value +.\".It Fn to_sequence value +.It Fn to_string value +Convert +.Ar value +to a character string. .It Sy today Return today’s date. .It Sy total @@ -1191,11 +1222,14 @@ Return the total of the posting. Return the calculated total of the posting according to the .Fl \-total option. -.It Fn truncate -.It Sy uncleared +.It Fn trim value +Trim leading and trailing whitespace from +.Ar value . +.\".It Fn truncate +.\".It Sy uncleared .It Sy virtual -Return the true if the transaction is virtual, e.g automated, false otherwise. -.It Sy xact +Return true if the transaction is virtual, e.g automated, false otherwise. +.\".It Sy xact .\" A variable scope .El .\".Sh ENTRIES -- cgit v1.2.3 From bc487be14bd1a79cbbedb9203921b357ced79ef7 Mon Sep 17 00:00:00 2001 From: Alexis Hildebrandt Date: Thu, 29 Jan 2015 16:23:48 +0100 Subject: [doc] Improve example for environment variable options [ci skip] --- doc/ledger.1 | 15 +++++++-------- doc/ledger3.texi | 13 ++++++------- 2 files changed, 13 insertions(+), 15 deletions(-) (limited to 'doc/ledger.1') diff --git a/doc/ledger.1 b/doc/ledger.1 index 2374971b..67c24470 100644 --- a/doc/ledger.1 +++ b/doc/ledger.1 @@ -1291,14 +1291,13 @@ was parsed. See the section on .Sh ENVIRONMENT Every option to .Nm -may be set using an environment variable. If -an option has a long name, for example -.Fl \-account , -setting the environment variable -.Ev LEDGER_ACCOUNT -will have the same effect as specifying that option on the command-line. -Options on the command-line always take precedence over environment variable -settings, however. +may be set using an environment variable if the option has a long name. +For example setting the environment variable +.Ev LEDGER_DATE_FORMAT="%d.%m.%Y' +will have the same effect as specifying +.Fl \-date-format Ar '%d.%m.%Y' +on the command-line. Options on the command-line always take precedence over +environment variable settings, however. .Sh FILES .Bl -tag -width -indent .It Pa ~/.ledgerrc diff --git a/doc/ledger3.texi b/doc/ledger3.texi index e199181d..08d0d2db 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -7442,15 +7442,14 @@ BTC:USD}. @node Environment variables, , Commodity reporting, Detailed Option Description @subsection Environment variables -Every option to ledger may be set using an environment variable. If -an option has a long name, for example @option{--account}, setting the -environment variable @env{LEDGER_ACCOUNT} will have the same -effect as specifying that option on the command-line. Options on the -command-line always take precedence over environment variable -settings, however. +Every option to ledger may be set using an environment variable if the +option has a long name. For example setting the environment variable +@samp{@env{LEDGER_DATE_FORMAT}="%d.%m.%Y"} will have the same effect as specifying +@samp{@option{--date-format} '%d.%m.%Y'} on the command-line. Options on the +command-line always take precedence over environment variable settings, however. Note that you may also permanently specify option values by placing -option settings in the file @file{~/.ledgerrc}, for example: +option settings in the file @file{~/.ledgerrc} one option per line, for example: @smallexample --pager /bin/cat -- cgit v1.2.3