Follow-up Comment #10, bug #67881 (group groff): Hi Ingo,
At 2026-01-05T05:39:22-0500, Ingo Schwarze wrote: > Follow-up Comment #7: > [comment #6 comment #6:] >> Ingo, did you mean to reopen this? > > No, i did not intend to reopen this, sorry about that, and i'm not > completely sure how that happened - maybe because i started writing > the comment before you resolved the ticket but didn't finish it until > after you resolved it, so maybe Savannah reverted part of your changes > including the status. It's a bit of a pain that even when using the > "Preview" button, Savannah does not tell the user which changes the > "Submit" button will subsequently commit. Yeah, probably not your fault. I am used to (as is Dave, I think) Savannah instead being so sensitive to data desync that it throws up a failure page even for harmless discrepancies. Sounds like it's now found a way to err on the other side. Exciting times. > The main purpose of the comment was to ask whether the two mandoc > pages need an update. I hadn't given that much thought; it's your project. I'm only likely to complain if I see something in them that I think is flatly incorrect. >> What would you like to see done, or what defect do you perceive in >> Git HEAD? > > One grammatical mistake is obvious: > > As a typesetting system, > .Xr roff > distinguishes hyphens, > minus signs, > -and various sorts of dash. > +and various sorts of dashes. > > Feel free to commit that yourself or tell me to. Ah. I think it might be standard because "dash" is not a countable noun in this sense, but an abstract class. (Recall the Monty Python gag regarding tree recognition--when one recognizes "the larch", all instances of the species are meant, not merely the one depicted in the photograph.) However, I think I can improve on either formulation with +and dashes of various widths. > The new text is not particularly clear in a number of respects: > > * Unlike the mdoc(7) page from mandoc, groff_mdoc(7) never properly > introduces the concept of escape sequences, even though it talks > about escape sequences in various places. For comparison, mdoc(7) > says up front: > > Many aspects of the basic syntax of the mdoc language are based > on the roff(7) language; see the LANGUAGE SYNTAX and MACRO SYNTAX > sections in the roff(7) manual for details, in particular > regarding comments, escape sequences, whitespace, and quoting. > However, using roff(7) requests in mdoc documents is discouraged; > mandoc(1) supports some of them merely for backward > compatibility. Fair. I could copy over the "Fundamental concepts" subsection from _groff_man_style_(7), or refer the reader to _roff_(7), trusting that whichever version of that page the reader gets--_groff_roff_(7) or _mandoc_roff_(7)--will put them in the picture. > * The phrase "roff distinguishes hyphens, minus signs, and various > sorts of dashes" is less helpful than it could be because it fails > to say how it distinguishes those; I think that's out of scope for the page; _groff_char_(7) is about as far as I personally care to go in teaching the man page author the semantics of hundreds of glyphs. > pointing to groff_char(7) would be helpful, even though unlike > mandoc_char(7), groff_char(7) lacks a section "Dashes and Hyphens" and > the related information appears scattered around various places. For *roff purposes, there's -, \-, and everything else. Pedagogically, I mean. The breaking semantics of the various characters are another matter. > * Admittedly, there is a pointer to groff_char(7) in the preceding > paragraph, but that paragraph appears to be unrelated (and it > appears in a place that puts way too much emphasis on it - \( and > \*( are quite arcane technicalities of minimal importance that are > not well-placed above all the important stuff), so users will likely > not understand that's the place to learn how to distinguish hyphens > and dashes, unless they already know. I'll review. > * The wording seems both more cumbersome and less clear than it could > be. It is not made explicit what "hyphen-minus" refers to (the > ASCII and Unicode code point name) and it is unclear what the point > of copy-and-paste is unless you unambiguously and explicitly say > what the intended output glyph is. This could be made clearer by > talking about 'an ASCII 0x2d “hyphen-minus” output glyph' (as in > mandoc_char(7)), or a similar wording. For example, the wording > "U+002d" could be used if you prefer talking about Unicode to > talking about ASCII. In caps, yes, I'd prefer to speak of U+002D. > * Several of the section titles in groff_mdoc(7) are not descriptive: > what is the difference between "Description", "Getting started", > "Usage", and "Other possible pitfalls"? This could use some > sorting, i guess. I inherited most of those from my forebears. You remind me about a pet peeve I've long had--I dislike a page having both "Description" and "Usage". I think this practice arose because impatient Unix nerds who don't care much for learning a system carefully suffer under the delusion that an "Options" section needs to come within the first "screenful", no matter what the terminal dimensions. So the practice arose of boiling a page down to a one-paragraph introduction, immediately lurching into the "Options" section, which routinely introduces sundry concepts for the first time, then, that finished, switches to a "Usage" section presenting the material that the reader needed to comprehend the "Options" section in the first place. If it's not obvious, I think that's a dumb way to organize things. If a person already has the prerequisite knowledge, then a "usage" message summarizing command invocation is all they require; they don't need a man page at all unless they intend to spend more than five seconds reading. And proper hackers not only don't care to spend more than five seconds at a time reading documentation, they don't want to spend more than that per episode of _writing_ it, either...if that. https://www.tomshardware.com/software/linux/linuxs-contemporary-filesystem-mount-api-went-without-documentation-for-six-years-latest-man-page-package-finally-adds-content-for-2019-code Brauner's diagnosis is that *roff is the problem. If only he-man kernel hackers didn't have to put up with a formatting language from Bell Labs in 1970s (except they think it's from GNU in 1989), they'd produce TONS of documentation. If you just pick the correct markup language, documenters will show up in droves. Kernel hackers are some smart guys. They always know the optimal time to purge the I-cache, have mastered every algorithm in CLRS, and interview brilliantly at Alphabet or Meta, and have a mastery of every two-letter command-line program that rivals Thompson himself's. But the 30 one- or two-letter macros of man(7) utterly defeat them. Given that, Markdown is, obviously, the correct choice. They won't discuss which of its dialects is perfect; it's more important to unite against the common enemy, the *roff man page. Brauner's brilliant slice of Linux kernel documentation's Gordian Knot has produced a repository that has racked up... ...65 commits in just under two years. https://github.com/brauner/man-pages-md/commits/main/ Let's compare. I produce that many commits to just one documentation subdirectory of _groff_ in... $ git show $(git log --oneline man | awk 'NR == 65 { print $1 }') | sed -n '1,/^$/p' commit 05144a36e4e434abd1203516226feb9bd9c7d9ca Author: G. Branden Robinson <[email protected]> Date: Wed Dec 10 16:07:35 2025 -0600 ...under one month. _groff_ is vanishingly small compared to the Linux kernel and has always had a tiny development community in comparison. What this says about Linux kernel developers' capacity to "bro down" and write some documentation in service of Torvalds's stated objective of "world domination", I leave to the reader's inference. https://www.linuxjournal.com/article/36 I have my own diagnosis of what afflicts documentation production in the Linux kernel community, but it won't make me any friends, so I'll leave it for another time. And those guys won't listen to an outsider anyway. They'll learn once they absolutely have to. Maybe after the sixth or seventh disaster that strikes _even though_ the interface in question is documented in Markdown, which as we've seen might take a while. Anyway, yes, I'm aware of your preference regarding "Options", that being to omit it entirely. I reiterate that I don't find it tractable given the prevlance of "long options", and many of them, that GNU/Linux programs tend to sport. And, yes, I'm aware that OpenBSD and the *BSDs generally feel they have a superior approach. If you like, you can use the presence of an "Options" section in a man page as a fairly reliable indicator that you're reading about incorrectly designed software. ;-) _______________________________________________________ Reply to this item at: <https://savannah.gnu.org/bugs/?67881> _______________________________________________ Message sent via Savannah https://savannah.gnu.org/
