Re: [groff] groff as the basis for comprehensive documentation?

[Ingo Schwarze]

Hi Nate,

Nate Bargmann wrote on Sun, Apr 15, 2018 at 04:17:59PM -0500:

> I have long been involved with a project that has lacked good
> documentation for nearly all of its existence.  We've had documentation,
> but it isn't in a good format for generating man, HTML, or PDF versions.
[...]
> After letting this sit for some time, I realized that I had not
> investigated groff deeply

That is really strange.  :)

It has always been the central format for research and commercial
UNIX, it has always been used by all the BSD projects (actually
using GNU troff for about two decades), and the Linux man pages
project also uses it, so i would consider it the canonical solution
for documentation in general.

> But (there is always a 'but'), beyond the collection of nroff files I am
> creating for the man pages, it would be nice to be able to tie them all
> together into a whole.

For rendering manual pages, consider using mandoc(1) rather than
groff.  While it is not a typesetting system and consequently has
*much* weaker PostScript and PDF output than groff, it is slightly
better for terminal output and **much** better for HTML output.
The input languages are exactly the same, it is merely a different
parser and formatter implementation strictly optimized for manual
pages.

Also, both the command line and CGI tools are *much* more powerful
than the combination of groff with man-db, or with any other man(1)
implementation that runs on Linux.

Specifically, for the question you are asking, make sure you have
the man(1) implementation from the mandoc toolkit installed, then
use

  $ man -aks 2 ~.

to view a combined document containing all the section 2 manual
pages on a terminal or

  $ man -T pdf -aks 2 ~. > tmp.pdf

to create a single PDF document containing them all, or

  https://man.openbsd.org/?query=~.&apropos=1&sec=2

for an online HTML / CGI version with hyperlinks; off course, you
can also create a hyperlinked offline HTML version, for example
with the catman(8) tool contained in the mandoc toolkit, but the
online version is certainly more useful.

All that is available out of the box, without installing any
packages whatsoever, on OpenBSD, Alpine Linux, and Void Linux.

FreeBSD, NetBSD, and illumos also contain all the required binaries
by default without installing any package, but they install less
powerful implementations of man(1) by default, but you can easily
symlink mandoc to man to get the mandoc implementation of man(1).

Debian, Ubuntu, Arch, Gentoo, Slackware, Homebrew, MacPorts, and
pkgsrc provide packages that you can install.  Building from
source is also tested on AIX and Solaris 9-11.

> I was hoping the mom macro package might have some sort of a facility
> for this idea,

While mom is certainly a very considerable option for a wide 
range of non-manual-page documents, it cannot be used with
manual pages at all.  But there is no need, mandoc already
provides all you are asking for, and more - for example,
building a PDF document on demand containing the pages
returned by a specific semantic search query - no matter
whether the query returns a handful, dozens, or hundreds
of pages.

> Regardless, I plan to continue with improving our project's collection
> of man pages and work from there and will likely remove the Texinfo
> files at some point.

Sounds like a reasonable plan - http://mandoc.bsd.lv/texi2mdoc/
may or may not help with the transition, by the way.  It is not
very actively maintained these days (though i might fix bugs
in it if any are reported), and the output certainly needs manual
postprocessing, but using it is very likely to save you quite
some work compared to writing everything from scratch.

Of course, make sure to use the semantic mdoc(7) language, not the
old, purely presentational man(7) language, or you won't have
semantic searching, and most of the hyperlinking won't be present,
either.  Also, writing man(7) is much harder than writing mdoc(7).

For documentation, see

  http://mandoc.bsd.lv/

For overviews of the wide variety of topics that are being worked
on regarding roff(7) as documentation format, see

  https://www.openbsd.org/papers/eurobsdcon2015-mandoc.pdf
  https://www.bsdcan.org/2018/schedule/events/958.en.html

Yours,
  Ingo