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

2017-09-05 14:06:43 -07:00 · 2017-09-05 14:06:43 -07:00 · efbbcda7e6
commit efbbcda7e6
parent 079e76a370
5 changed files with 269 additions and 259 deletions
--- a/hledger-lib/doc/hledger_journal.5
+++ b/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
-following the date and status mark (or, the rest of line until a comment
-begins).
+A transaction\[aq]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.
-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
-subdivide it into a payee/payer name (on the left) and additional notes
-(on the right).
-This is entirely optional, but it can allow more precise
-.PD 0
-.P
-.PD
-querying and pivoting.
+You can optionally include a \f[C]|\f[] (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.
 .SS Account names
 .PP
 Account names typically have several parts separated by a full colon,
--- a/hledger-lib/doc/hledger_journal.5.info
+++ b/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
-following the date and status mark (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.
+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.
+* Menu:

-   Including a '|' (pipe) character in the description will subdivide it
-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.
+* Payee and note::


-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
-Ref: #transactions2867
-Node: Postings3551
-Ref: #postings3680
-Node: Dates4675
-Ref: #dates4792
-Node: Simple dates4857
-Ref: #simple-dates4985
-Node: Secondary dates5351
-Ref: #secondary-dates5507
-Node: Posting dates7070
-Ref: #posting-dates7201
-Node: Status8575
-Ref: #status8712
-Node: Description payee and note10426
-Ref: #description-payee-and-note10613
-Node: Account names11157
-Ref: #account-names11317
-Node: Amounts11804
-Ref: #amounts11942
-Node: Virtual Postings14043
-Ref: #virtual-postings14204
-Node: Balance Assertions15424
-Ref: #balance-assertions15601
-Node: Assertions and ordering16497
-Ref: #assertions-and-ordering16685
-Node: Assertions and included files17385
-Ref: #assertions-and-included-files17628
-Node: Assertions and multiple -f options17961
-Ref: #assertions-and-multiple--f-options18217
-Node: Assertions and commodities18349
-Ref: #assertions-and-commodities18586
-Node: Assertions and subaccounts19282
-Ref: #assertions-and-subaccounts19516
-Node: Assertions and virtual postings20037
-Ref: #assertions-and-virtual-postings20246
-Node: Balance Assignments20388
-Ref: #balance-assignments20559
-Node: Prices21678
-Ref: #prices21813
-Node: Transaction prices21864
-Ref: #transaction-prices22011
-Node: Market prices24167
-Ref: #market-prices24304
-Node: Comments25264
-Ref: #comments25388
-Node: Tags26501
-Ref: #tags26621
-Node: Directives28023
-Ref: #directives28138
-Node: Account aliases28331
-Ref: #account-aliases28477
-Node: Basic aliases29081
-Ref: #basic-aliases29226
-Node: Regex aliases29916
-Ref: #regex-aliases30086
-Node: Multiple aliases30801
-Ref: #multiple-aliases30975
-Node: end aliases31473
-Ref: #end-aliases31615
-Node: account directive31716
-Ref: #account-directive31898
-Node: apply account directive32194
-Ref: #apply-account-directive32392
-Node: Multi-line comments33051
-Ref: #multi-line-comments33243
-Node: commodity directive33371
-Ref: #commodity-directive33557
-Node: Default commodity34429
-Ref: #default-commodity34604
-Node: Default year35141
-Ref: #default-year35308
-Node: Including other files35731
-Ref: #including-other-files35890
-Node: EDITOR SUPPORT36287
-Ref: #editor-support36407
+Node: Transactions2729
+Ref: #transactions2852
+Node: Postings3536
+Ref: #postings3665
+Node: Dates4660
+Ref: #dates4777
+Node: Simple dates4842
+Ref: #simple-dates4970
+Node: Secondary dates5336
+Ref: #secondary-dates5492
+Node: Posting dates7055
+Ref: #posting-dates7186
+Node: Status8560
+Ref: #status8682
+Node: Description10396
+Ref: #description10536
+Node: Payee and note10855
+Ref: #payee-and-note10971
+Node: Account names11213
+Ref: #account-names11358
+Node: Amounts11845
+Ref: #amounts11983
+Node: Virtual Postings14084
+Ref: #virtual-postings14245
+Node: Balance Assertions15465
+Ref: #balance-assertions15642
+Node: Assertions and ordering16538
+Ref: #assertions-and-ordering16726
+Node: Assertions and included files17426
+Ref: #assertions-and-included-files17669
+Node: Assertions and multiple -f options18002
+Ref: #assertions-and-multiple--f-options18258
+Node: Assertions and commodities18390
+Ref: #assertions-and-commodities18627
+Node: Assertions and subaccounts19323
+Ref: #assertions-and-subaccounts19557
+Node: Assertions and virtual postings20078
+Ref: #assertions-and-virtual-postings20287
+Node: Balance Assignments20429
+Ref: #balance-assignments20600
+Node: Prices21719
+Ref: #prices21854
+Node: Transaction prices21905
+Ref: #transaction-prices22052
+Node: Market prices24208
+Ref: #market-prices24345
+Node: Comments25305
+Ref: #comments25429
+Node: Tags26542
+Ref: #tags26662
+Node: Directives28064
+Ref: #directives28179
+Node: Account aliases28372
+Ref: #account-aliases28518
+Node: Basic aliases29122
+Ref: #basic-aliases29267
+Node: Regex aliases29957
+Ref: #regex-aliases30127
+Node: Multiple aliases30842
+Ref: #multiple-aliases31016
+Node: end aliases31514
+Ref: #end-aliases31656
+Node: account directive31757
+Ref: #account-directive31939
+Node: apply account directive32235
+Ref: #apply-account-directive32433
+Node: Multi-line comments33092
+Ref: #multi-line-comments33284
+Node: commodity directive33412
+Ref: #commodity-directive33598
+Node: Default commodity34470
+Ref: #default-commodity34645
+Node: Default year35182
+Ref: #default-year35349
+Node: Including other files35772
+Ref: #including-other-files35931
+Node: EDITOR SUPPORT36328
+Ref: #editor-support36448

 End Tag Table
--- a/hledger-lib/doc/hledger_journal.5.m4.md
+++ b/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
-(or, the rest of line until a comment begins).
+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. 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 
-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](/hledger.html#queries) and [pivoting](/hledger.html#pivoting).
+### 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](/hledger.html#queries) and [pivoting](/hledger.html#pivoting) by payee.

 ## Account names

--- a/hledger-lib/doc/hledger_journal.5.txt
+++ b/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
-       As  mentioned, a transaction's description is the rest of the line fol-
-       lowing the date and status mark (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.
+   Description
+       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.

-       Including  a  |  (pipe)  character in the description will subdivide it
-       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.
+   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.

   Account names
       Account names typically have several parts separated by a  full  colon,
--- a/hledger/doc/queries.m4.md
+++ b/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`**