Problem : Documentations for hledger and journal don't explain --value clearly. #403

Closed
crocket opened this Issue Sep 19, 2016 · 1 comment

Projects

DONE in release 1.1

2 participants

@crocket
crocket commented Sep 19, 2016 edited

http://hledger.org/journal.html#market-prices says When market prices are known, the -V/--value option will use them to convert reported amounts to their market value as of the report end date..

There are two problems with this.

  1. The report end date is not defined. The definition should be given on http://hledger.org/journal.html#market-prices.
  2. as of could mean two things. On the report date and From the report date on.

It's better to say something like convert reported amounts to their latest market values before or on the report end date. For example, if the report end date was 2010/1/25, a market value on 2015/1/25 can be used, but a market value on 2015/1/26 cannot be used.

http://hledger.org/hledger.html#market-value says The -V/--value flag converts all the reported amounts to their "current market value" using their default market price. That is the latest market price (P directive) found in the journal (or an included file), for the amount's commodity, dated on or before the report end date.

This is confusing. I'd write something like The -V/--value flag converts all the reported amounts to their "current market value". The current market value is the latest market price (P directive) found in the journal (or an included file), for the amount's commodity, dated on or before the report end date. For example, if the report end date was 2015/1/26, a market value on 2015/1/26 can be used, but a market value on 2015/1/26 cannot be used.

I haven't defined report end date in the above examples. But, a pull request that addresses this issue will include the definition of report end date.

@simonmichael simonmichael modified the milestone: 0.28 Sep 20, 2016
@simonmichael simonmichael modified the milestone: 1.0, post 1.0 Oct 31, 2016
@simonmichael simonmichael modified the milestone: 1.1 Dec 29, 2016
@simonmichael simonmichael self-assigned this Dec 29, 2016
@simonmichael simonmichael modified the milestone: 1.1 Dec 30, 2016
@simonmichael simonmichael added a commit that referenced this issue Dec 30, 2016
@simonmichael doc: cli: add a new section on report start/end dates (#403)
and more linkage among the cli date docs.
fa431f9
@simonmichael
Owner

Wow. This sounded like a quick docs fix, but looks were deceiving. Two fixes and many docs clarifications later, I think this is resolved. I have rewritten
http://hledger.org/journal.html#market-prices and http://hledger.org/hledger.html#market-value, added a section http://hledger.org/hledger.html#report-start-end-date and added a bunch of links between these places (with some text hints for when hyperlinks are not available, eg in man pages).

Thanks for this helpful feedback.

@mstksg mstksg added a commit to mstksg/hledger that referenced this issue Feb 3, 2017
@simonmichael @mstksg + mstksg doc: cli: add a new section on report start/end dates (#403)
and more linkage among the cli date docs.
34d2495
@mstksg mstksg added a commit to mstksg/hledger that referenced this issue Feb 3, 2017
@simonmichael @mstksg + mstksg doc: journal: clarify market prices (#403) c21fffc
@mstksg mstksg added a commit to mstksg/hledger that referenced this issue Feb 3, 2017
@simonmichael @mstksg + mstksg lib: show report end date in debug output #403 #453 c980c3b
@mstksg mstksg added a commit to mstksg/hledger that referenced this issue Feb 3, 2017
@simonmichael @mstksg + mstksg lib: report end date fix #403 #453 ea91c74
@mstksg mstksg added a commit to mstksg/hledger that referenced this issue Feb 3, 2017
@simonmichael @mstksg + mstksg update market price tests #403 #453 1ee3a68
@mstksg mstksg added a commit to mstksg/hledger that referenced this issue Feb 3, 2017
@simonmichael @mstksg + mstksg doc, cli: improvements for -B, -V, prices docs #403 9cb5a71
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment