diff --git a/hledger-lib/hledger_csv.m4.md b/hledger-lib/hledger_csv.m4.md index 53ecb1d73..614b28a22 100644 --- a/hledger-lib/hledger_csv.m4.md +++ b/hledger-lib/hledger_csv.m4.md @@ -45,7 +45,7 @@ these are described more fully below, after the examples: | [**`newest-first`**](#newest-first) | disambiguate record order when there's only one date | | [**`include`**](#include) | inline another CSV rules file | -Note, for best error messages when reading CSV files, use a `.csv`, `.tsv` or `.ssv` +Note, for best error messages when reading CSV files, use a `.csv`, `.tsv` or `.ssv` file extension or file prefix - see [File Extension](#file-extension) below. There's an introductory [Convert CSV files](convert-csv-files.html) tutorial on hledger.org. @@ -102,7 +102,7 @@ fields date, description, amount-out, amount-in, balance # We generate balance assertions by assigning to "balance" # above, but you may sometimes need to remove these because: # -# - the CSV balance differs from the true balance, +# - the CSV balance differs from the true balance, # by up to 0.0000000000005 in my experience # # - it is sometimes calculated based on non-chronological ordering, @@ -176,7 +176,7 @@ amount2 %amzamount # add a third posting for fees, but only if they are non-zero. # Commas in the data makes counting fields hard, so count from the right instead. -# (Regex translation: "a field containing a non-zero dollar amount, +# (Regex translation: "a field containing a non-zero dollar amount, # immediately before the 1 right-most fields") if ,\$[1-9][.0-9]+(,[^,]*){1}$ account3 expenses:fees @@ -232,11 +232,11 @@ date-format %-m/%-d/%Y if In Progress Temporary Hold -Update to +Update to skip # add more fields to the description -description %description_ %itemtitle +description %description_ %itemtitle # save some other fields as tags comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ @@ -284,9 +284,9 @@ include common.rules # apply some overrides specific to this csv -# Transfers from/to bank. These are usually marked Pending, +# Transfers from/to bank. These are usually marked Pending, # which can be disregarded in this case. -if +if Bank Account Bank Deposit to PP Account description %type for %referencetxnid %itemtitle @@ -388,27 +388,27 @@ A fields list (the word "fields" followed by comma-separated field names) is the quick way to assign CSV field values to hledger fields. It does two things: -1. it names the CSV fields. +1. it names the CSV fields. This is optional, but can be convenient later for interpolating them. 2. when you use a standard hledger field name, it assigns the CSV value to that part of the hledger transaction. -Here's an example that says +Here's an example that says "use the 1st, 2nd and 4th fields as the transaction's date, description and amount; name the last two fields for later reference; and ignore the others": ```rules fields date, description, , amount, , , somefield, anotherfield ``` -Field names may not contain whitespace. +Field names may not contain whitespace. Fields you don't care about can be left unnamed. Currently there must be least two items (there must be at least one comma). Note, always use comma in the fields list, even if your CSV uses [another separator character](#separator). -Here are the standard hledger field/pseudo-field names. +Here are the standard hledger field/pseudo-field names. For more about the transaction parts they refer to, see the manual for hledger's journal format. ### Transaction field names @@ -421,7 +421,7 @@ For more about the transaction parts they refer to, see the manual for hledger's `accountN`, where N is 1 to 9, generates a [posting](journal.html#postings), with that account name. Most often there are two postings, so you'll want to set `account1` and `account2`. -If a posting's account name is left unset but its amount is set, +If a posting's account name is left unset but its amount is set, a default account name will be chosen (like expenses:unknown or income:unknown). `amountN` sets posting N's amount. Or, `amount` with no N sets posting @@ -432,18 +432,18 @@ a default account name will be chosen (like expenses:unknown or income:unknown). For convenience and backwards compatibility, if you set the amount of posting 1 only, a second posting with the negative amount will be generated automatically. -(Unless the account name is parenthesised indicating an +(Unless the account name is parenthesised indicating an [unbalanced posting](journal.html#virtual-postings).) If the CSV has the currency symbol in a separate field, you can use `currencyN` to prepend it to posting N's amount. `currency` with no N affects ALL postings. -`balanceN` sets a [balance assertion](journal.html#balance-assertions) amount +`balanceN` sets a [balance assertion](journal.html#balance-assertions) amount (or if the posting amount is left empty, a [balance assignment](journal.html#balance-assignments)). You may need to adjust this with the [`balance-type` rule](#balance-type). -Finally, `commentN` sets a [comment](journal.html#comments) on the Nth posting. +Finally, `commentN` sets a [comment](journal.html#comments) on the Nth posting. Comments can also contain [tags](journal.html#tags), as usual. See TIPS below for more about setting amounts and currency. @@ -459,7 +459,7 @@ Instead of or in addition to a [fields list](#fields), you can use a "field assignment" rule to set the value of a single hledger field, by writing its name (any of the standard hledger field names above) followed by a text value. -The value may contain interpolated CSV fields, +The value may contain interpolated CSV fields, referenced by their 1-based position in the CSV record (`%N`), or by the name they were given in the fields list (`%CSVFIELDNAME`). Some examples: @@ -554,7 +554,7 @@ banking thru software ## `end` This rule can be used inside [if blocks](#if) (only), to make hledger stop -reading this CSV file and move on to the next input file, or to command execution. +reading this CSV file and move on to the next input file, or to command execution. Eg: ```rules # ignore everything following the first empty record @@ -641,7 +641,7 @@ Balance assertions generated by [assigning to balanceN](#posting-field-names) are of the simple `=` type by default, which is a [single-commodity](https://hledger.org/journal.html#assertions-and-commodities), [subaccount-excluding](https://hledger.org/journal.html#assertions-and-subaccounts) assertion. -You may find the subaccount-including variants more useful, +You may find the subaccount-including variants more useful, eg if you have created some virtual subaccounts of checking to help with budgeting. You can select a different type of assertion with the `balance-type` rule: ```rules @@ -752,11 +752,11 @@ A posting amount can be set in one of these ways: `amountN` (posting N's amount) or `amount` (posting 1's amount) - by assigning to `amountN-in` and `amountN-out` (or `amount-in` and `amount-out`). - For each CSV record, whichever of these has a non-zero value will be used, with appropriate sign. + For each CSV record, whichever of these has a non-zero value will be used, with appropriate sign. If both contain a non-zero value, this may not work. - by assigning to `balanceN` (or `balance`) instead of the above, - setting the amount indirectly via a + setting the amount indirectly via a [balance assignment](journal.html#balance-assignments). If you do this the default account name may be wrong, so you should set that explicitly. diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index 52ca4565a..b619657d0 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -33,8 +33,8 @@ create and update it. Many users, though, edit the journal file with a text editor, and track changes with a version control system such as git. Editor addons such as -ledger-mode or hledger-mode for Emacs, -vim-ledger for Vim, +ledger-mode or hledger-mode for Emacs, +vim-ledger for Vim, and hledger-vscode for Visual Studio Code, make this easier, adding colour, formatting, tab completion, and useful commands. See [Editor configuration](editors.html) at hledger.org for the full list. @@ -93,7 +93,7 @@ Each transaction is recorded as a journal entry, beginning with a [simple date](#simple-dates) in column 0. This can be followed by any of the following optional fields, separated by spaces: -- a [status](#status) character (empty, `!`, or `*`) +- a [status](#status) character (empty, `!`, or `*`) - a code (any short number or text, enclosed in parentheses) - a description (any remaining text until end of line or a semicolon) - a comment (any remaining text following a semicolon until end of line, @@ -116,7 +116,7 @@ Here's a simple journal file containing one transaction: Dates in the journal file use *simple dates* format: `YYYY-MM-DD` or `YYYY/MM/DD` or `YYYY.MM.DD`, with leading zeros optional. The year may be omitted, in which case it will be inferred from the context: -the current transaction, the default year set with a [default year directive](#default-year), +the current transaction, the default year set with a [default year directive](#default-year), or the current date when the command is run. Some examples: `2010-01-31`, `2010/01/31`, `2010.1.31`, `1/31`. @@ -145,7 +145,7 @@ default, but with the `--date2` flag (or `--aux-date` or `--effective`), the secondary (right) date will be used instead. The meaning of secondary dates is up to you, but it's best to follow a -consistent rule. Eg "primary = the bank's clearing date, secondary = +consistent rule. Eg "primary = the bank's clearing date, secondary = date the transaction was initiated, if different", as shown here: ```journal 2010/2/23=2/19 movie ticket @@ -200,9 +200,9 @@ the transaction and DATE2 infers its year from DATE. ## Status -Transactions, or individual postings within a transaction, +Transactions, or individual postings within a transaction, can have a status mark, which is a single character before -the transaction description or posting account name, +the transaction description or posting account name, separated from it by a space, indicating one of three statuses: | mark   | status | @@ -243,7 +243,7 @@ and no flags to see the most up-to-date state of your finances. A transaction's description is the rest of the line following the date and status mark (or until a comment begins). Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you wish, -or left blank. Transaction descriptions can be queried, unlike [comments](#comments). +or left blank. Transaction descriptions can be queried, unlike [comments](#comments). ### Payee and note @@ -263,7 +263,7 @@ You can attach comments to a transaction by writing them after the description and/or indented on the following lines (before the postings). Similarly, you can attach comments to an individual posting by writing them after the amount and/or indented on the -following lines. +following lines. Transaction and posting comments must begin with a semicolon (`;`). Some examples: @@ -334,15 +334,15 @@ Tags are like Ledger's feature, except hledger's tag values are simple strings. ## Postings - -A posting is an addition of some amount to, or removal of some amount from, an account. + +A posting is an addition of some amount to, or removal of some amount from, an account. Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by: - (optional) a [status](#status) character (empty, `!`, or `*`), followed by a space - (required) an [account name](#account-names) (any text, optionally containing **single spaces**, until end of line or a double space) -- (optional) **two or more spaces** or tabs followed by an [amount](#amounts). +- (optional) **two or more spaces** or tabs followed by an [amount](#amounts). -Positive amounts are being added to the account, negative amounts are being removed. +Positive amounts are being added to the account, negative amounts are being removed. The amounts within a transaction must always sum up to zero. As a convenience, one amount may be left blank; it will be inferred so as to balance the transaction. @@ -377,7 +377,7 @@ to zero (separately from other postings). Eg: assets:cash $-10 ; <- these balance expenses:food $7 ; <- expenses:food $3 ; <- - [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:budget:food] $-10 ; <- and these balance [assets:checking:available] $10 ; <- (something:else) $5 ; <- not required to balance ``` @@ -403,7 +403,7 @@ Account names can be [aliased](#rewriting-accounts). After the account name, there is usually an amount. (Important: between account name and amount, there must be **two or more spaces**.) -hledger's amount format is flexible, supporting several international formats. +hledger's amount format is flexible, supporting several international formats. Here are some examples. Amounts have a number (the "quantity"): @@ -442,7 +442,7 @@ A decimal mark (decimal point) can be written with a period or a comma: 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 @@ -458,7 +458,7 @@ hledger will treat them both as decimal marks by default (cf [#793](https://github.com/simonmichael/hledger/issues/793)). If you use digit group marks, to prevent confusion and undetected typos -we recommend you write [commodity directives](#declaring-commodities) +we recommend you write [commodity directives](#declaring-commodities) 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, @@ -533,7 +533,7 @@ There are several ways to record a transaction price: (Ledger users: Ledger uses a different [syntax](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices) for fixed prices, `{=UNITPRICE}`, which hledger currently ignores). -Use the [`-B/--cost`](hledger.html#reporting-options) flag to convert +Use the [`-B/--cost`](hledger.html#reporting-options) flag to convert amounts to their transaction price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). Eg here is how -B affects the balance report for the example above: @@ -548,7 +548,7 @@ $ hledger bal -N --flat -B ``` Note -B is sensitive to the order of postings when a transaction price is inferred: -the inferred price will be in the commodity of the last amount. +the inferred price will be in the commodity of the last amount. So if example 3's postings are reversed, while the transaction is equivalent, -B shows something different: @@ -565,10 +565,10 @@ $ hledger bal -N --flat -B ## Balance Assertions -hledger supports +hledger supports [Ledger-style balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions) in journal files. -These look like, for example, `= EXPECTEDBALANCE` following a posting's amount. +These look like, for example, `= EXPECTEDBALANCE` following a posting's amount. Eg here we assert the expected dollar balance in accounts a and b after each posting: @@ -624,17 +624,17 @@ instead. The asserted balance must be a simple single-commodity amount, and in fact the assertion checks only this commodity's balance within the -(possibly multi-commodity) account balance. +(possibly multi-commodity) account balance. This is how assertions work in Ledger also. -We could call this a "partial" balance assertion. +We could call this a "partial" balance assertion. -To assert the balance of more than one commodity in an account, +To assert the balance of more than one commodity in an account, you can write multiple postings, each asserting one commodity's balance. -You can make a stronger "total" balance assertion by writing a -double equals sign (`== EXPECTEDBALANCE`). -This asserts that there are no other unasserted commodities in the account -(or, that their balance is 0). +You can make a stronger "total" balance assertion by writing a +double equals sign (`== EXPECTEDBALANCE`). +This asserts that there are no other unasserted commodities in the account +(or, that their balance is 0). ``` journal 2013/1/1 @@ -685,9 +685,9 @@ and because [balance *assignments*](#balance-assignments) do use them (see below ### Assertions and subaccounts -The balance assertions above (`=` and `==`) do not count the balance -from subaccounts; they check the account's exclusive balance only. -You can assert the balance including subaccounts by writing `=*` or `==*`, eg: +The balance assertions above (`=` and `==`) do not count the balance +from subaccounts; they check the account's exclusive balance only. +You can assert the balance including subaccounts by writing `=*` or `==*`, eg: ```journal 2019/1/1 @@ -718,7 +718,7 @@ These are like [balance assertions](#balance-assertions), but with no posting am instead it is calculated automatically so as to satisfy the assertion. This can be a convenience during data entry, eg when setting opening balances: ```journal -; starting a new journal, set asset account balances +; starting a new journal, set asset account balances 2016/1/1 opening balances assets:checking = $409.32 assets:savings = $735.24 @@ -733,7 +733,7 @@ or when adjusting a balance to reality: expenses:misc ``` -The calculated amount depends on the account's balance in the commodity at that point +The calculated amount depends on the account's balance in the commodity at that point (which depends on the previously-dated postings of the commodity to that account since the last balance assertion or assignment). Note that using balance assignments makes your journal a little less explicit; @@ -759,10 +759,10 @@ $ hledger print --explicit A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. -hledger's directives are based on a subset of Ledger's, but there are many differences +hledger's directives are based on a subset of Ledger's, but there are many differences (and also some differences between hledger versions). -Directives' behaviour and interactions can get a little bit [complex](https://github.com/simonmichael/hledger/issues/793), +Directives' behaviour and interactions can get a little bit [complex](https://github.com/simonmichael/hledger/issues/793), so here is a table summarising the directives and their effects, with links to more detailed docs. @@ -818,7 +818,7 @@ Some directives have multiple effects. If you have a journal made up of multiple files, or pass multiple -f options on the command line, note that directives which affect input typically last only until the end of their defining file. This provides more simplicity and predictability, eg reports are not changed by writing file options in a different order. -It can be surprising at times though. +It can be surprising at times though. @@ -1547,7 +1547,7 @@ directory. These are typically prototypes and not guaranteed to work. # ENVIRONMENT **COLUMNS** -The screen width used by the register command. +The screen width used by the register command. Default: the full terminal width. m4_dnl Standard LEDGER_FILE description: @@ -1584,17 +1584,17 @@ Here are some issues you might encounter when you run hledger [mail list](http://list.hledger.org) or [bug tracker](http://bugs.hledger.org)): -**Successfully installed, but "No command 'hledger' found"** +**Successfully installed, but "No command 'hledger' found"**\ stack and cabal install binaries into a special directory, which should be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. -**I set a custom LEDGER_FILE, but hledger is still using the default file** +**I set a custom LEDGER_FILE, but hledger is still using the default file**\ `LEDGER_FILE` should be a real environment variable, not just a shell variable. The command `env | grep LEDGER_FILE` should show it. You may need to use `export`. Here's an [explanation](http://stackoverflow.com/a/7411509). -**"Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors** +**"Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors**\ In order to handle non-ascii letters and symbols (like £), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that @@ -1638,4 +1638,3 @@ $ LANG=fr_FR.utf8 hledger -f my.journal print Note some platforms allow variant locale spellings, but not all (ubuntu accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`). -