doc: clarify tags

[ci skip]

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

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

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:
 ```
 

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