On Sat, Apr 13, 2024 at 01:22:01PM +0100, Keith Marshall wrote: > Hello, Hi Keith! (and Branden!) > In the man-pages(7) document, as rendered at: > http://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#man-pages.7 > > under the section heading "FORMATTING AND WORDING CONVENTIONS", and > subsection "Formatting conventions (general)", close to the bottom of > page 9, I see: Page numbers broke at some point. I noticed recently, but didn't know when it started happening. It might have been some of the refactors I applied to the script. If anyone contributes a fix to the script without making it less readable, please. <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/share/mk/build/pdf/book/prepare.pl> > > > Any reference to another man page should be written with the name in > > bold, always followed by the section number, formatted in Roman > > (normal) font, without any separating spaces (e.g., intro(2)). The > > preferred way to write this in the source file is: > > > > .BR intro (2) Yep. We still follow that convention in the source code (you can check yourself at any page's SEE ALSO for example). > I have noticed that, as of groff-1.23, both groff_man(7), and the macro > package which it documents, flagrantly ignore, and indeed violate this > convention. I further notice that man-pages(7) document, from which I > have quoted, above, appears to have been formatted using that very > version of groff_man(7), perhaps with the intro(2) reference, within the > quoted paragraph, having been formatted using: > > .MR intro 2 It is written in the source code with BR: <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/man-pages.7#n754> However, the magic script that prepares the PDF book does some transformations to MR. I think it's this line: <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/share/mk/build/pdf/book/prepare.pl#n140> I would love to see that perl(1) script transformed into a bash(1) script, so I can put my hands on it comfortably. If anyone offers for such task, such anyone is more than welcome. > rather than the recommended: > > .BR intro (2) > > This leads to a glaring anomaly, within the quoted paragraph; rather > than the topic name "intro" being set in bold, as the convention > demands, it is set in (non-bold) italics! If you see the manual page in the terminal, you'll still see it in bold. > > In my personal opinion, FWIW, the use of italics in this context is just > plain ugly. Opinion aside, it does not conform to the convention, as it > is stated in man-pages(7) -- either the convention needs to be changed, > by common consent, or groff_man(7) needs to be brought to heel. Yep. I'm waiting for Branden to send MR.sed, aka, the biggest single-commit change ever to this repo (AFAIR). When he sends that patch, I'll change this page to recommend the use of MR. (Or he could.) Have a lovely day! Alex > > -- > Regards, > Keith. -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
