Hi, Nate! At 2021-07-31T15:22:09-0500, Nate Bargmann wrote: > Hi Branden and all. > > I took the bait and looked up the linux-man mailing list archive and > from there found the link to graff_man(7) and from it > groff_man_style(7) on man7.org (the linux-man project page. Great > resource by the linux-man project, BTW). I think the effort with > groff_man_style(7) is outstanding and it would have helped me years > ago from jumping around three or four man pages and > interpolating/interpreting good practice for such documentation. The > link is likely one I'll include in my meager README.man-pages for the > hamlib project.
Terrific! > (Of course, my Debian Bullseye systems lack groff_man_style(7) as they > still have groff 1.22.4 installed). Yes, regrettable. > Regarding the PDF you attached from the Groff manual, I do think that > would still be rather dense reading for anyone without the background > in groff_man_style(7) and is for advanced man page > authors/maintainers. Oh, darn. Well, that's good to know. It tells me I need to vary my approach for the introductory section I'll eventually add to the page. > Now, a slight tangent. I think you would agree that consistency in > the man page corpus is a difficult but worthy goal. At the very least > there should be consistency in the corpus on a per-project basis and > even this is difficult over time as files are touched by various > authors. > > In groff_man_style(7) the .BI, .BR, etc. macros are described as > setting their odd arguments to the first style and their second > argument to the second style and so on on an odd/even alternating > basis. > > However, I was reading groff_mm(7) recently and noticed that the > description for its .IB macro reads as follows: > > IB [italic‐text [bold‐text [italic‐text [...]]] > Italic‐bold. Even arguments are printed in italic, odd in > bold‐face. See I. > > Do you see the disparity? Yup. > I think it is natural in the case of most people to assume as > groff_man_style(7) that macro arguments are odd/even alternating while > groff_mm(7) states even/odd alternating. Hmmm. I attribute the > wording in groff_mm(7) to be related in terms of 0 based indexing > whereas most documenters--not programmers per se--are more familiar > with 1 based indexing. > > Thoughts? I think you're right. The zeroth argument to a font alternation macro is not going to typeset itself. So we should count from one. I have not touched groff_mm(7) very much; there is much about it that is inconsistent with the way I've restyled most of other pages. I knew when I got involved with groff documentation that I'd likely be here for years. :) Regards, Branden
signature.asc
Description: PGP signature
