diff options
author | thdox <thdox@free.fr> | 2013-05-05 22:37:39 +0200 |
---|---|---|
committer | thdox <thdox@free.fr> | 2013-05-20 23:23:43 +0200 |
commit | 1e1275d25b847e716b74ea0579600c3cbaa1170a (patch) | |
tree | 9f52eaedce9d626d1c6095d69d27679b931f68d8 /doc | |
parent | 3e95bdd43fd82b40c6cc7af4cf01ebbddd2b4357 (diff) | |
download | fork-ledger-1e1275d25b847e716b74ea0579600c3cbaa1170a.tar.gz fork-ledger-1e1275d25b847e716b74ea0579600c3cbaa1170a.tar.bz2 fork-ledger-1e1275d25b847e716b74ea0579600c3cbaa1170a.zip |
Insert some spacing
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ledger-mode.texi | 71 | ||||
-rw-r--r-- | doc/ledger3.texi | 248 |
2 files changed, 286 insertions, 33 deletions
diff --git a/doc/ledger-mode.texi b/doc/ledger-mode.texi index aba860f5..3e87d090 100644 --- a/doc/ledger-mode.texi +++ b/doc/ledger-mode.texi @@ -8,6 +8,7 @@ @c needs. @copying + Copyright @copyright{} 2013, Craig Earls. All rights reserved. Redistribution and use in source and binary forms, with or without @@ -15,17 +16,21 @@ modification, are permitted provided that the following conditions are met: @itemize + @item Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + @item Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + @item Neither the name of New Artisans LLC nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + @end itemize THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS @@ -39,6 +44,7 @@ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + @end copying @dircategory Major Modes @@ -333,21 +339,25 @@ states unless specifically instructed to use them. Ledger-mode assigns some additional meaning to the states: @itemize + @item Uncleared. No state. This is equivalent to sticking a check in the mail. It has been obligated, but not been cashed by the recipient. It could also apply to credit/debit card transactions that have not been cleared into your account balance. You bank may call these transactions ``pending'', but Ledger-mode uses a slightly different meaning. + @item Pending. Ledger-mode's reconciliation function see pending transactions as an intermediate step in reconciling an account. When doing a reconciliation (@pxref{Reconciliation}), marking a transaction as pending means that you have seen the transaction finally recorded by the recipient, but you have not completely reconciled the account. + @item Cleared. The transaction has been completely recognized by all parties to the transaction. + @end itemize @kindex C-c C-e @@ -433,18 +443,24 @@ transactions. For details of the regular expression syntax, see using the @file{demo.ledger} are given here: @table @samp + @item Groceries Show only transactions that have a posting to the @samp{Groceries} account. + @item ^2011/01 Show only transactions occurring in January of 2011. + @item ^2011/.*/25 Show only transactions occurring on the 25th of the month in 2011. + @item auto Show only transactions with payees or accounts or comments containing. @samp{auto} + @item harley$ Show only transactions with any line ending with @samp{harley}. + @end table To show back all transactions simply invoke @samp{Narrow to Regex} or @@ -604,16 +620,21 @@ Typing @kbd{C-c C-o C-r} or using menu @samp{Ledger Run Report} prompt for the name of a saved report. The built-in reports are: @table @var + @item bal Produce a balance reports of all accounts. + @item reg Produce a register report of all transactions. + @item payee Prompt for a payee, then produce a register report of all transactions involving that payee. + @item account Prompt for an account, then produce a register report of all transactions involving that account. + @end table @node Adding and Editing Reports, Reversing Report Order, Running Basic Reports, The Report Buffer @@ -662,16 +683,20 @@ expansion to prompt the user for the account to use. There are four variables that can be expanded to run a report: @table @var + @item ledger-file Returns the file to be operated on. + @item payee Prompts for a payee. + @item account Prompt for an account. @c FIXME : is it 'value' or 'tag' for '@item value' just below? @item value Prompt for a tag value. + @end table You can use these expansion values in your ledger report commands. For @@ -751,14 +776,18 @@ for Ledger under the data options. Alternately you can choose @cindex customization, ledger-mode @ftable @option + @item ledger-occur-use-face-shown If non-nil, use a custom face for transactions shown in @option{ledger-occur} mode using @option{ledger-occur-xact-face}. + @item ledger-clear-whole-transactions If non-nil, clear whole transactions, not individual postings. + @item ledger-highlight-xact-under-point If non-nil, highlight transaction under point using @option{ledger-font-highlight-face}. + @end ftable @node Ledger Reconcile Customization Group, Ledger Report Customization Group, Ledger Customization Group, Customization Variables @@ -766,23 +795,30 @@ If non-nil, highlight transaction under point using @cindex customization, reconcile @ftable @option + @item ledger-reconcile-default-commodity The default commodity for use in target calculations in ledger reconcile. Defaults to @samp{$} (USD). + @item ledger-recon-buffer-name Name to use for reconciliation buffer. Defaults to @file{*Reconcile*}. + @item ledger-narrow-on-reconcile If non-nil, limit transactions shown in main buffer to those matching the reconcile regex. + @item ledger-buffer-tracks-reconcile-buffer If non-nil, then when the cursor is moved to a new transaction in the reconcile window. + @item ledger-reconcile-force-window-bottom If non-nil, make the reconcile window appear along the bottom of the register window and resize. + @item ledger-reconcile-toggle-to-pending If non-nil, then toggle between uncleared and pending @samp{!}. If false toggle between uncleared and cleared @samp{*}. + @end ftable @node Ledger Report Customization Group, Ledger Faces Customization Group, Ledger Reconcile Customization Group, Customization Variables @@ -790,11 +826,14 @@ false toggle between uncleared and cleared @samp{*}. @cindex customization, report @ftable @option + @item ledger-reports Definition of reports to run. + @item ledger-report-format-specifiers An alist mapping ledger report format specifiers to implementing functions. + @end ftable @node Ledger Faces Customization Group, Ledger Post Customization Group, Ledger Report Customization Group, Customization Variables @@ -804,38 +843,55 @@ functions. Ledger Faces: Ledger-mode highlighting @ftable @option + @item ledger-font-uncleared-face Default face for Ledger. + @item ledger-font-cleared-face Default face for cleared @samp{*} transactions. + @item ledger-font-highlight-face Default face for transaction under point. + @item ledger-font-pending-face Default face for pending @samp{!} transactions. + @item ledger-font-other-face Default face for other transactions. + @item ledger-font-posting-account-face Face for Ledger accounts. + @item ledger-font-posting-account-cleared-face Face for cleared Ledger accounts. + @item ledger-font-posting-account-pending-face Face for Ledger pending accounts. + @item ledger-font-posting-amount-face Face for Ledger amounts. + @item ledger-occur-narrowed-face Default face for Ledger occur mode hidden transactions. + @item ledger-occur-xact-face Default face for Ledger occur mode shown transactions. + @item ledger-font-comment-face Face for Ledger comments. + @item ledger-font-reconciler-uncleared-face Default face for uncleared transactions in the reconcile window. + @item ledger-font-reconciler-cleared-face Default face for cleared @samp{*} transactions in the reconcile window. + @item ledger-font-reconciler-pending-face Default face for pending @samp{!} transactions in the reconcile window. + @item ledger-font-report-clickable-face FIXME + @end ftable @node Ledger Post Customization Group, Ledger Exec Customization Group, Ledger Faces Customization Group, Customization Variables @@ -845,16 +901,22 @@ FIXME Ledger Post: @ftable @option + @item ledger-post-auto-adjust-amounts If non-nil, then automatically align amounts to column specified in @option{ledger-post-amount-alignment-column}. + @item ledger-post-amount-alignment-column The column Ledger-mode uses to align amounts. + @item ledger-default-acct-transaction-indent Default indentation for account transactions in an entry. + @item ledger-post-use-completion-engine Which completion engine to use: @var{iswitchb}, @var{ido}, or built-in. + @item ledger-post-use-ido + @end ftable @node Ledger Exec Customization Group, Ledger Test Customization Group, Ledger Post Customization Group, Customization Variables @@ -864,10 +926,13 @@ Which completion engine to use: @var{iswitchb}, @var{ido}, or built-in. Ledger Exec: Interface to the Ledger command-line accounting program. @ftable @option + @item ledger-binary-path Path to the ledger executable. + @item ledger-init-file-name Location of the ledger initialization file. nil if you don't have one. + @end ftable @node Ledger Test Customization Group, Ledger Texi Customization Group, Ledger Exec Customization Group, Customization Variables @@ -875,10 +940,13 @@ Location of the ledger initialization file. nil if you don't have one. @cindex customization, test @ftable @option + @item ledger-source-directory Directory where the Ledger sources are located. + @item ledger-test-binary Directory where the debug binary. + @end ftable @node Ledger Texi Customization Group, , Ledger Test Customization Group, Customization Variables @@ -886,12 +954,15 @@ Directory where the debug binary. @cindex customization, texi @ftable @option + @item ledger-texi-sample-doc-path Location for sample data to be used in texi tests, defaults to @file{~/ledger/doc/sample.dat}. + @item ledger-texi-normalization-args texi normalization for producing ledger output, defaults to @samp{--args-only --columns 80}. + @end ftable @node Generating Ledger Regression Tests, Embedding Example results in Ledger Documentation, Customizing Ledger-mode, Top diff --git a/doc/ledger3.texi b/doc/ledger3.texi index 499561cd..2ca34144 100644 --- a/doc/ledger3.texi +++ b/doc/ledger3.texi @@ -16,17 +16,21 @@ modification, are permitted provided that the following conditions are met: @itemize + @item Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + @item Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + @item Neither the name of New Artisans LLC nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + @end itemize THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS @@ -1653,6 +1657,7 @@ scheme. As far as valuation goes, it's shorthand for writing A valuation function receives three arguments: @table @code + @item source A string identifying the commodity whose price is being asked for (example: @samp{EUR}) @@ -1664,6 +1669,7 @@ The reference date the price should be relative. A string identifying the ``target'' commodity, or the commodity the returned price should be in. This argument is null if @code{--market} was used instead of @code{--exchange @var{COMMODITY}}. + @end table The valuation function should return an amount. If you've written @@ -1833,6 +1839,7 @@ The initial character of each line determines what the line means, and how it should be interpreted. Allowable initial characters are: @table @code + @item NUMBER A line beginning with a number denotes a transaction. It may be followed by any number of lines, each beginning with white-space, to @@ -1902,6 +1909,7 @@ If the semi colon is indented and occurs inside a transaction, it is parsed as a persistent note for its preceding category. These notes or tags can be used to augment the reporting and filtering capabilities of Ledger. + @end table @node Command Directives, , Transaction and Comments, Journal Format @@ -1910,6 +1918,7 @@ Ledger. @findex --pedantic @table @code + @item beginning of line Command directives must occur at the beginning of a line. Use of @samp{!} and @samp{@@} is deprecated. @@ -1997,7 +2006,6 @@ alias Checking=Assets:Credit Union:Joint Checking Account 2011/11/28 YummyPalace Dining $10.00 Checking - @end smallexample The aliases are only in effect for transactions read in after the alias @@ -2034,7 +2042,6 @@ bucket Assets:Checking 2011/12/01 Sale Assets:Checking:Business $ 30.00 - @end smallexample @item capture @@ -2284,6 +2291,7 @@ The following single letter commands may be at the beginning of a line alone, for backwards compatibility with older Ledger versions. @table @code + @item A See @code{bucket} @@ -2328,6 +2336,7 @@ C 1.00 Kb = 1024 bytes These four relate to timeclock support, which permits Ledger to read timelog files. See the timeclock's documentation for more info on the syntax of its timelog files. + @end table @node Converting from other formats, Archiving Previous Years, Journal Format, Keeping a Journal @@ -3243,26 +3252,25 @@ a function by using a lambda expression taking three arguments: The arguments passed to these functions have the following meaning: @itemize -@item source - The source commodity string, or an amount object. If it is - a string, the return value must be an amount representing the - price of the commodity identified by that string (example: - @samp{$}). If it is an amount, return the value of that - amount as a new amount (usually calculated as commodity price - times source amount). - -@item date - The date to use for determining the value. If null, it means - no date was specified, which can mean whatever you want it to - mean. - -@item target - If not null, a string representing the desired target - commodity that the commodity price, or repriced amount, should - be valued in. Note that this string can be a comma-separated - list, and that some or all of the commodities in that list may - be suffixed with an exclamation mark, to indicate what is - being desired. + +@item source +The source commodity string, or an amount object. If it is a string, +the return value must be an amount representing the price of the +commodity identified by that string (example: @samp{$}). If it is an +amount, return the value of that amount as a new amount (usually +calculated as commodity price times source amount). + +@item date +The date to use for determining the value. If null, it means no date +was specified, which can mean whatever you want it to mean. + +@item target +If not null, a string representing the desired target commodity that the +commodity price, or repriced amount, should be valued in. Note that +this string can be a comma-separated list, and that some or all of the +commodities in that list may be suffixed with an exclamation mark, to +indicate what is being desired. + @end itemize In most cases, it is simplest to either use explicit amounts in your @@ -3485,6 +3493,7 @@ Ledger you can control every aspect of the timing of a transaction. Say you're in business. If you bill a customer, you can enter something like + @cindex effective date of invoice @smallexample @@ -4327,19 +4336,20 @@ include Ledger entries within an org file. There are three ways (at least) in which these can be included: @enumerate + @item - place all Ledger entries within one source block and execute - this block with different arguments to generate the - appropriate reports; +place all Ledger entries within one source block and execute this block +with different arguments to generate the appropriate reports; + @item - place Ledger entries in more than one source block and use the - noweb literary programming approach, supported by babel, to - combine these into one block elsewhere in the file for - processing by Ledger; and, +place Ledger entries in more than one source block and use the noweb +literary programming approach, supported by babel, to combine these into +one block elsewhere in the file for processing by Ledger; and, + @item - place Ledger entries in different source blocks and use - tangling to generate a Ledger file which you can subsequently - process using Ledger directly. +place Ledger entries in different source blocks and use tangling to +generate a Ledger file which you can subsequently process using Ledger +directly. @end enumerate The first two are described in more detail in this short tutorial. @@ -4707,15 +4717,20 @@ quantity. The commodity can have a set of flags that indicate how to display it. The meaning of the flags (all of which are optional) are: @table @code + @item P The commodity is prefixed to the value. + @item S The commodity is separated from the value by a space. + @item T Thousands markers are used to display the amount. + @item E The format of the amount is European, with period used as a thousands marker, and comma used as the decimal point. + @end table The actual quantity for an amount is an integer of arbitrary size. @@ -4972,35 +4987,47 @@ commands. @subsection Reporting Commands @ftable @code + @item balance @itemx bal Show account balances + @item register @itemx reg Show all transactions with running total + @item csv Show transactions in csv format, for exporting to other programs + @item print Print transaction in a ledger readable format + @item xml Produce XML output of the register command + @item lisp @itemx emacs Produce Emacs lisp output + @item equity Print account balances as transactions + @item prices Print price history for matching commodities + @item pricedb Print price history for matching commodities in ledger readable format + @item xact Generate transactions based on previous postings + @end ftable @node Basic Options Quick Reference, Report Filtering Quick Reference, Reporting Commands Quick Reference, Command Line Quick Reference @subsection Basic Options @ftable @code + @item --help @itemx -h Print summary of all options @@ -5024,213 +5051,281 @@ Specify options file @item --account @var{STR} @itemx -a @var{STR} Specify default account @var{STR} for QIF file postings + @end ftable @node Report Filtering Quick Reference, Error Checking and Calculation Options, Basic Options Quick Reference, Command Line Quick Reference @subsection Report Filtering @ftable @code + @item --current @itemx -c Display transaction on or before the current date + @item --begin @var{DATE} @itemx -b @var{DATE} Begin reports on or after @var{DATE} + @item --end @var{DATE} @itemx -e @var{DATE} Limit end date of transactions for report + @item --period @var{PERIOD_EXPRESSION} @itemx -p @var{PERIOD_EXPRESSION} Set report period to @var{PERIOD_EXPRESSION} + @item --period-sort @var{VEXPR} Sort postings within each period + @item --cleared @itemx -C Display only cleared postings + @item --dc Display register or balance in debit/credit format + @item --uncleared @itemx -U Display only uncleared postings + @item --real @itemx -R Display only real postings + @item --actual @itemx -L Display only actual postings, not automated + @item --related @itemx -r Display related postings + @item --budget Display how close your postings meet your budget + @item --add-budget Show un-budgeted postings + @item --unbudgeted Show only un-budgeted postings + @item --forecast Project balances into the future + @item --limit @var{EXPR} @itemx -l @var{EXPR} Limit postings in calculations + @item --amount @var{EXPR} @itemx -t @var{EXPR} Change value expression reported in @command{register} report + @item --total @var{VEXPR} @itemx -T @var{VEXPR} Change the value expression used for ``totals'' column in @command{register} and @command{balance} reports + @end ftable @node Error Checking and Calculation Options, Output Customization Quick Reference, Report Filtering Quick Reference, Command Line Quick Reference @subsection Error Checking and Calculation Options @ftable @code + @item --strict Accounts, tags or commodities not previously declared will cause warnings. + @item --pedantic Accounts, tags or commodities not previously declared will cause errors. @item --check-payees Enable strict and pedantic checking for payees as well as accounts, commodities and tags. + @item --immediate Instruct ledger to evaluate calculations immediately rather than lazily. + @end ftable @node Output Customization Quick Reference, Grouping Options, Error Checking and Calculation Options, Command Line Quick Reference @subsection Output Customization @ftable @code + @item --collapse @itemx -n Collapse transactions with multiple postings + @item --subtotal @itemx -s Report register as a single subtotal + @item --by-payee @itemx -P Report subtotals by payee + @item --empty @itemx -E Include empty accounts in report + @item --weekly @itemx -W Report posting totals by week + @item --yearly @itemx -Y Report posting totals by year + @item --dow Report Posting totals by day of week + @item --sort @var{VEXPR} @itemx -S @var{VEXPR} Sort a report using @var{VEXPR} + @item --wide @itemx -w Assume 132 columns instead of 80 + @item --head @var{INT} Report the first @var{INT} postings + @item --tail @var{INT} Report the last @var{INT} postings + @item --pager @var{FILE} Direct output to @var{FILE} pager program + @item --average @itemx -A Report average posting value + @item --deviation @itemx -D Report each posting deviation from the average + @item --percent @itemx -% Show subtotals in the balance report as percentages @c @item --totals @c Include running total in the @code{xml} report + @item --pivot @var{TAG} Produce a pivot table of the @var{TAG} type specified + @item --amount-data @itemx -j Show only date and value column to format the output for plots + @item --plot-amount-format @var{FORMAT_STRING} Specify the format for the plot output + @item --total-data @itemx -J Show only dates and totals to format the output for plots + @item --plot-total-format @var{FORMAT_STRING} Specify the format for the plot output + @item --display @var{EXPR} @itemx -d @var{EXPR} Display only posting that meet the criterias in the @var{EXPR} + @item --date-format @var{DATE_FORMAT} @itemx -y @var{DATE_FORMAT} Change the basic date format used in reports + @item --format @var{FORMAT_STRING} @itemx --balance-format @var{FORMAT_STRING} @itemx --register-format @var{FORMAT_STRING} @itemx --prices-format @var{FORMAT_STRING} @itemx -F @var{FORMAT_STRING} Set reporting format + @item --wide @itemx -w Wide + @item --anon Print the ledger register with anonymized accounts and payees, useful for filing bug reports. + @end ftable @node Grouping Options, Commodity Reporting Quick Reference, Output Customization Quick Reference, Command Line Quick Reference @subsection Grouping Options @ftable @code + @item --by-payee @itemx -P Group postings by common payee names + @item --daily @itemx -D Group postings by day + @item --weekly @itemx -W Group postings by week + @item --monthly @itemx -M Group postings by month + @item --quarterly Group postings by quarter + @item --yearly @itemx -Y Group postings by year + @item --dow Group by day of weeks + @item --subtotal @itemx -s Group posting together, similar to balance report + @end ftable @node Commodity Reporting Quick Reference, , Grouping Options, Command Line Quick Reference @subsection Commodity Reporting @ftable @code + @item --price-db @var{FILE} Use @file{FILE} for retrieving stored commodity prices. + @item --price-exp @var{INT} @itemx -L @var{INT} Set expected freshness of prices in @var{INT} minutes. + @item --download @itemx -Q Download quotes using named @file{getquote}. + @item --getquote @var{FILE} Sets path to a user defined script to download commodity prices. + @item --quantity @itemx -O Report commodity totals without conversion. + @item --basis @itemx -B Report cost basis. + @item --market @itemx -V Report last known market value. + @item --gain @itemx -G Report net gain loss for commodities that have a price history. + @end ftable @node Detailed Options Description, Period Expressions, Command Line Quick Reference, Command-line Syntax @@ -5258,6 +5353,7 @@ instance of Ledger running in the background and running multiple sessions with multiple reports per session. @ftable @code + @item --args-only Ignore all environment and init-file settings and use only command-line arguments to control Ledger. Useful for debugs @@ -5332,6 +5428,7 @@ FIX THIS ENTRY @c FIXME thdox @item --version FIX THIS ENTRY @c FIXME thdox + @end ftable @node Session Options, Report Options, Global Options, Detailed Options Description @@ -5345,6 +5442,7 @@ instance of Ledger running in the background and running multiple sessions with multiple reports per session. @ftable @code + @item --cache @var{FIXME} FIX THIS ENTRY @c FIXME thdox @@ -5450,6 +5548,7 @@ with the --time-colon option they will be displayed as 2:15. @item --value-expr @var{FIXME} FIX THIS ENTRY @c FIXME thdox + @end ftable @node Report Options, Basic options, Session Options, Detailed Options Description @@ -5463,6 +5562,7 @@ instance of Ledger running in the background and running multiple sessions with multiple reports per session. @ftable @code + @item --abbrev-len @var{INT} Set the minimum length an account can be abbreviated to if it doesn't fit inside the @code{account-width}. If @var{INT} is zero, then the @@ -6130,6 +6230,7 @@ want to set them using environment variables (see @ref{Environment Variables}), instead of using actual command-line options: @ftable @code + @item --help @itemx -h Print a summary of all the options, and what they are used for. This @@ -6175,6 +6276,7 @@ precedence over settings in the init file. @itemx -a @var{STR} Specify the default account which QIF file postings are assumed to relate to. + @end ftable @node Report Filtering, Output Customization, Basic options, Detailed Options Description @@ -6184,6 +6286,7 @@ These options change which postings affect the outcome of a report, in ways other than just using regular expressions: @ftable @code + @item --current @itemx -c Display only transactions occurring on or before the current date. @@ -6293,6 +6396,7 @@ totals in the @command{balance} report, and the values printed in the @itemx -T @var{VEXPR} Set the value expression used for the ``totals'' column in the @command{register} and @command{balance} reports. + @end ftable @c @node Search Terms, Output Customization, Report Filtering, Detailed Options Description @@ -6346,6 +6450,7 @@ These options affect only the output, but not which postings are used to create it: @ftable @code + @item --collapse @itemx -n Cause transactions in a @command{register} report with multiple @@ -6600,6 +6705,7 @@ Set the format for the @command{prices} report. The default is: "%(date) %-8(display_account) %(justify(scrub(display_amount), 12, 2 + 9 + 8 + 12, true, color))\n" @end smallexample + @end ftable @node Commodity Reporting, Environment Variables, Output Customization, Detailed Options Description @@ -6608,6 +6714,7 @@ Set the format for the @command{prices} report. The default is: These options affect how commodity values are displayed: @ftable @code + @item --price-db @var{FILE} Set the file that is used for recording downloaded commodity prices. It is always read on startup, to determine historical prices. Other @@ -6646,6 +6753,7 @@ value understood by ledger. A sample implementation of a distribution. Downloaded quote price are then appended to the price database, usually specified using the environment variable @env{LEDGER_PRICE_DB}. + @end ftable There are several different ways that ledger can report the totals it @@ -6655,6 +6763,7 @@ there are also several ``default'' reports, which will satisfy most users basic reporting needs: @ftable @code + @item --quantity @itemx -O Report commodity totals (this is the default) @@ -6671,6 +6780,7 @@ Use the last known value for commodities to calculate final values. @itemx -G Report the net gain/loss for all commodities in the report that have a price history. + @end ftable Often you will be more interested in the value of your entire holdings, @@ -6708,7 +6818,7 @@ One thing many people have wanted to do is to fixate the valuation of old European currencies in terms of the Euro after a certain date: @smallexample - = expr commodity == "DM" += expr commodity == "DM" ; VALUE:: date < [Jun 2008] ? market(amount, date, exchange) : 1.44 EUR @end smallexample @@ -6790,6 +6900,7 @@ example, then it will balance against that specific price for AAPL. Normally when you use @code{-X @var{COMMODITY}} to request that amounts be reported in a specific commodity, Ledger uses these values: + @itemize @item Register Report @@ -6799,6 +6910,7 @@ end of today's value is different from the value of the last posting. @item Balance Report For the balance report, use the value of that commodity as of today. + @end itemize You can now specify @code{-H} to ask that all valuations for any @@ -7048,15 +7160,20 @@ Ledger uses value expressions to make calculations for many different purposes: @enumerate + @item The values displayed in reports + @item For predicates (where truth is anything non-zero), to determine which postings are calculated (@code{-l}) or displayed (@code{-d}). + @item For sorting criteria, to yield the sort key. + @item In the matching criteria used by automated postings. + @end enumerate Value expressions support most simple math and logic operators, in @@ -7111,6 +7228,7 @@ accounts, often with a subtle difference in meaning. The use of each variable for both is specified. @table @code + @item t This maps to whatever the user specified with @code{-t}. In a register report, @code{-t} changes the value column; in a balance @@ -7125,6 +7243,7 @@ not specified, the current report style's value expression is used. @item m This is always the present moment/date. + @end table @menu @@ -7136,6 +7255,7 @@ This is always the present moment/date. @subsection Posting/account details @table @code + @item d A posting's date, as the number of seconds past the epoch. This is always ``today'' for an account. @@ -7171,12 +7291,14 @@ account. @item Z @samp{1} if a posting is not automated, @samp{0} otherwise. + @end table @node Calculated totals, , Posting/account details, Variables @subsection Calculated totals @table @code + @item O The total of all postings seen so far, or the total of an account and all its children. @@ -7197,6 +7319,7 @@ all its children. The total net gain (market value minus cost basis), for a series of postings, or an account and its children. It is the same as @samp{V-B}. + @end table @node Functions, Operators, Variables, Value Expressions @@ -7205,6 +7328,7 @@ postings, or an account and its children. It is the same as The available one letter functions are: @table @code + @item - Negates the argument. @@ -7222,6 +7346,7 @@ The arithmetic mean of the argument; @samp{Ax} is the same as The present market value of the argument. The syntax @samp{P(x,d)} is supported, which yields the market value at time @samp{d}. If no date is given, then the current moment is used. + @end table @node Operators, Complex Expressions, Functions, Value Expressions @@ -7277,6 +7402,7 @@ The binary and ternary operators, in order of precedence, are: More complicated expressions are possible using: @table @code + @item NUM A plain integer represents a commodity-less amount. @@ -7316,6 +7442,7 @@ precedence order of operators. @item [DATE] Useful specifying a date in plain terms. For example, you could say @code{[2004/06/01]}. + @end table @menu @@ -7447,12 +7574,16 @@ a maximum width is given, the substituted text will never be wider than this, and will be truncated to fit. Here are some examples: @table @code + @item %-20P A transaction's payee, left justified and padded to 20 characters wide. + @item %20P The same, right justified, at least 20 chars wide. + @item %.20P The same, no more than 20 chars wide. + @end table The expression following the format constraints can be a single letter, @@ -7464,6 +7595,7 @@ or an expression enclosed in parentheses or brackets. The allowable expressions are: @table @code + @item % Inserts a percent sign. @@ -7560,6 +7692,7 @@ 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. + @end table @node --balance-format, Formatting codes, Format Expressions, Format Strings @@ -7654,21 +7787,29 @@ terminal character colors and font highlights in a normal TTY session. The following functions allow you to manipulate and format dates. @table @code + @item date Return the date of the current transaction + @item format_date(date, "FORMAT_STRING") Format the date using the given format string. + @item now Return the current date and time. If the @code{--now @var{DATE}} option is defined it will return that value. + @item today Return the current date. If the @code{--now @var{DATE}} option is defined it will return that value. + @item to_datetime Convert a string to a date-time value + @item to_date Convert a string to date value + @item value_date + @end table @menu @@ -7696,6 +7837,7 @@ Dates are formed from a combination of day, month and year codes, in whatever order you prefer: @table @code + @item %Y Four digit year @@ -7707,6 +7849,7 @@ Two digit month @item %d Two digit date + @end table @noindent @@ -7720,31 +7863,41 @@ You can have additional weekday information in your date with @samp{%A} as @table @code + @item %m-%d-%Y %A yields @code{02-10-2010 Wednesday} @item %A %m-%d-%Y yields @code{Wednesday 02-10-2010} + @end table @noindent These are options you can select for weekday @table @code + @item %a weekday, abbreviated Wed + @item %A weekday, full Wednesday + @item %d day of the month (dd), zero padded 10 + @item %e day of the month (dd) 10 + @item %j day of year, zero padded 000-366 + @item %u day of week starting with Monday (1), i.e. @code{mtwtfss} 3 + @item %w day of week starting with Sunday (0), i.e. @code{smtwtfs} 3 + @end table @node Month, Miscellaneous Date Codes, Weekdays, Date and Time Format Codes @@ -7754,17 +7907,20 @@ You can have additional month information in your date with @samp{%B} as @table @code + @item %m-%d-%Y %B yields @code{02-10-2010 February} @item %B %m-%d-%Y yields @code{February 02-10-2010} + @end table @noindent These are options you can select for month @table @code + @item %m @samp{mm} month as two digits @@ -7774,6 +7930,7 @@ as @samp{Feb} @item %B Locale’s full month, variable length February + @end table @node Miscellaneous Date Codes, , Month, Date and Time Format Codes @@ -7782,20 +7939,28 @@ Locale’s full month, variable length February Additional date format parameters which can be used: @table @code + @item %U week number Sunday as first day of week 01–53 + @item %W week number Monday as first day of week 01–53 + @item %V week of the year 01–53 + @item %C @code{cc} century 00–99 + @item %D yields @code{mm/dd/yy 02/10/10} + @item %x locale’s date representation @code{02/10/2010} for the U.S. + @item %F yields @code{%Y-%m-%d 2010-02-10} + @end table @menu @@ -7810,6 +7975,7 @@ yields @code{%Y-%m-%d 2010-02-10} The following format functions allow you limited formatting of text: @table @code + @item ansify_if(value, color) Surrounds the string representing value with ANSI codes to give it @code{color} on an TTY display. Has no effect if directed to a file. @@ -7833,6 +7999,7 @@ Return @code{STR} surrounded by double quotes, @code{"STR"}. @item strip(value) Values can have numerous annotations, such as effective dates and lot prices. @code{strip} removes these annotations. + @end table @node Data File Parsing Information, , Text Formatting, Formatting codes @@ -7843,20 +8010,26 @@ regarding the coordinates of entries in the source data file(s) that generated the posting. @table @code + @item filename name of ledger data file from whence posting came, abbreviated @samp{S} + @item beg_pos character position in @code{filename} where entry for posting begins, abbreviated @samp{B} + @item end_pos character position in @code{filename} where entry for posting ends, abbreviated @samp{E} + @item beg_line line number in @code{filename} where entry for posting begins, abbreviated @samp{b} + @item end_line line number in @code{filename} where posting's entry for posting ends, abbreviated @samp{e} + @end table @node Extending with Python, Ledger for Developers, Format Strings, Top @@ -8039,6 +8212,7 @@ modularity. Those tiers are: @itemize + @item Utility code There's lots of general utility in Ledger for doing time parsing, @@ -8248,6 +8422,7 @@ Application object. This creates the global scope object, performs error reporting, and handles command-line options which must precede even the creation of the global scope, such as @code{--debug}. + @end itemize And that's Ledger in a nutshell. All the rest are details, such as @@ -8565,6 +8740,7 @@ These options are primarily for Ledger developers, but may be of some use to a user trying something new. @ftable @code + @item --args-only Ignore init files and environment variables for the ledger run. @@ -8631,6 +8807,7 @@ FIX THIS ENTRY @c FIXME thdox @item --version Print version information and exit. + @end ftable @node Pre-commands, , Debug Options, Developer Commands @@ -8643,6 +8820,7 @@ is that pre-commands ignore the journal data file completely, nor is the user's init file read. @ftable @code + @item eval @var{VEXPR} Evaluate the given value expression against the model transaction @@ -8728,6 +8906,7 @@ FIX THIS ENTRY @c FIXME thdox @item template Shows the insertion template that a @code{draft} or @code{xact} sub-command generates. This is a debugging command. + @end ftable @node Ledger Development Environment, , Developer Commands, Ledger for Developers @@ -8784,11 +8963,14 @@ for example, issue @code{ctest -V -R "5FB"}. @chapter Major Changes from version 2.6 @itemize + @item OFX support has been removed from Ledger 3.0 + @item Single character value expressions are deprecated and should be changed to the new value expressions available in 3.0 + @end itemize @node Example Data File, Miscellaneous Notes, Major Changes from version 2.6, Top |