Re: [Refdb-devel] man pages

[Markus H. <mar...@mh...>]

Michael Smith <sm...@xm...> was heard to say:

> > The real question though, and I've been wondering since I know
> > DocBook, is whether I can maintain my RefDB manual (a 300+ page
> > DocBook document shipped as HTML and PDF) and the man pages from the
> > same sources. The manual contains similar descriptions of the tools,
> > with synopses of the commands and such. Is that possible?
>
> Yes. If the commands are all marked up as Refentry instances.
>

Well, currently they are not, but each tool has a cmdsynopsis and a description
of the options, so it'll take only some rearrangement to end up with Refentry
instances.

> The manpages stylesheet walks through your DocBook source file
> looking for Refentry instances, and "bursts" them out, creating a
> separate man-page output file (e.g. foo.1) for each one found. It
> ignores everything else (non-Refentry content) in the source file.
>

This is way cool. Having all documentation in a single source is an absolute
plus.

There's just a minor issue. I'm currently maintaining the manual as a SGML
document because I still can't get PDF output from the RefDB manual if I
convert it to XML. The XML is valid, FOP works in general, but it dies on my
system on this particular document with a memory exception. I guess I'll have
to run the SGML sources through osx in the Makefile to generate the XML for
your stylesheets.

> Another trick the manpages stylesheet does is that if you have
> alternate names/aliases (in DocBook terms, multiples Refnames in
> the same Refentry) for the same command, then for each alternate
> name it writes a "stub" file for soelim(1) to read -- for example,
> a bar.1 file containing:
>
>   .so man1/foo.1
>

This is very handy, and I actually use this trick for two of the man pages. Nice
to see that DocBook does this automatically.

> It also writes a manifest file (named MAN.MANIFEST by default)
> that you can use in make "clean" targets and such. (See the
> example makefile I sent). Because without such a manifest, your
> build system has no way to know what individual man-page files are
> generated during the bursting of your single DocBook source file.
>

Very handy too.

> The current manpages stylesheet does have some significant
> limitiations. The biggest one currently is that it cannot convert
> DocBook tables (neither CALS nor HTML) to *roff (actually, tbl(1)
> stuff). It also doesn't process Footnote instances.

Nothing to worry about currently.

Thanks a lot
Markus

-- 
Markus Hoenicka
mar...@ca...
(Spam-protected email: replace the quadrupeds with "mhoenicka")
http://www.mhoenicka.de