Re: Summary of man-page formatting

[Dan Plassche <dplassche%gmail.com@localhost>]

On 2020-11-15 12:20, Robert Elz wrote:
>     Date:        Sun, 15 Nov 2020 03:10:08 +0100
>     From:        Kamil Rytarowski <kamil%netbsd.org@localhost>
>     Message-ID:  <12f29556-2407-2f6f-de5c-67539bca6d66%netbsd.org@localhost>
> 
>   | 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