OK, if you put it like that it is more complex. I was referring pretty much only to outputting the same content as man page and as html. I would not suggest that writing custom XSL sheets for docbook is a trivial task at all.
Sphinx does have man output, although somewhat hidden. And you always have the issue of updating the docs as well as the code as soon as you have the docs in any external format. A summary in ledger -h works for me also. S On Mon, Jun 28, 2010 at 9:45 PM, Roel Vanhout <[email protected]>wrote: > Well I disagree that it's pretty easy, although it would certainly be > possible. It would, from investigating shallowly, presumably require > changing the OPTION family of parameters to take an extra argument > that would give each option an identifier. Then it would need some > form of hierarchically grouping options, so that 'ledger -h' would > show the 'top-level' options, and 'ledger -h report' would show the > reporting options (the ones in report.h), etc. Next it would require > custom xsl stylesheets to transform the source docbook document (the > others don't seem to output to man) into a format that can be > #included in the source, and in an order that makes sense. Quite a bit > of work, and error-prone later on, it's easy to forget to document an > option when it's added, so the system would need a way to check for > that... The number of options is huge, I can imagine that providing a > full interface to the help from the command line is painstaking task. > > Maybe an easier route to take would be to show only a very brief > summary of the most used options when doing 'ledger -h'. Maybe > something like: > > - balance > - register > - -f > - -s > - -p, --begin, --end, a summary of the types of periods that can be entered > - totals > - --init-file > > Maybe some more? A small subset of commands that doesn't change > (much), and with a reference to the man page or the full > documentation. IMO this would be more idiomatic than showing the man > page when the -h option is provided. > > > cheers, > > roel > > > > On Mon, Jun 28, 2010 at 3:54 PM, Samuel Wright <[email protected]> > wrote: > > Pretty easy to create both from the same source using something like > docbook > > / sphinx /deplate or other markup. > > S > > > > On Mon, Jun 28, 2010 at 2:42 AM, John Wiegley <[email protected]> > wrote: > >> > >> On Jun 26, 2010, at 3:40 PM, Roel Vanhout wrote: > >> > >> > Am I correct in understanding from global.h:131 that in ledger v3, the > >> > --help option doesn't show a help menu any more but rather opens the > >> > man page? Or did v2 extract information from the man page and display > >> > it? As you know, the windows version has that code disabled because of > >> > a general lack of man (queue '-liness' jokes here ;) ). > >> > >> I had no intention of doing built-in help text anymore, as it is very > >> difficult > >> to manage. Instead, I intended all such quick help to exist in a man > >> page. > >> > >> What do people think? What kind of help system would work best for a > tool > >> like > >> Ledger? > >> > >> John > > > > >
