Re: ripgrep author seems happy with groff_man_style(7)

[onf]

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 $?