Re: [PATCH 4/6] xattr.7: wfix

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4482 bytes --]

At 2022-08-11T14:48:51+0200, Ingo Schwarze wrote:
> Alejandro Colomar wrote on Mon, Aug 01, 2022 at 03:28:03PM +0200:
> > I'd like to arrive to some consensus on usage of \~ and '\ '.
> 
> In manual pages, always use "\ " and never use "\~", period.

This is hugely overstated.

> The former is portable and the latter is a GNU extension.

...that is over 30 years old and supported by Heirloom Doctools troff
for 17 years now, neatroff for about six, and your mandoc for three.

For full disclosure, I'll acknowledge that Documenter's Workbench [DWB]
troff doesn't support it, but it doesn't seem to have been maintained
for 30 years (Heirloom Doctools troff appears to be its
descendant/successor).  plan9port troff doesn't either, and its laudable
introduction of a man(7) MR macro notwithstanding, its activity level is
not high.

I would pessimistically assume that most or all proprietary Unix
troffs branched off from V7 Unix troff or early device-independent troff
(maybe DWB 1.0 troff, ca. 1984 [?, 1]) lack support for `\~`.[2]

I further note that groff has a long tradition of inclusion in BSD
Unix,[3] and despite the efforts of the mdocml/mandoc project to
supplant or dispose of it groff in BSD's descendant communities, the
underlying fact remains.  Giving up support for `\~` was therefore, in
this sense, a regression, and one that took quite some time to address.

> > What do you think?
> 
> I think you are massively overthinking this and the whole SI
> argument is irrelevent for manual pages.

Man pages are technical writing and BIPM's recommendations in this area
that Alejandro uncovered have prompted me to reconsider the style advice
in groff_man_style(7) [from groff Git].

But you should welcome that.  It would mean that a handful of uses of
`\~` in the groff man pages would move to `\ `, which is motion in the
direction you want anyway.

In any event, the selection of `\ ` versus `\~`, assuming support for
both and an understanding of their distinct meanings and effect on
adjusted output, is a matter for a software project's documentation
style guide.

As I recall, mandoc does not even support "full justification"
(alignment of text to both left and right margins, with inter-word
spaces expanded ["adjusted"] to achieve this) in the first place and
there are no plans to.  mandoc can thus treat the two sequences as
synonymous--but that doesn't mean the `\~` escape sequence is a
gratuitous alias or deviation from the norm.  It is a replacement for an
arcane troff hack.

  .\" no trailing space or character translation target on the next line
  .tr ~
  G.~W.~Pabst directed several films in the 1920s.

> While the above concern about robustness is minor, too (both groff and
> mandoc support \~),

...as do others, listed above...

> portability is still significantly more important

You are not quantifying anything.  Come on, can we at least get a Fermi
estimation of the installed bases of the respective troff
implementations and mandoc?

There are, I presume, still C compilers out there that don't accept ANSI
C (1989) input.  That doesn't, and shouldn't, stop the rest of the world
from moving forward.

> than such minute typographical details.

For someone arguing from a standpoint of such slavish fidelity to 40
year-old practices, you seem to be selective in the way you do it.  The
Unix manual was always meant to be typeset.

"The manual was intended to be typeset; some detail is sacrificed on
terminals." (man(1), _Unix Time-Sharing System Programmer's Manual_,
Eighth Edition, Volume 1, February 1985)

At the time that statement was written, the sentiment was some 12 years
old; the Bell Labs CSRC typeset man pages as soon as it was possible for
them to do so.[4]

I understand if some man page contributors don't want to mess with
aspects of typography that will appear only when formatting for output
devices more sophisticated than terminal emulators--widow and orphan
management can be tedious, for instance--but we shouldn't promulgate
advice that makes the task of those who do--people like Alejandro and
me--_harder_.

Regards,
Branden

[1] https://archive.org/details/dwb-preprocessor-ref
[2] https://github.com/n-t-roff/Solaris10-ditroff/blob/master/troff/n1.c#L797
[3] https://minnie.tuhs.org/cgi-bin/utree.pl?file=Net2/usr/src/usr.bin/groff/VERSION
[4] https://dspinellis.github.io/unix-v4man/v4man.pdf

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]