man page generator

[Hans Ulrich Niedermann]

Martin Pool <mbp at sourcefrog.net> writes:

> On  7 Jun 2005, Michael Ellerman <michael at ellerman.id.au> wrote:
>> On Tue, 7 Jun 2005 17:54, Hans Ulrich Niedermann wrote:
>> > 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".
>> > > ...
>> > >
>> > >  - 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.
>> 
>> There is a Python package called docutils [1] that turns Restructured text [2] 
>> into html/xml/latex. http://docutils.sourceforge.net/

Yes, that was what I was looking for. :)

However, restructured text alone probably cannot help us yet - we
still need a way to express:

  a) command synopsis:
     command name, valid values for the parameters and options

  b) items to be substituted:
     e.g. the actual name of the bzr executable

Oh, and our options need to be documented somehow (the option
themselves, and what they do in the context of the command they are
used with).

>> You could write an XSLT stylesheet to transform the XML into a format man can 
>> cope with.
>
> Maybe it's just me, but I'd rather write Python than XSLT.

I'd have no problem writing XSLT, but the question is whether you can
write "good" man pages with XSLT at all. Judging from the output of
Norman Walsh's Docbook XML XSLT stylesheets (and those are pretty
sophisticated stylesheets!), it is at least quite difficult.

> Using docutils to produce HTML would make sense; perhaps we could even
> write a rest-to-man translator.

rest-to-man translator sounds reasonable.

Uli