Re: Summary of man-page formatting

[David Holland <dholland-tech%netbsd.org@localhost>]

On Sun, Nov 15, 2020 at 03:10:08AM +0100, Kamil Rytarowski wrote:
 > I'm going to summarize the situation with formatters in the NetBSD base.

A couple more points:

 > [...] old groff in base.

There's an additional reason to not update groff besides licensing,
which is that recent groff depends on perl.

 > 9. The upstream mandoc(1) team (as of today) is open to accept MANWIDTH
 > as it was repeatedly requested by users, however only for the release
 > after the coming one.

I don't think there's any point trying to format roff docs to any
terminal width other than 80. The formatting is not robust and I don't
think we can expect anything other than plain paragraphs of text to
resize correctly, and maybe not even that.

Furthermore, widths much past 80 are too wide for ergonomic reading
anyhow. You'd want to switch to two (or more) columns, and that's a
can of worms.

 > 11. For some reason we have got a rule for .me files in man.conf(5).

Someone should try to find out why/how it got there, but realistically
it can be removed.

 > 12. I recall recurring discussions about phasing out gplv2 groff from
 > the base and introduction of something else.

This is not relevant to man pages; we have mandoc for man pages and
it works well enough.

Trying to find something else for typesetting articles and large
documents and perhaps also the release notes (it might be possible to
abuse mandoc into handling the release notes, but it's not desirable
and mandoc will never be able to handle the general case) .... that's
an entirely different question.

When it comes up, there's basically three standard responses:

(1) Various people propose switching to this or that other roff
implementation, and sometimes lengthy discussion of the current
availability or licensing concerns or whatever follows, all ignoring
that this is rearranging the deck chairs on the Titanic.

(2) Thierry mentions kertex as an alternative to trying to import
ordinary tex into base (which is a nonstarter), but this never goes
anywhere; occasionally someone also proposes writing something new,
which has some of the same problems, most notably that it would be a
private project without much or any user community and without much
(or any) upstream supporting it.

(3) People go inventory the small number of existing alternatives to
roff and tex and find that they're all pretty problematic even
ignoring questions of whether they can credibly be imported into
base.

None of this goes anywhere useful and what's left is the status quo.

I think the _solution_ to this problem is a new typesetting engine
(not anything based on tex or roff), but this has to happen and become
viable independent of netbsd before we adopt it; if we jump the gun
it's as likely to become an expensive white elephant as anything else,
and we already have as many of those as we can afford.

Like with many other problems, the current situation is poor and
there's also no particularly viable way forward.

 > 14. We still deliver vgrind(1) and some similar macros that use groff
 > internally.

vgrind(1) is rubbish. You can easily get much nicer listings from
enscript.

The vgrind we have should probably just be deleted. I'm not convinced
it's worth writing a replacement, particularly not one that depends on
roff. But since it's a traditional Unix utility maybe someone cares
enough to bother.

-- 
David A. Holland
dholland%netbsd.org@localhost