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

[doc] Replace .Nm with .Ic where appropriate

Browse source 
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]
This commit is contained in:
Alexis Hildebrandt 2015-01-23 08:33:49 +01:00
parent 2d33ddf12f
commit 91862091c0
1 changed files with 82 additions and 78 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

160
doc/ledger.1
View file

@ -33,12 +33,12 @@ dataset without reparsing.
.Pp .Pp
The following is a complete list of reporting commands accepted by Ledger: The following is a complete list of reporting commands accepted by Ledger:
.Bl -tag -width accounts .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 Lists all accounts for postings matching the
.Ar report-query . .Ar report-query .
.El .El
.Bl -tag -width balance .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 Produces a balance report showing totals for all matching accounts, and
aggregate totals for parents of those accounts. Options most commonly used aggregate totals for parents of those accounts. Options most commonly used
with this command are: with this command are:
@ -60,11 +60,11 @@ Suppress the summary total shown at the bottom of the report (when not zero).
.El .El
.Pp .Pp
The synonyms The synonyms
.Nm bal .Ic bal
and and
.Nm b .Ic b
are also accepted. 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 A special balance report which includes three extra columns: the amount
budgeted during the reporting period, how spending differed from the budget, budgeted during the reporting period, how spending differed from the budget,
and the percentage of budget spent (exceeds 100% if you go over 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 periodic transactions
.Dc .Dc
to be defined in your data file(s). See the manual for more information. 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 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. 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 For this accounting to be meaningful, the cleared flag must be set on at least
one posting. See the manual for more information. 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 Lists all commodities for postings matching the
.Ar report-query . .Ar report-query .
.It Nm convert .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 Ledger
transactions. transactions.
.It Nm csv Oo Ar report-query Oc .It Ic csv Oo Ar report-query Oc
Report of postings matching the Report of postings matching the
.Ar report-query .Ar report-query
in CSV format (comma-separated values). Useful for exporting data to a in CSV format (comma-separated values). Useful for exporting data to a
spreadsheet for further analysis or charting. 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 Generate and display a new, properly formatted Ledger transaction by comparing
the the
.Ar entry-template .Ar entry-template
@ -99,14 +99,14 @@ section
.Sx ENTRIES . .Sx ENTRIES .
.Pp .Pp
The synonym The synonym
.Nm xact .Ic xact
is also accepted. 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 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 editor, in a series of Lisp forms. This is used by the
.Li ledger.el .Li ledger.el
Emacs mode to process reporting data from Ledger. 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 Prints a series of transactions that balance current totals for
accounts matching the accounts matching the
.Ar report-query .Ar report-query
@ -114,38 +114,38 @@ in a special account called
.Li Equity:Opening Balances . .Li Equity:Opening Balances .
The purpose of this report is to close the books for a prior year, while using 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 transactions to carry forward those balances.
.It Nm org .It Ic org
Produces a journal file suitable for use in the Emacs org mode. 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 Lists all payees for postings matching the
.Ar report-query . .Ar report-query .
.It Nm pricemap .It Ic pricemap
Produces a file which can be used to generate a graph with graphviz showing 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 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 Reports prices for all commodities in postings matching the
.Ar report-query . .Ar report-query .
The prices are reported with the granularity of a single day. 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 Reports prices for all commodities in postings matching the
.Ar report-query . .Ar report-query .
Prices are reported down to the second, using the same format as the Prices are reported down to the second, using the same format as the
.Li ~/.pricedb .Li ~/.pricedb
file. 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 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 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 Ledger file to transfer to other files.
.It Nm push Oo Ar options Oc .It Ic push Oo Ar options Oc
In the In the
.Tn REPL , .Tn REPL ,
this command pushes a set of command-line options, so that they will apply to this command pushes a set of command-line options, so that they will apply to
all subsequent reports. all subsequent reports.
.It Nm pop .It Ic pop
In the In the
.Tn REPL , .Tn REPL ,
pops any option settings that have been pushed. 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 List all postings matching the
.Ar report-query . .Ar report-query .
This is one of the most common commands, and can be used to provide a variety 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 , .Ar commodity ,
if a price conversion rate can be determined. Rates are always displayed 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 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 report is a historical value report. For current values, it may be preferable
to use the to use the
.Nm balance .Ic balance
report. report.
.It Fl \-gain Pq Fl G .It Fl \-gain Pq Fl G
Show any gains (or losses) in commodity values over time. 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. Group postings by the day of the week on which they took place.
.It Fl \-subtotal Pq Fl s .It Fl \-subtotal Pq Fl s
Group all postings together. This is very similar to the totals shown by the Group all postings together. This is very similar to the totals shown by the
.Nm balance .Ic balance
report. report.
.El .El
.Pp .Pp
The synonyms The synonyms
.Nm reg .Ic reg
and and
.Nm r .Ic r
are also accepted. are also accepted.
.It Nm server .It Ic server
This command requires that Python support be active. If so, it starts up an 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 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 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. 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 List all postings matching the
.Ar sql-query . .Ar sql-query .
This command allows to generate SQL-like queries. 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 Parses a journal file and checks it for errors. Ledger will return success
if no errors are found. 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 Provides summary information about all the postings matching
.Ar report-query . .Ar report-query .
It provides information such as: It provides information such as:
@ -268,7 +268,7 @@ Days since last posting
.It .It
More... More...
.El .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 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 accounts and commodities involved in the report, plus the postings and the
transactions they are contained in. See the manual for more information. 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. to the beginning of every account reported in a balance report or register report.
.It Fl \-account-width Ar INT .It Fl \-account-width Ar INT
Set the width of the account column in the Set the width of the account column in the
.Nm register .Ic register
report report
to to
.Ar INT .Ar INT
@ -320,7 +320,7 @@ On a register report print only the dates and amount of postings.
Useful for graphing and spreadsheet applications. Useful for graphing and spreadsheet applications.
.It Fl \-amount-width Ar INT .It Fl \-amount-width Ar INT
Set the width in characters of the amount column in the Set the width in characters of the amount column in the
.Nm register .Ic register
report. report.
.It Fl \-anon .It Fl \-anon
Anonymize registry output, mostly for sending in bug reports. 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. running totals.
.It Fl \-balance-format Ar FMT .It Fl \-balance-format Ar FMT
Specify the format to use for the Specify the format to use for the
.Nm balance .Ic balance
report. report.
.\".It Fl \-base .\".It Fl \-base
.It Fl \-basis Pq Fl B .It Fl \-basis Pq Fl B
@ -351,12 +351,13 @@ that date will be ignored.
.It Fl \-bold-if Ar EXPR .It Fl \-bold-if Ar EXPR
Print the entire line in bold if the given value expression is true. Print the entire line in bold if the given value expression is true.
.It Fl \-budget .It Fl \-budget
Only display budgeted items. In a register report this Only display budgeted items. In a
displays transaction in the budget, in a balance report this displays .Ic register
accounts in the budget. report this displays transaction in the budget, in a balance report this
displays accounts in the budget.
.It Fl \-budget-format Ar FMT .It Fl \-budget-format Ar FMT
Specify the format to use for the Specify the format to use for the
.Nm budget .Ic budget
report. report.
.It Fl \-by-payee Pq Fl P .It Fl \-by-payee Pq Fl P
Group postings in the register report by common payee names. Group postings in the register report by common payee names.
@ -368,7 +369,7 @@ commodities and tags.
Display only cleared postings. Display only cleared postings.
.It Fl \-cleared-format Ar FMT .It Fl \-cleared-format Ar FMT
Specify the format to use for the Specify the format to use for the
.Nm cleared .Ic cleared
report report
.It Fl \-collapse Pq Fl n .It Fl \-collapse Pq Fl n
By default ledger prints all accounts in an account tree. With By default ledger prints all accounts in an account tree. With
@ -382,7 +383,7 @@ Alias for
.Fl \-ansi .Fl \-ansi
.It Fl \-columns Ar INT .It Fl \-columns Ar INT
Specify the width of the Specify the width of the
.Nm register .Ic register
report in characters. report in characters.
.It Fl \-cost .It Fl \-cost
Report the cost basis on all posting. Report the cost basis on all posting.
@ -390,14 +391,14 @@ Alias for
.Fl \-basis . .Fl \-basis .
.It Fl \-count .It Fl \-count
Direct ledger to report the number of items when appended to the Direct ledger to report the number of items when appended to the
.Nm commodities , .Ic commodities ,
.Nm accounts .Ic accounts
or or
.Nm payees .Ic payees
commands. commands.
.It Fl \-csv-format Ar FMT .It Fl \-csv-format Ar FMT
Specify the format to use for the Specify the format to use for the
.Nm csv .Ic csv
report report
.It Fl \-current Pq Fl c .It Fl \-current Pq Fl c
Shorthand for Shorthand for
@ -413,14 +414,17 @@ Specify the format ledger should use to print dates.
.\" .It Fl \-datetime-format Ar FMT .\" .It Fl \-datetime-format Ar FMT
.It Fl \-date-width Ar INT .It Fl \-date-width Ar INT
Specify the width, in characters, of the date column in the Specify the width, in characters, of the date column in the
.Nm register .Ic register
report. report.
.\".It Fl \-day-break .\".It Fl \-day-break
.It Fl \-dc .It Fl \-dc
Display register or balance in debit/credit format If you use Display register or balance in debit/credit format If you use
.Fl \-dc .Fl \-dc
with either the register (reg) or balance (bal) commands, with either the
you will now get separate columns for debits and credits. .Ic register
or
.Ic balance
commands, you will now get separate columns for debits and credits.
.It Fl \-debug Ar STR .It Fl \-debug Ar STR
If Ledger has been built with debug options this will provide extra If Ledger has been built with debug options this will provide extra
data during the run. data during the run.
@ -479,7 +483,7 @@ for a transaction to be considered in the
report. report.
.It Fl \-equity .It Fl \-equity
Related to the Related to the
.Nm equity .Ic equity
command. Gives current account balances in the form of a register command. Gives current account balances in the form of a register
report. report.
.\".It Fl \-exact .\".It Fl \-exact
@ -530,7 +534,7 @@ transactions) in the report, in cases where you normally wouldn't want
them. them.
.It Fl \-group-by Ar EXPR .It Fl \-group-by Ar EXPR
Group transaction together in the Group transaction together in the
.Nm register .Ic register
report. report.
.Ar EXPR .Ar EXPR
can be anything, although most common would be can be anything, although most common would be
@ -655,7 +659,7 @@ Specify the pager program to use as
.Ar STR . .Ar STR .
.It Fl \-payee .It Fl \-payee
Sets a value expression for formatting the payee. In the Sets a value expression for formatting the payee. In the
.Nm register .Ic register
report this prevents the second entry from having report this prevents the second entry from having
a date and payee for each transaction. a date and payee for each transaction.
.It Fl \-payee-width Ar INT .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 .It Fl \-period Ar PERIOD Pq Fl p
Define a period expression that sets the time period during which Define a period expression that sets the time period during which
transactions are to be accounted. For a transactions are to be accounted. For a
.Nm register .Ic register
report only report only
the transactions that satisfy the period expression with be displayed. the transactions that satisfy the period expression with be displayed.
For a balance report only those transactions will be accounted in the 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 .Fl \-leeway Ar INT Pq Fl Z
.It Fl \-prices-format Ar FMT .It Fl \-prices-format Ar FMT
Set the format for the Set the format for the
.Nm prices .Ic prices
report. report.
.It Fl \-pricedb-format Ar FMT .It Fl \-pricedb-format Ar FMT
Set the format expected for the historical price file. Set the format expected for the historical price file.
@ -729,7 +733,7 @@ Shorthand for
.Fl \-period Ar "quarterly" . .Fl \-period Ar "quarterly" .
.It Fl \-raw .It Fl \-raw
In the In the
.Nm print .Ic print
report, show transactions using the exact same syntax as report, show transactions using the exact same syntax as
specified by the user in their data file. Don't do any massaging or specified by the user in their data file. Don't do any massaging or
interpreting. Can be useful for minor cleanups, like just aligning 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. the result of an earlier expansion again, until no more expansions apply.
.It Fl \-register-format Ar FMT .It Fl \-register-format Ar FMT
Define the output format for the Define the output format for the
.Nm register .Ic register
report. report.
.It Fl \-related Pq Fl r .It Fl \-related Pq Fl r
In a register report show the related account. This is the other In a register report show the related account. This is the other
@ -762,7 +766,7 @@ of each transaction.
Set the random seed to Set the random seed to
.Ar INT .Ar INT
for the for the
.Nm generate .Ic generate
command. Used as part of development testing. command. Used as part of development testing.
.It Fl \-script Ar FILE .It Fl \-script Ar FILE
Execute a ledger script. Execute a ledger script.
@ -835,7 +839,7 @@ Perform all calculations without rounding and display results to full
precision. precision.
.It Fl \-values .It Fl \-values
Shows the values used by each tag when used in combination with the Shows the values used by each tag when used in combination with the
.Nm tags .Ic tags
command. command.
.\".It Fl \-value-expr Ar EXPR .\".It Fl \-value-expr Ar EXPR
.It Fl \-verbose .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 is that pre-commands ignore the journal data file completely, nor is
the user's init file read. the user's init file read.
.Bl -tag -width -indent .Bl -tag -width -indent
.It Nm args / query .It Ic args / query
Evaluate the given arguments and report how Ledger interprets it against Evaluate the given arguments and report how Ledger interprets it against
the following model transaction. the following model transaction.
.It Nm eval .It Ic eval
Evaluate the given value expression against the model transaction. 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 Print details of how ledger uses the given formatting description and
apply it against a model transaction. 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 Print details of how ledger uses the given value expression description
and apply it against a model transaction. and apply it against a model transaction.
.It Nm generate .It Ic generate
Randomly generates syntactically valid Ledger data from a seed. Used Randomly generates syntactically valid Ledger data from a seed. Used
by the GenerateTests harness for development testing. by the GenerateTests harness for development testing.
.It Nm period .It Ic period
Evaluate the given period and report how Ledger interprets it. Evaluate the given period and report how Ledger interprets it.
.It Nm script .It Ic script
.It Nm template .It Ic template
Shows the insertion template that the Shows the insertion template that the
.Nm xact .Ic xact
sub-command generates. This is a debugging command. sub-command generates. This is a debugging command.
.El .El
.Sh QUERIES .Sh QUERIES
@ -896,12 +900,12 @@ Thus, to report the current balance for all assets and liabilities, you would
use: use:
.Pp .Pp
.Dl ledger bal asset liab .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. Query on the payee, rather than the account.
.It Nm tag Ar regex Pq \&% Ns Ar regex .It Ic tag Ar regex Pq \&% Ns Ar regex
.It Nm note Ar regex Pq \&= Ns Ar regex .It Ic note Ar regex Pq \&= Ns Ar regex
Query on anything found in an item's note. 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). 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 Nm and Ar term
Query terms are joined by an implicit OR operator. You can change this to AND 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 In addition to the regular reporting commands, Ledger also accepts several
debug commands: debug commands:
.Bl -tag -width balance .Bl -tag -width balance
.It Nm args Oo Ar report-query Oc .It Ic args Oo Ar report-query Oc
Accepts a Accepts a
.Ar report-query .Ar report-query
as its argument and displays it back to the user along with a complete 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 Ledger interpreted it. Useful if you want to understand how
report queries are translated into value expressions. 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 Evaluates the given
.Ar value-expression .Ar value-expression
and prints the result. For more on value expressions, see the section and prints the result. For more on value expressions, see the section
.Sx EXPRESSIONS . .Sx EXPRESSIONS .
.It Nm format Oo Ar format-string Oc .It Ic format Oo Ar format-string Oc
Accepts a Accepts a
.Ar format-string .Ar format-string
and displays an analysis of how it was parsed, and what it would look like 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 applied to a sample transaction. For more on format strings, see the section
.Sx FORMATS . .Sx FORMATS .
.It Nm generate .It Ic generate
Generates 50 randomly composed yet valid Ledger transactions. 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 Parses the given
.Ar value-expression .Ar value-expression
and display an analysis of the expression tree and its evaluated value. For and display an analysis of the expression tree and its evaluated value. For
more on value expressions, see the section more on value expressions, see the section
.Sx EXPRESSIONS . .Sx EXPRESSIONS .
.It Nm python Oo Ar file Oc .It Ic python Oo Ar file Oc
Invokes a Python interpreter to read the given Invokes a Python interpreter to read the given
.Ar file . .Ar file .
What is special about this is that the ledger module is builtin, not read from 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 disk, so it doesn't require Ledger to be installed anywhere, or the shared
library variants to be built. library variants to be built.
.It Nm reload .It Ic reload
Used only in the Used only in the
.Tn REPL , .Tn REPL ,
it causes an immediate reloading of all data files for the current session. 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 Accepts a
.Ar draft-template .Ar draft-template
and displays information about how it was parsed. See the section on and displays information about how it was parsed. See the section on