On 2020-11-15 12:20, Robert Elz wrote: > Date: Sun, 15 Nov 2020 03:10:08 +0100 > From: Kamil Rytarowski <ka...@netbsd.org> > Message-ID: <12f29556-2407-2f6f-de5c-67539bca6...@netbsd.org> > > | 1. NetBSD base ships with two programs that can format manual pages from > | base and most 3rd party software: BSD mandoc (newest) and GPLv2 groff > | 1.19.2 (old, from 2005). > > When discussing this, remember that there are more than manual pages > that need to be formatted - Martin mentioned the release docs, but there's > also (the sources for) /usr/share/doc (and while that is kind of sparsely > populated, we should be trying to fill in everything that we can that's > missing from the CSRG distributions, whether they're still highly useful > or not (they provide historic data on how we got to where we are now) > and also add anything else that might be useful. > > mandoc isn't useful for any of that, and nor should it be, that's not > its purpose. > ... > > | - switch to https://github.com/aligrudi/neatroff > | - switch to https://n-t-roff.github.io/heirloom/doctools.html > > I don't know how full featured either of those is, nor how many > groffism's have crept into other docs. > > | - switch to something else (anything else?) > > Thierry, TeX is not an alternative. As a general purpose doc > tool it is fine, and it doesn't take much arguing to convince people > that it produces better results than anything *roff can ever do, > but it doesn't format existing *roff docs. > > Whether some version of that (KerTeX or another) should be in base > is an entirely unrelated discussion.
Heirloom troff covers the varied requirements raised in this discussion and provides a number of additional benefits as a replacement for groff. The main requirements identified appear to be the ability to format all historical roff documents in any macro package into terminal, html, and typeset postscript or pdf output. The failure of the old groff in base with current mandoc files is one illustration of that requirement. The heirloom doctools include all the standard macro packages and pre-processors used in historical documentation outside of manpages as well as compatibility with groff extensions like long macro names and the ability to produce html output. Moreover, the heirloom tools support unicode characters, ttf/otf fonts, and the Knuth-Plass linebreaking algorithm unlike groff. It would also be nice to have the heirloom tools in base be coded in C rather than the C++ in groff. The alternatives in descending order are all lacking in some key features: - 4.3 BSD includes C/A/T troff and the ditroff under contrib that cannot produce postscript output (encumbered Adobe transcript or psroff from Chris Lewis were used; psroff would be difficult to maintain and extend) - AT&T Documenter's Workbench (https://github.com/n-t-roff/DWB3.3) is in an incomplete state of change from Research v9 ditroff in SVR4: some pre-processors are missing and new versions of utilities exist alongside old versions, such as the unformatted ascii flag to a single roff executable (troff), which failed to replace the old version of nroff (onroff) that needed to be bundled as well - neatroff is a reimplementation that omits some low-level roff commands and preprocessors - manpage formatters like mandoc and cawf are geared to terminal display with significant command/formatting limitations All the TeX variants are several orders of magnitude larger, slower, and harder to customize than any version of roff while failing to provide terminal output. Even if a preprocessor accurately converted all the roff sources in the tree to TeX input, then there still would be no standard reliable tool to produce formatted terminal output. I've found that the tools for terminal output -- catdvi, dvitty, and dvi2tty -- are all unmaintained and produce little more than the equivalent of deroff with no indentation or formatting retained from the dvi output. The heirloom doctools are really the best all around and least invasive replacement groff. Best, Dan Plassche
