Re: man(7), hyphen, and minus

[G. Branden Robinson]

At 2022-12-23T12:49:15-0800, Russ Allbery wrote:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> > Right.  Four or five years ago I proposed a new groff special
> > character identifier `\(hm` to cover this case.  But this was not
> > met with assent, and I concede that the problem may be confined to
> > man pages.
> 
> I've been curious: how much use do you see of groff outside of man
> pages?

Others have answered this but I would also point you to Ralph Corderoy's
page on the subject.

https://www.troff.org/pubs.html

It hasn't been updated since about 2006, I think, which means it has
missed a few publications since then, like _The Go Programming Language_
and Kernighan's _UNIX: A History and Memoir_.

> I dropped a bunch of troff formating guesswork and magic from Pod::Man
> that had caused no ends of maintenance problems because I have seen
> little evidence of anyone using it for something other than man pages,
> and in my day job supporting research science I don't hear anyone
> talking about roff in that context either.  (Everyting is LaTeX.)

The groff_man(7) page has long attempted to prescribe a reasonably
portable, reduced subset of the roff language for use in man pages.
mandoc maintainer Ingo Schwarze and I spent some time prior to groff
1.22.4's release hammering that out in further detail.

> I've therefore started optimizing Pod::Man for manual pages, although
> if anyone reports problems with any other use I try to keep it
> working.

It's called Pod::_Man_: why would people use it for anything that isn't
a manual page?

pandoc has a filter (recently improved) for generating ms(7) documents
from other formats; this sort of approach is better for general
documentation.

As LaTeX is a macro package for TeX, man(7) is a macro package for
*roff.  I don't see where it is in Pod::Man's charter to support fully
programmable typesetting.

> As a related question, are there grand plans for adding more Unicode
> support?

Yes.  But there are two problems to solve: (1) acceptance of Unicode
(probably just UTF-8) input and (2) improved ergonomics of integration
with a wide variety of fonts.  The goals, among other, are laid out in
groff's Mission Statement.[1]

> I noticed that, for example, troff from groff as installed on Debian
> appeared to have fairly rudimentary Unicode font support.  It looked
> like the default font was missing a bunch of characters, it didn't
> handle combining accent marks when I tried, etc.  It's possible that I
> was testing incorrectly, though.

I would look first at the groff_char(7) man page, on any output device
you like.  That will begin to establish the parameters of what is
possible.

It has been possible for many years (since well before groff 1.22.3) to
specify any Unicode code point for output.

> Yeah, at this point I would recommend everyone switch to Unicode and
> try to support it as well as possible, although that doesn't help with
> cases where the debate is over how to render pre-existing ASCII
> characters.

No, but that problem is small in scope.

> I had not heard of Heirloom Doctools or neatroff before, although I
> don't follow this field very closely.  Do you know if any platform
> uses them for man pages right now?

Heirloom Doctools is a descendant of AT&T troff; among other things, it
provides its own man(7) implementation, a lineal descendant of Doug
McIlroy's 1979 original.  It _can_ and _does_ render man pages.  Whether
any *nix distribution ("platform"?) ships Heirloom as its sole or
preferred *roff, I don't know.  I wouldn't be surprised if at least one
BSD does, for the usual reasons of GPL antipathy[2].  About 15 years ago
it undertook a major effort to clone groff features, and it is
reasonably groff compatible when configured to be (`-mg` flag, `xflag`
request, and whatnot).

I often use Heirloom Doctools troff (and, of late, its predecessor
DWB 3.3 troff [a former AT&T product]) for comparative analyses.

Neatroff is a permissively licensed ground-up rewrite.  It does not
provide its own man(7) macros.

Both Heirloom Doctools and Neatroff troffs enjoy considerable praise
regarding their support for "microtypography" and OpenType fonts, and
some ink is spent derogating groff for lacking these.  It is not clear
to me how much of this is jabbering of the sort teenage boys used to do
with car magazines regarding the specifications of muscle cars they
could not afford to buy and had no hope of personally driving.

On the other hand, we _know_ that people are frequently frustrated by
the difficulty of using third-party fonts with groff, hence the
popularity of Peter Schaffter's install-fonts.sh script, and my rewrite
of a chunk of the grops(1) and gropdf(1) man pages for 1.23 to address
this issue after personal experimentation.

And, Dave Kemper practically has his own wing of the groff bug tracker
in Savannah dedicated to kerning issues.  So I don't doubt that real
users who exist who truly care about these matters.

What's weird is that these alternative troffs don't have much in the way
of support channels; this mailing list is the water cooler for all
surviving *roff systems, and Heirloom and neatroff just don't come up
very often.

So they might be bugless and perfect or they just don't have many users.

> The two implementations I mostly target are groff and mandoc,

For a tool that limits is domain to manual pages, I think that approach
is perfectly sound.  Man pages _have to_ work on groff and/or mandoc or
they are not fit for purpose.

> since that seems to cover the vast majority of modern systems and the
> remainders are using some legacy UNIX code base that basicallly
> doesn't exist outside of that UNIX.

Right.  This is why I'd urge you to withdraw support for Solaris troff,
as Solaris itself has.  It's a manifest impediment to further Pod::Man
improvement.  If it weren't, I wouldn't care, and would even argue for
retention of support on the principle of not breaking things for no
benefit.  But like Solaris's pre-standarized /bin/sh (which _finally_
got retired), its troff is a boat anchor on other software systems that
have to work around its bugs.

Regards,
Branden

[1] https://www.gnu.org/software/groff/groff-mission-statement.html

[2] The CDDL is way _more_ free than the GNU GPL, you see, because it is
    a copyleft _and_ has a choice-of-law clause, and someday the BSDs
    will have an island microstate nullifying all copyleft licenses.

signature.asc
Description: PGP signature