man page generator (was: plans for 0.0.6 release)

[Hans Ulrich Niedermann]

Martin Pool <mbp at sourcefrog.net> writes:

> On  1 Jun 2005, Hans Ulrich Niedermann <arch at n-dimensional.de> wrote:

>> I have written a script which autogenerates an (admittedly basic) man
>> page from the output of "bzr help". It still lacks the detailed
>> explanations, but it is already a lot better than having nothing at
>> all:
>> 
>> http://es.lauft.net/bzr/bzr-manpage.patch   (the patch)
>> http://es.lauft.net/bzr/bzr.1               (the generated man page)
>> http://es.lauft.net/bzr/bzr.ndim/           (my enhanced branch)
>
> Thanks!  I was planning to do that, or hoping someone would do it.

Well, I've already done this for bazaar, so this was just a kind of a
port from Perl to Python and moving from parsing program output to
working within the program itself.

> We could enhance this a bit:
>
>  - also generate HTML 

Before we start doing anything else but creating a simple, we will
want to evaluate existing python doc tools to avoid reimplementing
stuff.

Some of those tools might work with a (docstring) syntax we might want
to adopt, and which we will want to evaluate before inventing our own.

>  - put the introductory material into a text file rather than
>    hardcoded into the program
>
>    I'd like to have "bzr help introduction" show some of this.

Or as another doc string (fits better into the existing pattern).

So far, I have just copied the first few paragraphs from the bazaar-ng
website.

>  - Include sub-sections for each command showing its syntax and options, 
>    as generated by the help command.

Already done, merge again :)

Another point for enhancements would be to refactor baz-man.py and
merge some of the code into bzrlib.help. This could avoid some
serialization and reparsing of help information (consider option
lists).

Uli