Hi Michael and Alex! At 2020-09-28T12:34:40+0200, Michael Kerrisk (man-pages) wrote: > On Mon, 28 Sep 2020 at 11:04, Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> wrote: > > I had been using .PP because I hadn't seen .br before. > > > > I think .br is the correct format, > > following the pattern in already existing man pages. > > I don't disagree with the formatting change, but I am wondering if > there's a better way to do it. There are a few ways to skin cats in even the restricted dialect of man(7) that I advocate. (The other groff developers seem to generally agree, but I will admit that I am probably more puritanical and maniacal than most of them. :) ) > I tend to consider (perhaps wrongly) that the use of .sp and .br is > unidiomatic, In my book you're certainly right. There are a few reasons for keeping the lexicon of macros/requests appearing in man pages small. 1. man pages, far more than any other type of *roff source document, get parsed by things are not *roff typesetting engines. The less *roff they have to simulate, the easier it will be for them to achieve intelligible rendering. mandoc(1) is probably the premier example in this respect, and I believe I understand from its current developer Ingo Schwarze that it handles rather more *roff than we would prefer. There have also been numerous "man2html" processors developed over the years, typically of somewhat dispiriting quality. 2. Even in the world of *roff typesetters there is diversity. For a long time groff was the only freely-licensed game in town, but nowadays I know of Heirloom Doctools, Plan 9, Solaris 10, DWB 3.3, and neatroff implementations. The smaller the language, the easier it is to get consensus and parity around portable constructs. 3. A smaller language is easier to learn and easier to retain for people who are part-time documenters. A person who only tackles documentation maintenance once every four to six months, say, is going to have an easier time with a language with maybe two dozen tags, several of which fall into groupings with a predictable naming pattern, than they will with, say, the 417 tags of DocBook[1]. For groff 1.22.4, released in December 2018, I made sure to front-load the groff_man(7) page with a quick reference for all non-deprecated tags. My hope is that man page writers who have been around the block with the man(7) language once before can type "man groff_man" and be refreshed after having to hit the space bar at most twice. A corollary of point (3), especially when it comes to the mixing of *roff requests with macros, is that their subtle interactions can be frustrating to learners--and even to experienced users. Someone who leans what .sp does may be surprised to find it not working between a section heading (.SH) and the first line of text afterwards. Similar frustrations can arise with the .in request when mixed with .RS and .RE. > and over the years I have replaced a large of them with alternatives. > (For example, in many cases, .sp was being used when .PP should have > been.) > > If Branden does not tell us of something better, I will just apply > your patch as is. _Personally_, I prefer system_data_types(7) as of efbe7900b931789849a978c619106a8973e679cd to any intrusion of .br requests. And as a C programmer I find it clear enough. I do wonder about the huge list of header files providing `size_t`, but I guess my raised eyebrow is better aimed at the ISO C committee than here. :) Regards, Branden [1] https://tdg.docbook.org/tdg/4.5/docbook.html
Attachment:
signature.asc
Description: PGP signature
