Re: ripgrep author seems happy with groff_man_style(7)

[onf]

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>