From 9759b5c8672551e1fdcd74fa2435fad75287dc74 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Mon, 16 Jan 2017 16:26:51 -0800 Subject: [PATCH] doc: clarify tags [ci skip] --- hledger-lib/doc/hledger_journal.5 | 59 ++++++++++---- hledger-lib/doc/hledger_journal.5.info | 102 ++++++++++++++---------- hledger-lib/doc/hledger_journal.5.m4.md | 37 ++++++--- hledger-lib/doc/hledger_journal.5.txt | 37 ++++++--- 4 files changed, 157 insertions(+), 78 deletions(-) diff --git a/hledger-lib/doc/hledger_journal.5 b/hledger-lib/doc/hledger_journal.5 index 6459dd436..cbf3919df 100644 --- a/hledger-lib/doc/hledger_journal.5 +++ b/hledger-lib/doc/hledger_journal.5 @@ -613,30 +613,57 @@ end\ comment .fi .SS Tags .PP -A \f[I]tag\f[] is a word followed by a full colon inside a transaction -or posting comment. -You can write multiple tags, comma separated. -Eg: \f[C];\ a\ comment\ containing\ sometag:,\ anothertag:\f[]. -.PD 0 -.P -.PD -You can search for tags with the \f[C]tag:\f[] query, or pivot on them -with \f[C]\-\-pivot\ TAG\f[]. +Tags are a way to add extra labels or labelled data to postings and +transactions, which you can then search or pivot on. .PP -A tag can also have a value, which is any text between the colon and the -next comma or newline, excluding leading/trailing whitespace. -(So hledger tag values can not contain commas or newlines). +A simple tag is a word (which may contain hyphens) followed by a full +colon, written inside a transaction or posting comment line: +.IP +.nf +\f[C] +2017/1/16\ bought\ groceries\ \ \ \ ;\ sometag: +\f[] +.fi +.PP +Tags can have a value, which is the text after the colon, up to the next +comma or end of line, with leading/trailing whitespace removed: +.IP +.nf +\f[C] +\ \ \ \ expenses:food\ \ \ \ $10\ \ \ ;\ a\-posting\-tag:\ the\ tag\ value +\f[] +.fi +.PP +Note this means hledger\[aq]s tag values can not contain commas or +newlines. +Ending at commas means you can write multiple short tags on one line, +comma separated: +.IP +.nf +\f[C] +\ \ \ \ assets:checking\ \ \ \ \ \ \ ;\ a\ comment\ containing\ tag1:,\ tag2:\ some\ value\ ... +\f[] +.fi +.PP +Here, +.IP \[bu] 2 +"\f[C]a\ comment\ containing\f[]" is just comment text, not a tag +.IP \[bu] 2 +"\f[C]tag1\f[]" is a tag with no value +.IP \[bu] 2 +"\f[C]tag2\f[]" is another tag, whose value is +"\f[C]some\ value\ ...\f[]" .PP Tags in a transaction comment affect the transaction and all of its postings, while tags in a posting comment affect only that posting. -For example, the following transaction has three tags (A, TAG2, -third\-tag) and the posting has four (A, TAG2, third\-tag, -posting\-tag): +For example, the following transaction has three tags (\f[C]A\f[], +\f[C]TAG2\f[], \f[C]third\-tag\f[]) and the posting has four (those plus +\f[C]posting\-tag\f[]): .IP .nf \f[C] 1/1\ a\ transaction\ \ ;\ A:,\ TAG2: -\ \ \ \ ;\ third\-tag:\ a\ third\ transaction\ tag,\ this\ time\ with\ a\ value +\ \ \ \ ;\ third\-tag:\ a\ third\ transaction\ tag,\ <\-\ with\ a\ value \ \ \ \ (a)\ \ $1\ \ ;\ posting\-tag: \f[] .fi diff --git a/hledger-lib/doc/hledger_journal.5.info b/hledger-lib/doc/hledger_journal.5.info index f81e1b758..65e013cdf 100644 --- a/hledger-lib/doc/hledger_journal.5.info +++ b/hledger-lib/doc/hledger_journal.5.info @@ -638,24 +638,44 @@ File: hledger_journal.5.info, Node: Tags, Next: Directives, Prev: Comments, 1.10 Tags ========= -A _tag_ is a word followed by a full colon inside a transaction or -posting comment. You can write multiple tags, comma separated. Eg: `; a -comment containing sometag:, anothertag:'. -You can search for tags with the `tag:' query, or pivot on them with -`--pivot TAG'. +Tags are a way to add extra labels or labelled data to postings and +transactions, which you can then search or pivot on. - A tag can also have a value, which is any text between the colon and -the next comma or newline, excluding leading/trailing whitespace. (So -hledger tag values can not contain commas or newlines). + A simple tag is a word (which may contain hyphens) followed by a full +colon, written inside a transaction or posting comment line: + + +2017/1/16 bought groceries ; sometag: + + Tags can have a value, which is the text after the colon, up to the +next comma or end of line, with leading/trailing whitespace removed: + + + expenses:food $10 ; a-posting-tag: the tag value + + Note this means hledger's tag values can not contain commas or +newlines. Ending at commas means you can write multiple short tags on +one line, comma separated: + + + assets:checking ; a comment containing tag1:, tag2: some value ... + + Here, + + * "`a comment containing'" is just comment text, not a tag + + * "`tag1'" is a tag with no value + + * "`tag2'" is another tag, whose value is "`some value ...'" Tags in a transaction comment affect the transaction and all of its postings, while tags in a posting comment affect only that posting. For -example, the following transaction has three tags (A, TAG2, third-tag) -and the posting has four (A, TAG2, third-tag, posting-tag): +example, the following transaction has three tags (`A', `TAG2', +`third-tag') and the posting has four (those plus `posting-tag'): 1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, this time with a value + ; third-tag: a third transaction tag, <- with a value (a) $1 ; posting-tag: Tags are like Ledger's metadata feature, except hledger's tag values @@ -1051,35 +1071,35 @@ Node: Comments21085 Ref: #comments21207 Node: Tags22319 Ref: #tags22439 -Node: Implicit tags23427 -Ref: #implicit-tags23535 -Node: Directives24054 -Ref: #directives24169 -Node: Account aliases24362 -Ref: #account-aliases24508 -Node: Basic aliases25110 -Ref: #basic-aliases25255 -Node: Regex aliases25943 -Ref: #regex-aliases26113 -Node: Multiple aliases26883 -Ref: #multiple-aliases27057 -Node: end aliases27553 -Ref: #end-aliases27695 -Node: account directive27797 -Ref: #account-directive27979 -Node: apply account directive28275 -Ref: #apply-account-directive28473 -Node: Multi-line comments29133 -Ref: #multi-line-comments29325 -Node: commodity directive29452 -Ref: #commodity-directive29638 -Node: Default commodity30511 -Ref: #default-commodity30686 -Node: Default year31222 -Ref: #default-year31389 -Node: Including other files31812 -Ref: #including-other-files31971 -Node: EDITOR SUPPORT32367 -Ref: #editor-support32487 +Node: Implicit tags23874 +Ref: #implicit-tags23982 +Node: Directives24501 +Ref: #directives24616 +Node: Account aliases24809 +Ref: #account-aliases24955 +Node: Basic aliases25557 +Ref: #basic-aliases25702 +Node: Regex aliases26390 +Ref: #regex-aliases26560 +Node: Multiple aliases27330 +Ref: #multiple-aliases27504 +Node: end aliases28000 +Ref: #end-aliases28142 +Node: account directive28244 +Ref: #account-directive28426 +Node: apply account directive28722 +Ref: #apply-account-directive28920 +Node: Multi-line comments29580 +Ref: #multi-line-comments29772 +Node: commodity directive29899 +Ref: #commodity-directive30085 +Node: Default commodity30958 +Ref: #default-commodity31133 +Node: Default year31669 +Ref: #default-year31836 +Node: Including other files32259 +Ref: #including-other-files32418 +Node: EDITOR SUPPORT32814 +Ref: #editor-support32934  End Tag Table diff --git a/hledger-lib/doc/hledger_journal.5.m4.md b/hledger-lib/doc/hledger_journal.5.m4.md index 12743200d..28a971c81 100644 --- a/hledger-lib/doc/hledger_journal.5.m4.md +++ b/hledger-lib/doc/hledger_journal.5.m4.md @@ -502,24 +502,39 @@ end comment ## Tags -A *tag* is a word followed by a full colon inside a transaction or -posting [comment](#comments). You can write multiple tags, comma -separated. Eg: `; a comment containing sometag:, anothertag:`. -You can search for tags with the [`tag:` query](/hledger.html#queries), -or pivot on them with [`--pivot TAG`](/hledger.html#pivoting). +Tags are a way to add extra labels or labelled data to postings and transactions, +which you can then [search](/journal.html#queries) or [pivot](/hledger.html#pivoting) on. -A tag can also have a value, which is any text between the colon and -the next comma or newline, excluding leading/trailing whitespace. -(So hledger tag values can not contain commas or newlines). +A simple tag is a word (which may contain hyphens) followed by a full colon, +written inside a transaction or posting [comment](#comments) line: +```journal +2017/1/16 bought groceries ; sometag: +``` + +Tags can have a value, which is the text after the colon, up to the next comma or end of line, with leading/trailing whitespace removed: +```journal + expenses:food $10 ; a-posting-tag: the tag value +``` + +Note this means hledger's tag values can not contain commas or newlines. +Ending at commas means you can write multiple short tags on one line, comma separated: +```journal + assets:checking ; a comment containing tag1:, tag2: some value ... +``` +Here, + +- "`a comment containing `" is just comment text, not a tag +- "`tag1`" is a tag with no value +- "`tag2`" is another tag, whose value is "`some value ...`" Tags in a transaction comment affect the transaction and all of its postings, while tags in a posting comment affect only that posting. -For example, the following transaction has three tags (A, TAG2, third-tag) -and the posting has four (A, TAG2, third-tag, posting-tag): +For example, the following transaction has three tags (`A`, `TAG2`, `third-tag`) +and the posting has four (those plus `posting-tag`): ```journal 1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, this time with a value + ; third-tag: a third transaction tag, <- with a value (a) $1 ; posting-tag: ``` diff --git a/hledger-lib/doc/hledger_journal.5.txt b/hledger-lib/doc/hledger_journal.5.txt index aa2fff0d9..e0ee3f43a 100644 --- a/hledger-lib/doc/hledger_journal.5.txt +++ b/hledger-lib/doc/hledger_journal.5.txt @@ -468,23 +468,40 @@ FILE FORMAT ; a journal comment (because not indented) Tags - A tag is a word followed by a full colon inside a transaction or post- - ing comment. You can write multiple tags, comma separated. Eg: - ; a comment containing sometag:, anothertag:. - You can search for tags with the tag: query, or pivot on them with - --pivot TAG. + Tags are a way to add extra labels or labelled data to postings and + transactions, which you can then search or pivot on. - A tag can also have a value, which is any text between the colon and - the next comma or newline, excluding leading/trailing whitespace. (So - hledger tag values can not contain commas or newlines). + A simple tag is a word (which may contain hyphens) followed by a full + colon, written inside a transaction or posting comment line: + + 2017/1/16 bought groceries ; sometag: + + Tags can have a value, which is the text after the colon, up to the + next comma or end of line, with leading/trailing whitespace removed: + + expenses:food $10 ; a-posting-tag: the tag value + + Note this means hledger's tag values can not contain commas or new- + lines. Ending at commas means you can write multiple short tags on one + line, comma separated: + + assets:checking ; a comment containing tag1:, tag2: some value ... + + Here, + + o "a comment containing" is just comment text, not a tag + + o "tag1" is a tag with no value + + o "tag2" is another tag, whose value is "some value ..." Tags in a transaction comment affect the transaction and all of its postings, while tags in a posting comment affect only that posting. For example, the following transaction has three tags (A, TAG2, - third-tag) and the posting has four (A, TAG2, third-tag, posting-tag): + third-tag) and the posting has four (those plus posting-tag): 1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, this time with a value + ; third-tag: a third transaction tag, <- with a value (a) $1 ; posting-tag: Tags are like Ledger's metadata feature, except hledger's tag values