[CC list brutally trimmed] Hi, Alex! At 2021-07-31T13:20:59+0200, Alejandro Colomar (man-pages) wrote: > On 7/31/21 3:42 AM, G. Branden Robinson wrote: [...] > > I recommend: > > > > .BI MOUNT_ATTR_SIZE_VER number\c > > \&. > > I also prefer your way (at least in cases like this one (maybe in the > synopsis \f would be more appropriate)). It is more consistent with > our current style of placing each identifier in a line of its own, and > normal text separately (punctuation is placed wherever it's simpler, > but in this case I think it's simpler in a separate line). Another benefit of using the font escapes that I was reminded of today while doing a big revision pass on groff_man_style(7)[1] is that you get italic corrections for free with them. This was already true to some extent in groff 1.22.4, but I refactored the implementation of the macros earlier this year to be brutally consistent[2]. I would say that I like being able to tell man page authors that they need not learn the italic correction escapes, but I'd probably hear from many of them that they had no intention of doing so in the first place. I might get threatened with defections to RST and Sphinx just for bringing it up. 🤣 [...] > > groff -man -rCHECKSTYLE=n [...] > I'll try it. Thanks! Cool! > > > > > +.BR open_tree (2) > > > > +with the > > > > +.I OPEN_TREE_CLONE > > > > +flag and it must not already have been visible in the filesystem. > > > > +.RE > > > > +.IP > > > > > > .IP here doesn't mean anything, if I'm not mistaken. > > > > It certainly _should_--it should cause the insertion of vertical > > space. (It would also cause a break, but .RE already did that.) > > > > The interaction of .IP and .RS/.RE is tricky and can probably be > > blamed, back in 2017, for irritating me to the point that I became a > > groff developer. I've documented it as extensively as I am able in > > groff_man_style(7)[1]. > > Yes, indeed there are 2 consecutive blank lines, which is incorrect > most likely. That sounds like a bug in your man(7) renderer, and it sounds badly violative of the semantics of these macros in _any_ implementation. (You can't stack adjacent paragraph macros to make additional blank space; you just get the one.[3]) This stuff has been stable since 1979. I do not get _2_ blank lines after the paragraph ending "visible in the filesystem." Just one. None of groff 1.22.4 (Debian), groff Git HEAD, nor mandoc 1.14.4 misrender for me in that way. What's your tool set? If it's groff, I'm intensely curious to know how it's screwing this up. I can likely help you root-cause it. > Probably a glitch of copying and pasting without really understanding > what each macro does (not to blame Christian, but that the > groff_man(7) language (or dialect actually) is not something familiar > to programmers, and most of them legitimately don't have time to learn > it well). There is a wealth of terrible examples to follow, which make the language seem harder than it is. A large part of my work on groff's man pages has been to make them good examples to follow--but as, at my last count, groff's ~60 man pages produce 364 pages of type on U.S. letter paper, this is a process that is taking some time. I acknowledge that you and Michael are wrestling an even bigger bear. :) > If there's any difficulty that I should/may address, please tell me :) It looks like my latest effort was as ill-fated as my past ones. I'll follow up in the appropriate thread. > > I think it bears restating that code examples in man pages, whether set > > with the .EX/.EE macros or otherwise, are not "literal" or > > "preformatted" regions[1]. .EX does two things only: it disables > > s/1/2/? I forgot what I meant to link to here. :-/ I don't remember having a link to a Version 6 Unix (1975) troff manual handy, but if I did, we can perhaps all be grateful I failed to include it. ;-) Regards, Branden [1] https://www.man7.org/linux/man-pages/man7/groff_man_style.7.html [2] https://git.savannah.gnu.org/cgit/groff.git/commit/?id=e58e32ea308ac5d344b3c79b20d7f4ab2456377b [3] This is because the man(7) paragraphing macros activate *roff's "no space mode"[4]. [4] https://www.gnu.org/software/groff/manual/html_node/Manipulating-Spacing.html
Attachment:
signature.asc
Description: PGP signature
