Hi Alexis, On Sun Nov 3, 2024 at 8:39 AM CET, Alexis wrote: > > It's not that documentation isn't important, merely that it's > > not so incredibly important to spend several hours on such a minor > > task. This also becomes a problem in that manpages aren't maintained > > as well as the software because few people understand the syntax. > > By which i presume you mean, the man(7) language rather than the > mdoc(7) language; more on this below. > > i certainly agree that, for people not regularly creating new man > pages from scratch, having to learn roff and a macro library > probably feels like unnecessary work.
I had mostly based this on the original quotation of Andrew Gallant, but personally it took me a while just to get acquainted with the general syntax of troff, understanding how macros and escapes work, etc., even before I learned any macros. So no, I think it applies generally. > > I can imagine manpages would be much more usable if cross-references > > and subheadings etc. weren't just a matter of formatting, but > > actually meant something to the viewer. > > This is one of the reasons i'm an advocate for people using > mdoc(7) for man pages - as is done on the *BSDs - rather than > man(7). Where man(7) is primarily presentational markup, mdoc(7) > is primarily _semantic_ markup. This allows the use of the macros > as search keys for apropos(1); [...] I completely agree with mdoc being vastly preferable to man, and it's a pity it's not used more on the Linux side. Unfortunately though, I feel like its potential is vastly underutilized. While you can absolutely get a list of manpages containing a specific term of a specific type with apropos (like the example you gave), what I was getting at is that you can't say to your pager "jump to the flag -e". The best you can do is `/^ +-e`. I feel like if such features were in place, there would be much bigger incentive to write manpages by hand. With as things are right now, there is very little difference between man and mdoc from the user's perspective (outside of mdoc's consistent formatting, but I doubt many people notice that). And as a result it doesn't really matter if you write your manpage by hand or generate it (with something at least a bit capable, i.e. not from plain markdown) because the end result is fairly similar. > > Speaking of which, I noticed just recently that all of groff's > > manpages don't use all caps for subheadings (.SH)... which is about > > the first time I've seen manpage subheadings that weren't in all > > caps. > > In my mdoc(7) ports of documentation in the skaware ecosystem > (e.g. s6-man-pages, https://git.sr.ht/~flexibeast/s6-man-pages), > i've used sentence case with Ss, the mdoc(7) equivalent of SH. I don't know either of those macro packages well, but the equivalent of man's SH seems to be Sh in mdoc. (I might have confused you by calling them subheadings when they are in fact section headings.) Personally I just find sentence case headings harder to read at a glance because the characters seem smaller. Compare "Name" with "NAME". I feel like ideally, though, the authors should write sentence case and the macros should take care of capitalization if it's desirable (with .stringup or similar)... Clearly mdoc's semantic approach has its limits :) > [...] > > To try to demystify it for others, i wrote this quickstart guide: > https://github.com/flexibeast/guides/blob/master/mdoc-quickstart.md Cool, that's a really nice tutorial! I will try to give some constructive suggestions/criticism... If this is really intended for the absolute beginner who doesn't understand roff, I would suggest properly explaining what roff macros mean before using that term. You use them in Introduction without any explanation, then explain it slightly in the Background section only to dive into the issues with man and the benefits of mdoc without their meaning having been adequately explained. I suggest something along the lines of: roff is a typesetting language ultimately descended from RUNOFF, the first computer typesetting system. In roff, formatting is carried out by the means of so-called requests (formatting commands). To simplify repetitive formatting tasks, requests can be grouped into macros which perform a particular function (such as format its arguments as a heading). A collection of macros which all serve a shared purpose (such as formatting a letter) is called a macro package. Traditionally, the man(7) macro package has been used to format manpages. ... You say that BSD mandoc provides a roff implementation, but afaik it implements only as much roff as is necessary to format manpages.[1] I realize it's difficult to succinctly describe what exactly BSD mandoc is, though. When mentioning the use of \& to disable the meaning of . at the beginning of line, ' (no-break control character) also needs to be mentioned, which is much more common at the beginning of a line. When discussing the Op and Fl macros, the way macro names in arguments are handled by mdoc should be explained, because the fact you call Fl a macro and it appears only as a text argument to Op is confusing. (I know Fl IS a macro, but it's used like a text argument in the code.) The part discussing the It macro makes this feel even more confusing as you write: The It macro is a list Item. It's parsed, so we use the Fl macro as its argument, with a literal as the argument to the Fl macro. but just before that you said: Note that any formatting command is on a distinct line of its own, rather than being inline. You also write that: The -tag argument specifies that item bodies should be indented by the value of the -width argument. but from reading mdoc(7), it seems to me the line: .Bl -tag -width x actually indents by the width of character x, not its numeric value. When you write: Note that a new sentence starts on a new line. To start a new paragraph, use the Pp macro. I would suggest adding that beginning a sentence on a new line is merely a matter of style, not a requirement of the language.[2] When you write an example exit status section, I would expect to hear about the Ex macro, which is often preferable to writing it by hand. And by the way, there is technically no such thing as exit status -1, it becomes 255.[3] Missing word: Man pages referenced in this section should [be] sorted by section number When you write: Note how the commas are a distinct final argument on the request lines; this allows the punctuation to be handled appropriately. I suggest adding something like this at the end: (i.e. being put right after the closing parentheses without any space between them). When you write: Note that we made no roff requests directly; only roff macros were used. I feel like s/roff/mdoc/2 would convey the meaning better. I can also imagine that a section about tbl would come in handy. ~ onf [1] From mandoc_roff(7): To properly format such manuals, the mandoc(1) utility supports a subset of roff requests and escapes. Even though this manual page lists all roff requests and escape sequences, it only contains partial information about requests not supported by mandoc(1) and about language features that do not matter for manual pages. [2] Unless you want inter-sentence space to be larger than inter-word space, but few people actually do that and it's apparently considered old-fashioned in typography circles. [3] Try this: $ err() { return -1; } $ err; echo $?
