doc:Tags: improve the Special tags list, and the tags doc generally

Author: simonmichael

hledger/hledger.m4.md

@@ -1581,17 +1581,19 @@ except they may contain [tags](#tags), which are not ignored.
 
 <!-- same section name as Commands > tags, if reordering these update all #tags[-1] links -->
 
-Tags are a way to add extra labels or labelled data to transactions, postings, or accounts,
+Tags are a way to add extra labels or data fields to transactions, postings, or accounts,
 which you can then [search](#queries) or [pivot](#pivoting) on.
 
-They are written as a word (optionally hyphenated) immediately followed by a full colon,
-in a transaction or posting or account directive's [comment](#account-comments).
-(This is an exception to the usual rule that things in comments are ignored.)
-You can write multiple tags separated by comma, and/or you can add more comment lines
-and write more tags there.
+A tag is a word, optionally hyphenated, immediately followed by a full colon,
+in the [comment](#account-comments) of a transaction, a posting, or an account directive.
+Eg: `2024-01-01 a transaction   ; foo:`
+Note this is an exception to the usual rule that things in comments are ignored.
 
-Here five different tags are recorded: one on the checking account,
-two on the transaction, and two on the expenses posting:
+You can write multiple tags on one line, separated by comma.
+Or you can write each tag on its own comment line (no comma needed in this case).
+
+For example, here are five different tags: 
+one on the `assets:checking` account, two on the transaction, and two on the `expenses:food` posting:
 
 ```journal
 account assets:checking         ; accounttag:
@@ -1602,11 +1604,6 @@ account assets:checking         ; accounttag:
     expenses:food           $1  ; postingtag:, another-posting-tag:
 ```
 
-You can list tag names with `hledger tags [NAMEREGEX]`,
-or match by tag name with a `tag:NAMEREGEX` query.
-
-### Tag inheritance
-
 Postings also inherit tags from their transaction and their account.
 And transactions also acquire tags from their postings (and postings' accounts).
 So in the example above, the expenses posting effectively has all five tags
@@ -1615,46 +1612,60 @@ and the transaction also has all five tags (by acquiring from the expenses posti
 
 ### Tag names
 
-Tag names are currently not very clearly specified; any sequence of non-whitespace characters
-followed by a colon may work.
+Most non-whitespace characters are allowed in tag names. Eg `😀:` is a valid tag.
 
-The following tag names are generated by hledger or have special significance to hledger,
-so you may want to avoid using them yourself:
+You can list the tag names used in your journal with the [tags](#tags) command:\
+`hledger tags [NAMEREGEX]`
 
-- `balances`  -- a balance assertions transaction generated by close
-- `retain`    -- a retain earnings transaction generated by close
-- `start`     -- a opening balances, closing balances or balance assignment transaction generated by close
-- `generated-transaction`  -- a transaction generated by --forecast
-- `generated-posting`  -- a posting generated by --auto
-- `modified`  -- a transaction which has had postings added by --auto
-- `type`      -- declares an account's type in an account declaration
-- `t`         -- stores the (user defined, single letter) type of a 15m unit of time parsed from timedot format
+In commands which use a [query](#queries), you can match by tag name. Eg:\
+`hledger print tag:NAMEREGEX`
 
-Some additional tag names with an underscore prefix are used internally and not displayed
-in reports (but can be matched by queries):
+You can declare valid tag names with the [tag directive](#tag-directive) and then check them with the [check](#check) command.
 
-- `_generated-transaction`
-- `_generated-posting`
-- `_modified`
-- `_conversion-matched`
+### Special tags
 
+Some tag names have special significance to hledger, 
+and could produce an error message if you use them wrongly (the `date:` tag in particular).
+They are explained elsewhere, but here is a list for reference:
+
+<!-- keep synced with JournalChecks.hs -->
+```
+  date                   -- overrides a posting's date
+  date2                  -- overrides a posting's secondary date
+  type                   -- declares an account's type
+  t                      -- appears on postings generated by timedot letters
+  assert                 -- appears on txns generated by close --assert
+  retain                 -- appears on txns generated by close --retain
+  start                  -- appears on txns generated by close --migrate/--close/--open/--assign
+  generated-transaction  -- with --verbose-tags, appears on generated periodic txns
+  generated-posting      -- with --verbose-tags, appears on generated auto postings
+  modified               -- with --verbose-tags, appears on txns which have had auto postings added
+
+  Hidden tags used internally (and queryable):
+  _generated-transaction -- always exists on generated periodic txns
+  _generated-posting     -- always exists on generated auto postings
+  _modified              -- always exists on txns which have had auto postings added
+  _conversion-matched    -- exists on postings which have been matched with a nearby @/@@ cost notation
+```
 
 ### Tag values
 
-Tags can have a value, which is any text after the colon up until a comma or end of line
-(with surrounding whitespace removed).
-Note this means that hledger tag values can not contain commas.
+Tags can have a value, which is any text after the colon up until a comma or end of line, with surrounding whitespace removed.
+Ending at comma allows us to write multiple tags on one line, but also means that tag values can not contain commas.
+
 Eg in the following posting, the three tags' values are "value 1", "value 2", and "" (empty) respectively:
 ```journal
     expenses:food   $10    ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz
 ```
 
-Note that tags can be repeated, and are additive rather than overriding:
+Multiple tags with the same name are additive rather than overriding:
 when the same tag name is seen again with a new value, the new name:value pair is added to the tags.
-(It is not possible to override a tag's value or remove a tag.)
+It is not possible to override a previous tag's value or remove a tag.
+
+You can list all the values used for a particular tag in the journal with\
+`hledger tags TAGNAME --values`
 
-You can list a tag's values with `hledger tags TAGNAME --values`,
-or match by tag value with a `tag:NAMEREGEX=VALUEREGEX` query.
+You can match on tag values with a query like `tag:NAMEREGEX=VALUEREGEX`
 
 ## Directives
 
@@ -2299,7 +2310,7 @@ tag  item-id
 Any indented subdirectives are currently ignored.
 
 The ["tags" check](#check) will report an error if any undeclared tag name is used.
-It is quite easy to accidentally create a tag through normal use of colons in [comments](#comments];
+It is quite easy to accidentally create a tag through normal use of colons in [comments](#comments);
 if you want to prevent this, you can declare and check your tags .
 
 ## Periodic transactions