Re: nesting lists in man(7) pages

[Ingo Schwarze]

Hi Larry,

this is straying from the Subject:, but i'm not sure there is enough
to discuss to warrant assigning a new subject.

Larry Kollar wrote on Mon, Aug 30, 2021 at 10:45:42PM -0400:

> General Docbook to man(7) would be quite an undertaking, yes.

Well, several such converters exist, usually producing man(7) code
of abysmal quality.

Most manual pages autogenerated from DocBook that you see in the
wild reference http://docbook.sf.net/ .  That is used, for instance,
by clisp(1), giflib, git(1), GTK+, libnfs, libxml2, neon, PostgreSQL,
SCons, twolame(1), wavpack(1), xmlcatalog(1), xsltproc(1), ...

But there is also

 * docbook2man, part of docbook2X, used for example by flac(1), ps2eps(1)
 * db2man.xsl, used for example by checkXML5(1) and other KDE stuff,
   gdbus, and parts of samba
 * https://manpages.debian.org/unstable/docbook-to-man/docbook-to-man.1.en.html
 * http://www.sagehill.net/docbookxsl/RefentryToMan.html
 * and probably many others

and myself, i am maintaining https://mandoc.bsd.lv/docbook2mdoc/ .

> But given some input constraints (i.e. the Docbook document is
> structured similarly to a manpage),

Essentially, that is what "refentry" was invented for.

> it should be possible to get decent output.
> But for best results, the author would need to consider man(7)
> while creating and editing the Docbook source.

  https://man.openbsd.org/fonts

generated using docbook2mdoc(1) from an <article> file demonstrates that
semi-decent results can be attained even if the author did not care.

[...]
> Manpages, whether man(7) or mdoc, have much to teach tech writers using
> XML nowadays. Not the least of which is KISS.

Amen.

Yours,
  Ingo