Docbook to Man pages

[Jeff Schering]

On 8/12/06, Bhuvaneswaran <bhuvan at ubuntu.com> wrote:
>
> So, it implies we must maintain a seperate set of xml files to
> generate man pages and make changes related to the above mentioned
> tags. I wish to get your concurrence before i can create seperate
> directory (sg-man-pages?) for these set of xml files.
>

Actually, instead of creating a separate set of xml files for
docbook->manpage, it would be better to create an xslt file to
transform the existing docbook to one with the ref* tags. That way, we
only need to maintain the one document.

The process would look something like this:
docbook with sect* tags + xslt = docbook with ref* tags
docbook with ref* tags + xslt = man page(s)

In this case, the docbook with ref* tags is an intermediate file and
can be deleted once the man pages have been created.

All of the processing commands can be added to the existing makefile.

The beauty of this approach is that it is generalized. Once the xslt
is created, it can be applied to any document that we want to create a
man page from.

The drawback is that someone needs to write the xslt, but hopefully
this sort of thing has been done before and we can find an existing
transformation file that we can use or modify.

> We have two ways to go from here:
>
> 1) Merge all existing server guide xml files (chapters) to single file
> with single refentry tag, thus, just one man page is generated. The
> user can use this man page as one-stop guide to install all his server
> applications
>
> 2) Retain all existing server guide xml files (chapters) as they are
> right now. But, make changes in them to include necessary ref* tags.
> In this method, seperate man page is generated for each chapter. We
> may have one master man page listing the details of man pages of all
> chapters and instructing the user to refer the relevant man page for
> further details.
>

Theoretically, the xslt for the docbook with sect* tags to docbook
with ref* tags should be able to output one or the other of the above
two formats, or both. We can then decide which one to go with.

Cheers,
Jeff

-- 
Jeff Schering
GPG: F23C67E8