diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index af018351a..204034b55 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -337,119 +337,134 @@ Account names can be aliased. .SS Amounts .PP After the account name, there is usually an amount. -Important: between account name and amount, there must be \f[B]two or -more spaces\f[R]. +(Important: between account name and amount, there must be \f[B]two or +more spaces\f[R].) .PP -Amounts consist of a number and (usually) a currency symbol or commodity -name. -Some examples: +hledger\[aq]s amount format is flexible, supporting several +international formats. +Here are some examples. +Amounts have a number (the \[dq]quantity\[dq]): +.IP +.nf +\f[C] +1 +\f[R] +.fi .PP -\f[C]2.00001\f[R] -.PD 0 -.P -.PD -\f[C]$1\f[R] -.PD 0 -.P -.PD -\f[C]4000 AAPL\f[R] -.PD 0 -.P -.PD -\f[C]3 \[dq]green apples\[dq]\f[R] -.PD 0 -.P -.PD -\f[C]-$1,000,000.00\f[R] -.PD 0 -.P -.PD -\f[C]INR 9,99,99,999.00\f[R] -.PD 0 -.P -.PD -\f[C]EUR -2.000.000,00\f[R] -.PD 0 -.P -.PD -\f[C]1 999 999.9455\f[R] -.PD 0 -.P -.PD -\f[C]EUR 1E3\f[R] -.PD 0 -.P -.PD -\f[C]1000E-6s\f[R] +\&..and usually a currency or commodity name (the \[dq]commodity\[dq]). +This is a symbol, word, or phrase, to the left or right of the quantity, +with or without a separating space: +.IP +.nf +\f[C] +$1 +4000 AAPL +\f[R] +.fi .PP -As you can see, the amount format is somewhat flexible: -.IP \[bu] 2 -amounts are a number (the \[dq]quantity\[dq]) and optionally a currency -symbol/commodity name (the \[dq]commodity\[dq]). -.IP \[bu] 2 -the commodity is a symbol, word, or phrase, on the left or right, with -or without a separating space. -If the commodity contains numbers, spaces or non-word punctuation it -must be enclosed in double quotes. -.IP \[bu] 2 -negative amounts with a commodity on the left can have the minus sign -before or after it -.IP \[bu] 2 -digit groups (thousands, or any other grouping) can be separated by -space or comma or period and should be used as separator between all -groups -.IP \[bu] 2 -decimal part can be separated by comma or period and should be different -from digit groups separator -.IP \[bu] 2 -scientific E-notation is allowed. -Be careful not to use a digit group separator character in scientific -notation, as it\[aq]s not supported and it might get mistaken for a -decimal point. -(Declaring the digit group separator character explicitly with a -commodity directive will prevent this.) +If the commodity name contains spaces, numbers, or punctuation, it must +be enclosed in double quotes: +.IP +.nf +\f[C] +3 \[dq]no. 42 green apples\[dq] +\f[R] +.fi .PP -You can use any of these variations when recording data. -However, there is some ambiguous way of representing numbers like -\f[C]$1.000\f[R] and \f[C]$1,000\f[R] both may mean either one thousand -or one dollar. -By default hledger will assume that this is sole delimiter is used only -for decimals. -On the other hand commodity format declared prior to that line will help -to resolve that ambiguity differently: +Amounts can be negative. +The minus sign can be written before or after a left-side commodity +symbol: +.IP +.nf +\f[C] +-$1 +$-1 +\f[R] +.fi +.PP +Scientific E notation is allowed: +.IP +.nf +\f[C] +1E-6 +EUR 1E3 +\f[R] +.fi +.PP +A decimal mark (decimal point) can be written with a period or a comma: +.IP +.nf +\f[C] +1.23 +1,23456780000009 +\f[R] +.fi +.SS Digit group marks +.PP +In the integer part of the quantity (left of the decimal mark), groups +of digits can optionally be separated by a \[dq]digit group mark\[dq] - +a space, comma, or period (different from the decimal mark): +.IP +.nf +\f[C] + $1,000,000.00 + EUR 2.000.000,00 +INR 9,99,99,999.00 + 1 000 000.9455 +\f[R] +.fi +.PP +Note, a number containing a single group mark and no decimal mark is +ambiguous. +Are these group marks or decimal marks ? +.IP +.nf +\f[C] +1,000 +1.000 +\f[R] +.fi +.PP +hledger will treat them both as decimal marks by default (cf #793). +If you use digit group marks, to prevent confusion and undetected typos +we recommend you write commodity directives at the top of the file to +explicitly declare the decimal mark (and optionally a digit group mark). +Note, these formats (\[dq]amount styles\[dq]) are specific to each +commodity, so if your data uses multiple formats, hledger can handle it: .IP .nf \f[C] commodity $1,000.00 - -2017/12/25 New life of Scrooge - expenses:gifts $1,000 - assets +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +;commodity \[dq]\[dq] 1 000 000.9455 ; can\[aq]t declare a format for the null commodity yet \f[R] .fi +.SS Amount display format .PP -Though journal may contain mixed styles to represent amount, when -hledger displays amounts, it will choose a consistent format for each -commodity. -(Except for price amounts, which are always formatted as written). +For each commodity, hledger chooses a consistent format to use when +displaying amounts. +(Except price amounts, which are always displayed as written). The display format is chosen as follows: .IP \[bu] 2 -if there is a commodity directive specifying the format, that is used +If there is a commodity directive for the commodity, that format is used +(see examples above). .IP \[bu] 2 -otherwise the format is inferred from the first posting amount in that -commodity in the journal, and the precision (number of decimal places) -will be the maximum from all posting amounts in that commmodity +Otherwise the format of the first posting amount in that commodity seen +in the journal is used. +But the number of decimal places (\[dq]precision\[dq]) will be the +maximum from all posting amounts in that commmodity. .IP \[bu] 2 -or if there are no such amounts in the journal, a default format is used +Or if there are no such amounts in the journal, a default format is used (like \f[C]$1000.00\f[R]). .PP -Price amounts and amounts in \f[C]D\f[R] directives usually don\[aq]t -affect amount format inference, but in some situations they can do so +Price amounts, and amounts in \f[C]D\f[R] directives don\[aq]t affect +the amount display format directly, but occasionally they can do so indirectly. (Eg when D\[aq]s default commodity is applied to a commodity-less amount, or when an amountless posting is balanced using a price\[aq]s -commodity, or when -V is used.) If you find this causing problems, set -the desired format with a commodity directive. +commodity, or when -V is used.) If you find this causing problems, use a +commodity directive to set the display format. .SS Virtual Postings .PP When you parenthesise the account name in a posting, we call that a diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 09f2bfeb2..abb14421b 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -337,77 +337,109 @@ File: hledger_journal.info, Node: Amounts, Next: Virtual Postings, Prev: Acco 1.7 Amounts =========== -After the account name, there is usually an amount. Important: between -account name and amount, there must be *two or more spaces*. +After the account name, there is usually an amount. (Important: between +account name and amount, there must be *two or more spaces*.) - Amounts consist of a number and (usually) a currency symbol or -commodity name. Some examples: + hledger's amount format is flexible, supporting several international +formats. Here are some examples. Amounts have a number (the +"quantity"): - '2.00001' -'$1' -'4000 AAPL' -'3 "green apples"' -'-$1,000,000.00' -'INR 9,99,99,999.00' -'EUR -2.000.000,00' -'1 999 999.9455' -'EUR 1E3' -'1000E-6s' +1 - As you can see, the amount format is somewhat flexible: + ..and usually a currency or commodity name (the "commodity"). This +is a symbol, word, or phrase, to the left or right of the quantity, with +or without a separating space: - * amounts are a number (the "quantity") and optionally a currency - symbol/commodity name (the "commodity"). - * the commodity is a symbol, word, or phrase, on the left or right, - with or without a separating space. If the commodity contains - numbers, spaces or non-word punctuation it must be enclosed in - double quotes. - * negative amounts with a commodity on the left can have the minus - sign before or after it - * digit groups (thousands, or any other grouping) can be separated by - space or comma or period and should be used as separator between - all groups - * decimal part can be separated by comma or period and should be - different from digit groups separator - * scientific E-notation is allowed. Be careful not to use a digit - group separator character in scientific notation, as it's not - supported and it might get mistaken for a decimal point. - (Declaring the digit group separator character explicitly with a - commodity directive will prevent this.) +$1 +4000 AAPL - You can use any of these variations when recording data. However, -there is some ambiguous way of representing numbers like '$1.000' and -'$1,000' both may mean either one thousand or one dollar. By default -hledger will assume that this is sole delimiter is used only for -decimals. On the other hand commodity format declared prior to that -line will help to resolve that ambiguity differently: + If the commodity name contains spaces, numbers, or punctuation, it +must be enclosed in double quotes: + +3 "no. 42 green apples" + + Amounts can be negative. The minus sign can be written before or +after a left-side commodity symbol: + +-$1 +$-1 + + Scientific E notation is allowed: + +1E-6 +EUR 1E3 + + A decimal mark (decimal point) can be written with a period or a +comma: + +1.23 +1,23456780000009 + +* Menu: + +* Digit group marks:: +* Amount display format:: + + +File: hledger_journal.info, Node: Digit group marks, Next: Amount display format, Up: Amounts + +1.7.1 Digit group marks +----------------------- + +In the integer part of the quantity (left of the decimal mark), groups +of digits can optionally be separated by a "digit group mark" - a space, +comma, or period (different from the decimal mark): + + $1,000,000.00 + EUR 2.000.000,00 +INR 9,99,99,999.00 + 1 000 000.9455 + + Note, a number containing a single group mark and no decimal mark is +ambiguous. Are these group marks or decimal marks ? + +1,000 +1.000 + + hledger will treat them both as decimal marks by default (cf #793). +If you use digit group marks, to prevent confusion and undetected typos +we recommend you write commodity directives at the top of the file to +explicitly declare the decimal mark (and optionally a digit group mark). +Note, these formats ("amount styles") are specific to each commodity, so +if your data uses multiple formats, hledger can handle it: commodity $1,000.00 +commodity EUR 1.000,00 +commodity INR 9,99,99,999.00 +;commodity "" 1 000 000.9455 ; can't declare a format for the null commodity yet -2017/12/25 New life of Scrooge - expenses:gifts $1,000 - assets + +File: hledger_journal.info, Node: Amount display format, Prev: Digit group marks, Up: Amounts - Though journal may contain mixed styles to represent amount, when -hledger displays amounts, it will choose a consistent format for each -commodity. (Except for price amounts, which are always formatted as -written). The display format is chosen as follows: +1.7.2 Amount display format +--------------------------- - * if there is a commodity directive specifying the format, that is - used - * otherwise the format is inferred from the first posting amount in - that commodity in the journal, and the precision (number of decimal - places) will be the maximum from all posting amounts in that - commmodity - * or if there are no such amounts in the journal, a default format is +For each commodity, hledger chooses a consistent format to use when +displaying amounts. (Except price amounts, which are always displayed +as written). The display format is chosen as follows: + + * If there is a commodity directive for the commodity, that format is + used (see examples above). + + * Otherwise the format of the first posting amount in that commodity + seen in the journal is used. But the number of decimal places + ("precision") will be the maximum from all posting amounts in that + commmodity. + + * Or if there are no such amounts in the journal, a default format is used (like '$1000.00'). - Price amounts and amounts in 'D' directives usually don't affect -amount format inference, but in some situations they can do so -indirectly. (Eg when D's default commodity is applied to a -commodity-less amount, or when an amountless posting is balanced using a -price's commodity, or when -V is used.) If you find this causing -problems, set the desired format with a commodity directive. + Price amounts, and amounts in 'D' directives don't affect the amount +display format directly, but occasionally they can do so indirectly. +(Eg when D's default commodity is applied to a commodity-less amount, or +when an amountless posting is balanced using a price's commodity, or +when -V is used.) If you find this causing problems, use a commodity +directive to set the display format.  File: hledger_journal.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT @@ -1733,91 +1765,95 @@ Node: Account names11337 Ref: #account-names11480 Node: Amounts11967 Ref: #amounts12103 -Node: Virtual Postings15120 -Ref: #virtual-postings15279 -Node: Balance Assertions16499 -Ref: #balance-assertions16674 -Node: Assertions and ordering17633 -Ref: #assertions-and-ordering17819 -Node: Assertions and included files18519 -Ref: #assertions-and-included-files18760 -Node: Assertions and multiple -f options19093 -Ref: #assertions-and-multiple--f-options19347 -Node: Assertions and commodities19479 -Ref: #assertions-and-commodities19709 -Node: Assertions and prices20865 -Ref: #assertions-and-prices21077 -Node: Assertions and subaccounts21517 -Ref: #assertions-and-subaccounts21744 -Node: Assertions and virtual postings22068 -Ref: #assertions-and-virtual-postings22308 -Node: Assertions and precision22450 -Ref: #assertions-and-precision22641 -Node: Balance Assignments22908 -Ref: #balance-assignments23089 -Node: Balance assignments and prices24254 -Ref: #balance-assignments-and-prices24426 -Node: Transaction prices24650 -Ref: #transaction-prices24819 -Node: Comments27085 -Ref: #comments27219 -Node: Tags28389 -Ref: #tags28507 -Node: Directives29900 -Ref: #directives30043 -Node: Comment blocks35651 -Ref: #comment-blocks35796 -Node: Including other files35972 -Ref: #including-other-files36152 -Node: Default year36560 -Ref: #default-year36729 -Node: Declaring commodities37136 -Ref: #declaring-commodities37319 -Node: Default commodity38748 -Ref: #default-commodity38924 -Node: Market prices39558 -Ref: #market-prices39723 -Node: Declaring accounts40564 -Ref: #declaring-accounts40740 -Node: Account comments41665 -Ref: #account-comments41828 -Node: Account subdirectives42223 -Ref: #account-subdirectives42418 -Node: Account types42731 -Ref: #account-types42915 -Node: Account display order44557 -Ref: #account-display-order44727 -Node: Rewriting accounts45856 -Ref: #rewriting-accounts46041 -Node: Basic aliases46777 -Ref: #basic-aliases46923 -Node: Regex aliases47627 -Ref: #regex-aliases47799 -Node: Combining aliases48517 -Ref: #combining-aliases48695 -Node: end aliases49971 -Ref: #end-aliases50119 -Node: Default parent account50220 -Ref: #default-parent-account50386 -Node: Periodic transactions51270 -Ref: #periodic-transactions51468 -Node: Periodic rule syntax53340 -Ref: #periodic-rule-syntax53546 -Node: Two spaces between period expression and description!54250 -Ref: #two-spaces-between-period-expression-and-description54569 -Node: Forecasting with periodic transactions55253 -Ref: #forecasting-with-periodic-transactions55558 -Node: Budgeting with periodic transactions57584 -Ref: #budgeting-with-periodic-transactions57823 -Node: Auto postings / transaction modifiers58272 -Ref: #auto-postings-transaction-modifiers58483 -Node: Auto postings and dates60712 -Ref: #auto-postings-and-dates60969 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions61144 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61519 -Node: Auto posting tags61897 -Ref: #auto-posting-tags62136 -Node: EDITOR SUPPORT62801 -Ref: #editor-support62919 +Node: Digit group marks13036 +Ref: #digit-group-marks13185 +Node: Amount display format14174 +Ref: #amount-display-format14331 +Node: Virtual Postings15356 +Ref: #virtual-postings15515 +Node: Balance Assertions16735 +Ref: #balance-assertions16910 +Node: Assertions and ordering17869 +Ref: #assertions-and-ordering18055 +Node: Assertions and included files18755 +Ref: #assertions-and-included-files18996 +Node: Assertions and multiple -f options19329 +Ref: #assertions-and-multiple--f-options19583 +Node: Assertions and commodities19715 +Ref: #assertions-and-commodities19945 +Node: Assertions and prices21101 +Ref: #assertions-and-prices21313 +Node: Assertions and subaccounts21753 +Ref: #assertions-and-subaccounts21980 +Node: Assertions and virtual postings22304 +Ref: #assertions-and-virtual-postings22544 +Node: Assertions and precision22686 +Ref: #assertions-and-precision22877 +Node: Balance Assignments23144 +Ref: #balance-assignments23325 +Node: Balance assignments and prices24490 +Ref: #balance-assignments-and-prices24662 +Node: Transaction prices24886 +Ref: #transaction-prices25055 +Node: Comments27321 +Ref: #comments27455 +Node: Tags28625 +Ref: #tags28743 +Node: Directives30136 +Ref: #directives30279 +Node: Comment blocks35887 +Ref: #comment-blocks36032 +Node: Including other files36208 +Ref: #including-other-files36388 +Node: Default year36796 +Ref: #default-year36965 +Node: Declaring commodities37372 +Ref: #declaring-commodities37555 +Node: Default commodity38984 +Ref: #default-commodity39160 +Node: Market prices39794 +Ref: #market-prices39959 +Node: Declaring accounts40800 +Ref: #declaring-accounts40976 +Node: Account comments41901 +Ref: #account-comments42064 +Node: Account subdirectives42459 +Ref: #account-subdirectives42654 +Node: Account types42967 +Ref: #account-types43151 +Node: Account display order44793 +Ref: #account-display-order44963 +Node: Rewriting accounts46092 +Ref: #rewriting-accounts46277 +Node: Basic aliases47013 +Ref: #basic-aliases47159 +Node: Regex aliases47863 +Ref: #regex-aliases48035 +Node: Combining aliases48753 +Ref: #combining-aliases48931 +Node: end aliases50207 +Ref: #end-aliases50355 +Node: Default parent account50456 +Ref: #default-parent-account50622 +Node: Periodic transactions51506 +Ref: #periodic-transactions51704 +Node: Periodic rule syntax53576 +Ref: #periodic-rule-syntax53782 +Node: Two spaces between period expression and description!54486 +Ref: #two-spaces-between-period-expression-and-description54805 +Node: Forecasting with periodic transactions55489 +Ref: #forecasting-with-periodic-transactions55794 +Node: Budgeting with periodic transactions57820 +Ref: #budgeting-with-periodic-transactions58059 +Node: Auto postings / transaction modifiers58508 +Ref: #auto-postings-transaction-modifiers58719 +Node: Auto postings and dates60948 +Ref: #auto-postings-and-dates61205 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions61380 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61755 +Node: Auto posting tags62133 +Ref: #auto-posting-tags62372 +Node: EDITOR SUPPORT63037 +Ref: #editor-support63155  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index ae0540764..faf292f9d 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -246,83 +246,93 @@ FILE FORMAT Account names can be aliased. Amounts - After the account name, there is usually an amount. Important: between - account name and amount, there must be two or more spaces. + After the account name, there is usually an amount. (Important: be- + tween account name and amount, there must be two or more spaces.) - Amounts consist of a number and (usually) a currency symbol or commod- - ity name. Some examples: + hledger's amount format is flexible, supporting several international + formats. Here are some examples. Amounts have a number (the "quan- + tity"): - 2.00001 - $1 - 4000 AAPL - 3 "green apples" - -$1,000,000.00 - INR 9,99,99,999.00 - EUR -2.000.000,00 - 1 999 999.9455 - EUR 1E3 - 1000E-6s + 1 - As you can see, the amount format is somewhat flexible: + ..and usually a currency or commodity name (the "commodity"). This is + a symbol, word, or phrase, to the left or right of the quantity, with + or without a separating space: - o amounts are a number (the "quantity") and optionally a currency sym- - bol/commodity name (the "commodity"). + $1 + 4000 AAPL - o the commodity is a symbol, word, or phrase, on the left or right, - with or without a separating space. If the commodity contains num- - bers, spaces or non-word punctuation it must be enclosed in double - quotes. + If the commodity name contains spaces, numbers, or punctuation, it must + be enclosed in double quotes: - o negative amounts with a commodity on the left can have the minus sign - before or after it + 3 "no. 42 green apples" - o digit groups (thousands, or any other grouping) can be separated by - space or comma or period and should be used as separator between all - groups + Amounts can be negative. The minus sign can be written before or after + a left-side commodity symbol: - o decimal part can be separated by comma or period and should be dif- - ferent from digit groups separator + -$1 + $-1 - o scientific E-notation is allowed. Be careful not to use a digit - group separator character in scientific notation, as it's not sup- - ported and it might get mistaken for a decimal point. (Declaring the - digit group separator character explicitly with a commodity directive - will prevent this.) + Scientific E notation is allowed: - You can use any of these variations when recording data. However, - there is some ambiguous way of representing numbers like $1.000 and - $1,000 both may mean either one thousand or one dollar. By default - hledger will assume that this is sole delimiter is used only for deci- - mals. On the other hand commodity format declared prior to that line - will help to resolve that ambiguity differently: + 1E-6 + EUR 1E3 + + A decimal mark (decimal point) can be written with a period or a comma: + + 1.23 + 1,23456780000009 + + Digit group marks + In the integer part of the quantity (left of the decimal mark), groups + of digits can optionally be separated by a "digit group mark" - a + space, comma, or period (different from the decimal mark): + + $1,000,000.00 + EUR 2.000.000,00 + INR 9,99,99,999.00 + 1 000 000.9455 + + Note, a number containing a single group mark and no decimal mark is + ambiguous. Are these group marks or decimal marks ? + + 1,000 + 1.000 + + hledger will treat them both as decimal marks by default (cf #793). If + you use digit group marks, to prevent confusion and undetected typos we + recommend you write commodity directives at the top of the file to ex- + plicitly declare the decimal mark (and optionally a digit group mark). + Note, these formats ("amount styles") are specific to each commodity, + so if your data uses multiple formats, hledger can handle it: commodity $1,000.00 + commodity EUR 1.000,00 + commodity INR 9,99,99,999.00 + ;commodity "" 1 000 000.9455 ; can't declare a format for the null commodity yet - 2017/12/25 New life of Scrooge - expenses:gifts $1,000 - assets + Amount display format + For each commodity, hledger chooses a consistent format to use when + displaying amounts. (Except price amounts, which are always displayed + as written). The display format is chosen as follows: - Though journal may contain mixed styles to represent amount, when - hledger displays amounts, it will choose a consistent format for each - commodity. (Except for price amounts, which are always formatted as - written). The display format is chosen as follows: + o If there is a commodity directive for the commodity, that format is + used (see examples above). - o if there is a commodity directive specifying the format, that is used + o Otherwise the format of the first posting amount in that commodity + seen in the journal is used. But the number of decimal places ("pre- + cision") will be the maximum from all posting amounts in that comm- + modity. - o otherwise the format is inferred from the first posting amount in - that commodity in the journal, and the precision (number of decimal - places) will be the maximum from all posting amounts in that commmod- - ity - - o or if there are no such amounts in the journal, a default format is + o Or if there are no such amounts in the journal, a default format is used (like $1000.00). - Price amounts and amounts in D directives usually don't affect amount - format inference, but in some situations they can do so indirectly. - (Eg when D's default commodity is applied to a commodity-less amount, - or when an amountless posting is balanced using a price's commodity, or - when -V is used.) If you find this causing problems, set the desired - format with a commodity directive. + Price amounts, and amounts in D directives don't affect the amount dis- + play format directly, but occasionally they can do so indirectly. (Eg + when D's default commodity is applied to a commodity-less amount, or + when an amountless posting is balanced using a price's commodity, or + when -V is used.) If you find this causing problems, use a commodity + directive to set the display format. Virtual Postings When you parenthesise the account name in a posting, we call that a @@ -667,11 +677,6 @@ FILE FORMAT account any document account names, de- all entries in all text clare account types & dis- files, before or play order after - - - - - alias end rewrite account names following in- aliases line/included en- tries until end of @@ -727,6 +732,8 @@ FILE FORMAT file.) display how to display amounts of a commodity in reports (symbol side style and spacing, digit groups, decimal separator, decimal places) + + directive which entries and (when there are multiple files) which files scope are affected by a directive