Hi Alex! At 2023-01-07T01:25:50+0100, Alejandro Colomar wrote: > I agree with you that I'd prefer that section headings didn't shout at > the reader. However, I've waited to do such a change, because I'm not > sure about it. There's a good thing about having them in uppercase: > references to them are also in uppercase, and that makes it easy to > grep for them (I need to do that from time to time). > > Do you have any opinion on that? Yes. :) Section headings are still in sentence case (capitalize first letter) or title case (capitalize each word except for a fuzzy list of exceptions even native English speakers struggle to master). Whether sentence or title case is used is a style choice that I don't have a prescription for. In the groff man pages, after some discussion on the list we migrated to sentence case. As I recall there was at least one advocate for title case for section headings proper (`SH`) and sentence case for subsection headings (`SS`). The distinction is almost invisible for standard section headings anyway; the only common multi-word heading is "See also"; that one is practically never cross referenced, and it's almost always easier to find by just mashing Shift+G in the pager. If you type "-i" in less(1), this will toggle case-insensitive pattern matching. You can then search for the section name with a leading capital letter; that is usually reliable for detecting the headings, or cross references to them. > Also, when referring to the section within a page, would you refer in > lowercase, or the first-upper-then-lower? Using uppercase is > unambiguous, That's true, albeit shouty. > while using lowercase might need "section" next to the section name. In the groff man pages I have adopted the practice of always preceding the cross reference with "section" or "subsection" as appropriate, and quoting it with typographer's quotation marks (\(lq and \(rq). I go to the trouble of distinguishing sections from subsections because they are by default indented differently, and that gives people, especially those with a little facility with regular expressions, another tool with which to locate the relevant material. For instance, the following rules of thumb are crude but effective: Find a section named "Options" in a page: /^Options Find a subsection named "History" in a page: /^ History (where 3 spaces lie between ^ and "History"). _If_ we added yet another groff extension to man(7), analogous to mdoc(7)'s `Sx`, we could support hyperlinks directly to man page sections and subsections. (On terminals, we'd still need a way to mark locations in the page text as link targets, and for it to be practically useful, pagers would have to grow more features. Given the amount of idiocy, particularly from people who think that a URL in a terminal window is a security risk in some way that a URL on a web page isn't, that Egmont Koblinger has had to put up with in promulgating OSC 8, I would not count on the infrastructure for this materializing soon.) But for PDF all the pieces are in place; they just need some glue in the groff man(7) package. > Maybe it's not so easy to do the change. Changing the lettercase of the (sub)section headings in groff's ~60 man pages was not difficult. "sed -i" was equal to the task. :) Regards, Branden
Attachment:
signature.asc
Description: PGP signature
