Re: [Refdb-devel] man pages

[Michael S. <sm...@xm...>]

Markus Hoenicka <mar...@mh...> writes:

> Michael Smith writes:
>  > Now I wish I had suggested using DocBook earlier :(
>=20
> Actually, I have been lurking on the docbook-apps list :-> and I've
> followed the work you put into the DocBook to man stylesheets (haven't
> tried them yet, though). I was aware of the possibility, but in order
> to close a hole in no time the groff approach seemed easier to me,
> especially as most tools are fairly static and the startup options
> won't change every other week.

Yep, that's definitely understandable. And it takes some time to
get familiar with the DocBook Refentry markup. But that's a lot
easier if you have a good example or template to work from.

> But then you wrote...
>=20
>  > Anyway, should you decide using DocBook would be worthwhile, there
>  > is a tool called "doclifter" that can convert troff/groff man
>  > pages to DocBook -
>  >=20
>  >   http://www.catb.org/~esr/doclifter/
>  >=20
>  > It's packaged for Debian and maybe for some other distros (anyway,
>  > it's just a shell script) and does a very good job on most pages.
>=20
> ... which is almost like eating your cake and still have it. As the
> markup in the current man pages is pretty simple, I guess doclifter
> will have no hard time to "lift" them. This would make the move to
> Docbook fairly easy.

doclifter works quite well on most man pages. One of its slickest
features is its ability to convert command and function synopses
(with various brackets, parens, etc.) to correct DocBook
Cmdsynopsis or Funcsynopsis output.

Actually, one of the neat tricks I have done with doclifter is to
write an initial simple man page in groff, with just the command
synopsis -- with all the brackets and such -- and then then run
doclifter on it to convert it to DocBook XML to get the synopsis
marked up in correct DocBook.

That's sometimes (often) easier and quicker than trying to mark up
the synopsis in DocBook initially.

After that initial part, if/when you add new options, it's pretty
easy to figure out how to mark them up, because you can infer from
the existing markup in the sysnopsis how to mark it up correctly.

So it's a painless way to get familiar with the synopsis markup.

> 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.

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.

If you have already have your source marked up in DocBook with
Refentry instances for the individual apps, please try installing
the docboo-xsl stylesheets and give it a whirl.

If you have the DocBook XSL stylesheets installed and have your
catalogs set up, you should just be able to put your source into a
temp dir and drop in the Makefile I sent, and type "make man".

Anyway, it works prety well overall.. And if you try it and find
that there are things that don't work the way you'd expect and/or
you have suggestions for improvement, I'd very much welcome them.
The handling of the AUTHOR section is still in a bit of a flux. I
will be changing/improving it a bit this week.

A few more details about particulars below.

  --Mike

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

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.

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. Though it does
handle Ulink instances in a smart way: It puts a bracketed number
inline (e.g., [1]RefDB manual) -- and (optionally) puts the link
text in *roff ital markup -- and then generates a numbered
REFERENCES list at the end; for example:

  REFERENCES

  1. RefDB manual
     http://refdb.sourceforge.net/manual/book1.html

So it works a lot like what you get if you do "lynx -dump" to
get plain-text output of an HTML page. Except that it is a bit
smarter in that if the same URL is referenced by multiple Ulinks,
it only generates one instance of that URL in the REFERENCES list.
See the example refdb-ms.1 output from the refdb-ms.xml source.

I plan to add support soon for having Footnotes handled in that
list along with the Ulinks. At that time, I will probably make the
default name of that list be NOTES instead of REFERENCES. I
considered having it generate separate FOOTNOTES and REFERENCES
(or LINKS lists), but decided a single list would probably be

--=20
Michael Smith
http://sideshowbarker.net/