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:
signature.asc
Description: PGP signature
