Hi Branden, On Sat Oct 26, 2024 at 3:33 AM CEST, G. Branden Robinson wrote: > At 2024-10-25T16:51:26+0200, onf wrote: > > I wonder if the author tried Drew DeVault's scdoc, it seems to work > > well for simpler manpages. (Output is man.) > > I'm not crazy about the non-idiomatic section titles or organization.
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. > But the bigger point is that it's _easy_ to implement this sort of thing > for _simpler_ man pages, as you put it. > > The problem is that the boundary between "simple" and "not simple" is > not well-defined by any man(7) generator I've seen, so a page author > using one of these "easier", "simpler", or "smarter" tools doesn't have > a good way of knowing, short of experimentation, when they're going to > end up off the beaten track anticipated by the author of the converter. > > Worse, to hearken back to Kernighan's critique of standard Pascal, > "there is no escape". As far as I know, none of pod2man(1), > asciidoctor(1), docutils(1), or pandoc(1) supports a syntax for inlining > "raw" man(7)/*roff source into a document. I can well imagine why > people don't want to support that, but when combined with the deficiency > in the previous paragraph I think it erects a barrier to composition of > adequate man pages, let alone good ones. I think you've just discovered the exact definition of a "not simple" manpage. That is, it's a manpage for which these generators no longer suffice. > I admit that that's not a complaint users of these conversion source > languages seem to raise often. I suppose that this is for the usual > reason that most programmers (and their managers) disdain technical > writing. It's not "real work" and doesn't "deliver value". > > [...] I don't think it's as simple as you present it. I totally understand why people don't want to spend several hours understanding troff syntax just to be able to document the flags and key bindings of their program in manpage format.[1] 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. I remember sending a patch to the GNU grep team fixing their manpage because someone added non-troff bold/italic escapes[2] and either no one noticed it for over a year before me or no one bothered to fix it. The great positive effect I see with scdoc and similar is that contributors actually bother to update the manpage when they modify the program's behavior. I also wouldn't be so sure about the use of manpage generators being the result of not valuing documentation. For instance, the ffmpeg project, which ships basically all of its documentation as a manpage, generates manpages from texinfo (via podman iirc). The problem with ffmpeg's manpages is not the quality of its writing or formatting -- it's its poor navigability. Even though the age of hard-copy terminals is long gone, man viewers still don't even have something as basic as table of contents, which makes long manpages[3] hard to use. That's presumably the reason why many projects opt to use a different format for its primary documentation (even groff, in fact). 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. Even just being able to get a listing of all subheadings and their line numbers (so that one can use less's g command) would help. (As a matter of fact, I wrote a script to do that for me, but I really don't get why I even had to in the first place.) Similarly, it would be really helpful if there were mandb subsections. Perl attempted to do that with its 3p section, but apropos treats it like section 3 anyway. Almost every time I try to search for POSIX API docs by specifying section 3, I get the Perl wrappers with it. The combination of these two issues makes it impractical to use manpages as a main documentation format, which is a shame. The state of many projects' manpages reflects this, just as does the article you linked. I feel like for most users, manpages are a relict of old Unix times, written in an arcane "markup" language few people understand. It's no wonder then that many new projects don't even bother shipping with manpages. Notable examples I found locally include cython, go, ninja, rake, pip, pydoc, and sqlite3. All of them have decent documentation, it's just that none of it is in manpage format. They all even print a long synopsis if invoked with -h or --help, which would surely be more readable if someone converted it into a manpage. But, presumably, no one was around who understood the syntax and no one felt it a good use of their time to learn it to do just that. And I'm saying all that as someone who first goes to the relevant manpage when he isn't sure how something works. And all too often has to open the browser and look up online documentation because the manpage doesn't cover it in enough depth. [1] Example: mupdf(1) <https://man.voidlinux.org/mupdf> [2] It looked like I<PATTERNS>. I wonder if it's something carried over from texinfo. [3] Such as ffmpeg-filters(1) <https://man.voidlinux.org/ffmpeg-filters>
