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