New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

documenting hledger options is confusing and error-prone #663

simonmichael opened this Issue Dec 2, 2017 · 1 comment


None yet
1 participant

simonmichael commented Dec 2, 2017

Some review/clarification needed. An example: we added the new --forecast and --auto flags, generic to all commands. Here are the steps:

  1. New record fields were added to ReportOpts in ReportOptions.hs in the hledger-lib package. ReportOpts is how generic reporting flags are passed around through hledger core.

  2. In this file we also had to tell rawOptsToReportOpts how to parse these flags from RawOpts. RawOpts is how command-line options are shared between hledger packages which may not share each other's command line flag definitions, allowing modularity.

  3. The corresponding command line flags (cmdargs Flag), and their help, were added to reportflags in CliOptions.hs in the hledger package. This causes most hledger commands and addons to show the new flags in --help -> "General flags", and to accept them on the command line.

  4. Flags added to CliOptions.hs and similar places should also be documented in lib.m4, which we forgot. Also ./Shake all should be run, to update all generated docs. This causes the flag and help to appear in all the hledger tools' manuals (all formats).


  1. the above is complex and error-prone
  2. it's not explained in the dev guide
  3. why is flag order different in lib.m4 ?
  4. why are flags like --color missing from lib.m4 ?
  5. RawOptions.hs/ReportOptions.hs vs CliOptions.hs/UIOptions.hs/WebOptions.hs/etc. - similarly named but define different kinds of thing
  6. ReportOptions has some fields valid only for particular commands
  7. how can we ensure code (ReportOptions + eg CliOptions) and docs (lib.m4) remain in sync
  8. how can we ensure code (RawOptions) and code (ReportOptions) remain in sync (RawOpts provides modularity at the expense of compile-time correctness checking)

This comment has been minimized.

Show comment
Hide comment

simonmichael Dec 2, 2017


Relates to #654


simonmichael commented Dec 2, 2017

Relates to #654

@simonmichael simonmichael added ready and removed ready labels Dec 31, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment