Merge pull request #394 from thdox/add-to-doc3

Improve documentation about --rich-data

3 files changed, 68 insertions, 13 deletions

diff --git a/doc/ledger.1 b/doc/ledger.1
index 8284dfa4..8925e6f9 100644
--- a/doc/ledger.1
+++ b/doc/ledger.1
@@ -510,6 +510,12 @@ but not
 .Sy Expenses:Entertainment:Dining .
 This is a display predicate, which means it only affects display,
 not the total calculations.
+.It Fl \-detail
+Related to
+.Ic convert
+command. Synonym to 
+.Fl \-rich-data
+option.
 .It Fl \-deviation
 Report each posting's deviation from the average.  It is only meaningful
 in the
@@ -871,7 +877,10 @@ postings.
 .It Fl \-revalued-total
 Display the sum of the revalued postings as the running total, which serves
 to show unrealized capital in a gain/losses report.
-.\".It Fl \-rich-data
+.It Fl \-rich-data
+When generating ledger transaction from CSV file using the
+.Ic convert
+command, add CSV, Imported, and UUID meta-data.
 .It Fl \-seed Ar INT
 Set the random seed to
 .Ar INT
diff --git a/doc/ledger3.texi b/doc/ledger3.texi
index 936a69e0..a4e055d0 100644
--- a/doc/ledger3.texi
+++ b/doc/ledger3.texi
@@ -4638,14 +4638,52 @@ from the file above.
 @findex --account @var{STR}
 @findex --rich-data
 
-The @command{convert} command accepts three options.  They are
-@option{--invert} which inverts the amount field,
-@option{--account @var{STR}} which you can use to specify the account to
-balance against, and @option{--rich-data} which stores
-additional metadata as tags.  There is, for example,
-a UUID field.  If an entry with the same UUID tag is already included in
-the normal ledger file (specified via @option{--file @var{FILE} (-f)} or
-via the environment variable @env{LEDGER_FILE}) this entry will not be
+The @command{convert} command accepts three options. They are
+@option{--invert} which inverts the amount field, @option{--account
+@var{STR}} which you can use to specify the account to balance against,
+and @option{--rich-data} which stores additional metadata as tags.
+
+Using the two first lines of the above csv file,
+
+@smallexample @c file:B2EA7E8
+,date,payee,note,amount,,,code,
+767718,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-8.80,,00001640.04,,
+767406,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-1.03,,00001648.84,,
+@end smallexample
+
+and launching the below command,
+
+@smallexample @c command:B2EA7E8,with_file:download.csv
+$ ledger convert download.csv --input-date-format "%m/%d/%Y" \
+  --invert --account Assets:MyBank --rich-data \
+  --file sample.dat --now=2012/01/13
+@end smallexample
+
+you will get the result:
+
+@smallexample @c output:B2EA7E8
+2011/12/13 * Withdrawal  ;ACE HARDWARE 16335 S HOUGHTON RD
+    ; CSV: 767718,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-8.80,,00001640.04,,
+    ; Imported: 2012/01/13
+    ; UUID: dfdc3c3d5c54c6967dd39d5b4e4fd1ea76e87233
+    Expenses:Unknown                             8.8
+    Assets:MyBank
+
+2011/12/13 * Withdrawal  ;ACE HARDWARE 16335 S HOUGHTON RD
+    ; CSV: 767406,12/13/2011,"Withdrawal","ACE HARDWARE 16335 S HOUGHTON RD",-1.03,,00001648.84,,
+    ; Imported: 2012/01/13
+    ; UUID: 63086448b1f29f7fd6efb11ea40660185a213f9d
+    Expenses:Unknown                            1.03
+    Assets:MyBank
+@end smallexample
+
+The three added metadata are: @samp{CSV} as the original line from csv
+file, @samp{Imported} as the date when the csv file was imported into
+Ledger, and @samp{UUID} as a checksum of original csv line.
+
+If an entry with the same @samp{UUID} tag is already included in the
+normal ledger file (specified via @option{--file @var{FILE} (-f)} or via
+the environment variable @env{LEDGER_FILE}) this entry will not be
 printed again.
 
 You can also use @command{convert} with @code{payee} and @code{account}
@@ -6629,10 +6667,8 @@ to show unrealized capital in a gain/losses report.
 
 @item --rich-data
 @itemx --detail
-@c When generating ledger transaction from csv using the convert command
-@c add CSV, Imported, and UUID meta-data.
-@c see test/baeline/opt-rich-data.test
-@value{FIXME:UNDOCUMENTED}
+When generating ledger transaction from CSV file using the
+@command{convert} command, add CSV, Imported, and UUID metadata.
 
 @item --seed @var{INT}
 Set the random seed to @var{INT} for the @code{generate} command.
diff --git a/test/baseline/opt-rich-data.test b/test/baseline/opt-rich-data.test
index fbb73ebe..265af531 100644
--- a/test/baseline/opt-rich-data.test
+++ b/test/baseline/opt-rich-data.test
@@ -1,3 +1,13 @@
+test -f /dev/null convert test/baseline/feat-convert-with-directives.dat --now '2014/08/01'
+2012/01/01 * KFC
+    Expenses:Unknown                             $10
+    Equity:Unknown
+
+2012/01/02 * REWE SAGT DANKE  123454321
+    Expenses:Unknown                             10€
+    Equity:Unknown
+end test
+
 test -f /dev/null convert test/baseline/feat-convert-with-directives.dat --detail --now '2014/08/01'
 2012/01/01 * KFC
     ; CSV: 2012/01/01,KFC,$10