doc: tweak description/payee/note docs (#598, #608)

hledger-lib/doc/hledger_journal.5

@@ -303,23 +303,20 @@ With this scheme, you would use \f[C]\-PC\f[] to see the current balance
 at your bank, \f[C]\-U\f[] to see things which will probably hit your
 bank soon (like uncashed checks), and no flags to see the most
 up\-to\-date state of your finances.
-.SS Description, payee and note
+.SS Description
 .PP
-As mentioned, a transaction\[aq]s description is the rest of the line
+A transaction\[aq]s description is the rest of the line following the
-following the date and status mark (or, the rest of line until a comment
+date and status mark (or until a comment begins).
-begins).
 Sometimes called the "narration" in traditional bookkeeping, it can be
 used for whatever you wish, or left blank.
-The description can be queried, unlike comments.
+Transaction descriptions can be queried, unlike comments.
+.SS Payee and note
 .PP
-Including a \f[C]|\f[] (pipe) character in the description will
+You can optionally include a \f[C]|\f[] (pipe) character in a
-subdivide it into a payee/payer name (on the left) and additional notes
+description to subdivide it into a payee/payer name on the left and
-(on the right).
+additional notes on the right.
-This is entirely optional, but it can allow more precise
+This may be worthwhile if you need to do more precise querying and
-.PD 0
+pivoting by payee.
-.P
-.PD
-querying and pivoting.
 .SS Account names
 .PP
 Account names typically have several parts separated by a full colon,

hledger-lib/doc/hledger_journal.5.info

@@ -71,7 +71,7 @@ File: hledger_journal.5.info,  Node: FILE FORMAT,  Next: EDITOR SUPPORT,  Prev:
 * Postings::
 * Dates::
 * Status::
-* Description payee and note::
+* Description::
 * Account names::
 * Amounts::
 * Virtual Postings::
@@ -234,7 +234,7 @@ characters in this way.  With this syntax, DATE infers its year from the
 transaction and DATE2 infers its year from DATE.
 
 
-File: hledger_journal.5.info,  Node: Status,  Next: Description payee and note,  Prev: Dates,  Up: FILE FORMAT
+File: hledger_journal.5.info,  Node: Status,  Next: Description,  Prev: Dates,  Up: FILE FORMAT
 
 1.4 Status
 ==========
@@ -284,24 +284,33 @@ your bank, '-U' to see things which will probably hit your bank soon
 your finances.
 
 
-File: hledger_journal.5.info,  Node: Description payee and note,  Next: Account names,  Prev: Status,  Up: FILE FORMAT
+File: hledger_journal.5.info,  Node: Description,  Next: Account names,  Prev: Status,  Up: FILE FORMAT
 
-1.5 Description, payee and note
+1.5 Description
-===============================
+===============
 
-As mentioned, a transaction's description is the rest of the line
+A transaction's description is the rest of the line following the date
-following the date and status mark (or, the rest of line until a comment
+and status mark (or until a comment begins).  Sometimes called the
-begins).  Sometimes called the "narration" in traditional bookkeeping,
+"narration" in traditional bookkeeping, it can be used for whatever you
-it can be used for whatever you wish, or left blank.  The description
+wish, or left blank.  Transaction descriptions can be queried, unlike
-can be queried, unlike comments.
+comments.
+* Menu:
 
-   Including a '|' (pipe) character in the description will subdivide it
+* Payee and note::
-into a payee/payer name (on the left) and additional notes (on the
-right).  This is entirely optional, but it can allow more precise
-querying and pivoting.
 
 
-File: hledger_journal.5.info,  Node: Account names,  Next: Amounts,  Prev: Description payee and note,  Up: FILE FORMAT
+File: hledger_journal.5.info,  Node: Payee and note,  Up: Description
+
+1.5.1 Payee and note
+--------------------
+
+You can optionally include a '|' (pipe) character in a description to
+subdivide it into a payee/payer name on the left and additional notes on
+the right.  This may be worthwhile if you need to do more precise
+querying and pivoting by payee.
+
+
+File: hledger_journal.5.info,  Node: Account names,  Next: Amounts,  Prev: Description,  Up: FILE FORMAT
 
 1.6 Account names
 =================
@@ -1054,81 +1063,83 @@ Tag Table:
 Node: Top78
 Node: FILE FORMAT2380
 Ref: #file-format2506
-Node: Transactions2744
+Node: Transactions2729
-Ref: #transactions2867
+Ref: #transactions2852
-Node: Postings3551
+Node: Postings3536
-Ref: #postings3680
+Ref: #postings3665
-Node: Dates4675
+Node: Dates4660
-Ref: #dates4792
+Ref: #dates4777
-Node: Simple dates4857
+Node: Simple dates4842
-Ref: #simple-dates4985
+Ref: #simple-dates4970
-Node: Secondary dates5351
+Node: Secondary dates5336
-Ref: #secondary-dates5507
+Ref: #secondary-dates5492
-Node: Posting dates7070
+Node: Posting dates7055
-Ref: #posting-dates7201
+Ref: #posting-dates7186
-Node: Status8575
+Node: Status8560
-Ref: #status8712
+Ref: #status8682
-Node: Description payee and note10426
+Node: Description10396
-Ref: #description-payee-and-note10613
+Ref: #description10536
-Node: Account names11157
+Node: Payee and note10855
-Ref: #account-names11317
+Ref: #payee-and-note10971
-Node: Amounts11804
+Node: Account names11213
-Ref: #amounts11942
+Ref: #account-names11358
-Node: Virtual Postings14043
+Node: Amounts11845
-Ref: #virtual-postings14204
+Ref: #amounts11983
-Node: Balance Assertions15424
+Node: Virtual Postings14084
-Ref: #balance-assertions15601
+Ref: #virtual-postings14245
-Node: Assertions and ordering16497
+Node: Balance Assertions15465
-Ref: #assertions-and-ordering16685
+Ref: #balance-assertions15642
-Node: Assertions and included files17385
+Node: Assertions and ordering16538
-Ref: #assertions-and-included-files17628
+Ref: #assertions-and-ordering16726
-Node: Assertions and multiple -f options17961
+Node: Assertions and included files17426
-Ref: #assertions-and-multiple--f-options18217
+Ref: #assertions-and-included-files17669
-Node: Assertions and commodities18349
+Node: Assertions and multiple -f options18002
-Ref: #assertions-and-commodities18586
+Ref: #assertions-and-multiple--f-options18258
-Node: Assertions and subaccounts19282
+Node: Assertions and commodities18390
-Ref: #assertions-and-subaccounts19516
+Ref: #assertions-and-commodities18627
-Node: Assertions and virtual postings20037
+Node: Assertions and subaccounts19323
-Ref: #assertions-and-virtual-postings20246
+Ref: #assertions-and-subaccounts19557
-Node: Balance Assignments20388
+Node: Assertions and virtual postings20078
-Ref: #balance-assignments20559
+Ref: #assertions-and-virtual-postings20287
-Node: Prices21678
+Node: Balance Assignments20429
-Ref: #prices21813
+Ref: #balance-assignments20600
-Node: Transaction prices21864
+Node: Prices21719
-Ref: #transaction-prices22011
+Ref: #prices21854
-Node: Market prices24167
+Node: Transaction prices21905
-Ref: #market-prices24304
+Ref: #transaction-prices22052
-Node: Comments25264
+Node: Market prices24208
-Ref: #comments25388
+Ref: #market-prices24345
-Node: Tags26501
+Node: Comments25305
-Ref: #tags26621
+Ref: #comments25429
-Node: Directives28023
+Node: Tags26542
-Ref: #directives28138
+Ref: #tags26662
-Node: Account aliases28331
+Node: Directives28064
-Ref: #account-aliases28477
+Ref: #directives28179
-Node: Basic aliases29081
+Node: Account aliases28372
-Ref: #basic-aliases29226
+Ref: #account-aliases28518
-Node: Regex aliases29916
+Node: Basic aliases29122
-Ref: #regex-aliases30086
+Ref: #basic-aliases29267
-Node: Multiple aliases30801
+Node: Regex aliases29957
-Ref: #multiple-aliases30975
+Ref: #regex-aliases30127
-Node: end aliases31473
+Node: Multiple aliases30842
-Ref: #end-aliases31615
+Ref: #multiple-aliases31016
-Node: account directive31716
+Node: end aliases31514
-Ref: #account-directive31898
+Ref: #end-aliases31656
-Node: apply account directive32194
+Node: account directive31757
-Ref: #apply-account-directive32392
+Ref: #account-directive31939
-Node: Multi-line comments33051
+Node: apply account directive32235
-Ref: #multi-line-comments33243
+Ref: #apply-account-directive32433
-Node: commodity directive33371
+Node: Multi-line comments33092
-Ref: #commodity-directive33557
+Ref: #multi-line-comments33284
-Node: Default commodity34429
+Node: commodity directive33412
-Ref: #default-commodity34604
+Ref: #commodity-directive33598
-Node: Default year35141
+Node: Default commodity34470
-Ref: #default-year35308
+Ref: #default-commodity34645
-Node: Including other files35731
+Node: Default year35182
-Ref: #including-other-files35890
+Ref: #default-year35349
-Node: EDITOR SUPPORT36287
+Node: Including other files35772
-Ref: #editor-support36407
+Ref: #including-other-files35931
+Node: EDITOR SUPPORT36328
+Ref: #editor-support36448
 
 End Tag Table

hledger-lib/doc/hledger_journal.5.m4.md

@@ -229,17 +229,18 @@ With this scheme, you would use
 `-U` to see things which will probably hit your bank soon (like uncashed checks),
 and no flags to see the most up-to-date state of your finances.
 
-## Description, payee and note
+## Description
 
-As mentioned, a transaction's description is the rest of the line following the date and status mark
+A transaction's description is the rest of the line following the date and status mark (or until a comment begins).
-(or, the rest of line until a comment begins).
 Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you wish,
-or left blank. The description can be queried, unlike [comments](#comments). 
+or left blank. Transaction descriptions can be queried, unlike [comments](#comments). 
 
-Including a `|` (pipe) character in the description will subdivide it 
+### Payee and note
-into a payee/payer name (on the left) and additional notes (on the right).
+
-This is entirely optional, but it can allow more precise  
+You can optionally include a `|` (pipe) character in a description to 
-[querying](/hledger.html#queries) and [pivoting](/hledger.html#pivoting).
+subdivide it into a payee/payer name on the left and additional notes on the right.
+This may be worthwhile if you need to do more precise
+[querying](/hledger.html#queries) and [pivoting](/hledger.html#pivoting) by payee.
 
 ## Account names
 

hledger-lib/doc/hledger_journal.5.txt

@@ -221,17 +221,18 @@ FILE FORMAT
        uncashed checks), and no flags to see the most up-to-date state of your
        finances.
 
-   Description, payee and note
+   Description
-       As  mentioned, a transaction's description is the rest of the line fol-
+       A  transaction's description is the rest of the line following the date
-       lowing the date and status mark (or, the rest of line until  a  comment
+       and status mark (or until a  comment  begins).   Sometimes  called  the
-       begins).   Sometimes called the "narration" in traditional bookkeeping,
+       "narration" in traditional bookkeeping, it can be used for whatever you
-       it can be used for whatever you wish, or left blank.   The  description
+       wish, or left blank.  Transaction descriptions can be  queried,  unlike
-       can be queried, unlike comments.
+       comments.
 
-       Including  a  |  (pipe)  character in the description will subdivide it
+   Payee and note
-       into a payee/payer name (on the left)  and  additional  notes  (on  the
+       You  can  optionally  include  a | (pipe) character in a description to
-       right).  This is entirely optional, but it can allow more precise
+       subdivide it into a payee/payer name on the left and  additional  notes
-       querying and pivoting.
+       on  the  right.   This may be worthwhile if you need to do more precise
+       querying and pivoting by payee.
 
    Account names
        Account names typically have several parts separated by a  full  colon,

hledger/doc/queries.m4.md

@@ -54,7 +54,7 @@ quoting to hide it from the shell, so eg do: `hledger print cur:'\$'`
 or `hledger print cur:\\$`.
 
 **`desc:REGEX`**
-: match transaction [descriptions](/manual.html#description-payee-and-note).
+: match transaction descriptions.
 
 **`date:PERIODEXPR`**
 : match dates within the specified period.
@@ -69,11 +69,11 @@ If the `--date2` command line flag is present, this matches [secondary dates](ma
 : match (or display, depending on command) accounts at or above this depth
 
 **`note:REGEX`**
-: match transaction [notes](/manual.html#description-payee-and-note)
+: match transaction [notes](/manual.html#payee-and-note)
 (part of description right of `|`, or whole description when there's no `|`)
 
 **`payee:REGEX`**
-: match transaction [payee/payer names](/manual.html#description-payee-and-note)
+: match transaction [payee/payer names](/manual.html#payee-and-note)
 (part of description left of `|`, or whole description when there's no `|`)
 
 **`real:, real:0`**