Re: ripgrep author seems happy with groff_man_style(7)

[Ingo Schwarze]

Hi branden,

G. Branden Robinson wrote on Tue, Jan 21, 2025 at 12:27:36AM -0600:

[...]
> Possibly I'll formally propose an `SX` macro for man(7) at some point.

You mean that like mdoc(7) .Tp, not like mdoc(7) .Sx, right?

> It's not a high priority, nor in the near future because the automatic
> tagging problem is more fundamental and more important;

I strongly agree.  For exactly that reason, mandoc(1) supports
automatic tagging since July 2015 and manual tagging via .Tg
only since January 2020.  I allowed automatic tagging to mature
for half a decade before finally deciding that in rare cases,
supplementing it with manual tagging can be useful.

After five years of manual tagging being available, nine out of the 3472
manual page files in the OpenBSD manual page tree now use manual tagging:

   $ grep -Fl .Tg */*.[1-9]       
  man1/man.1
  man1/openssl.1
  man1/tmux.1
  man4/ddb.4
  man5/bgpd.conf.5
  man7/mdoc.7
  man8/ifconfig.8
  man8/pfctl.8
  man8/route.8
   $ ls */*.[1-9] | wc -l
  3472

So as expected, demand isn't exactly overwhelming: about three permille.

> with it, one could automatically generate a hyperlinked multi-level
> table of contents for any man(7) document, with no kludges.

You mean, like

  https://man.bsd.lv/mdoc.7
  https://man.bsd.lv/pf.conf.5
  https://man.bsd.lv/openssl.1
  https://man.bsd.lv/tmux.1
  https://man.bsd.lv/ddb.4
  https://man.bsd.lv/bgpd.conf.5
  https://man.bsd.lv/ifconfig.8
  
> That feature seems, by dint of having seen it done in ad hoc ways by
> man-to-HTML converters, much more in demand than document-directed ad
> libitum referencing at a finer-grained level than an entire man(7)
> or mdoc(7) document.

TOCs more in demand than cross-document deep linking?
Yes, i actually agree, that's how i remember interactions with users
as well.

All the same, do not overerstimate the demand.  Not everybody likes
or wants TOCs.  For example, Theo de Raadt and some other OpenBSD
developers hate TOCs so much that they got vetoed from and
disabled on man.openbsd.org - even though they are completely
supported by the software running there and only appear in documents
containing at least two non-standard section titles, which is a tiny
fraction of documents.

[...]
> My plan for resolving _that_ problem is to introduce a string sanitizer,
> probably in a new macro file "string.tmac", which people can use for
> common operations on strings.

You mean, like the recursive function deroff() in

  http://cvsweb.bsd.lv/~checkout~/mandoc/roff.c?rev=HEAD

That one is an internal mandoc API and cannot be called from documents,
but the purpose is similar: break down a tree of nodes to a
plain string.

It is used:
 - by the mdoc(7) validator to break down the content of the .Os
   and the first .Nm macro and the heads of .Sh and .Ss macros
 - by the HTML formatter for section and subsection titles
 - by the man(7) parser of makewhatis(8) to break down the NAME section
   and the content of .Nd and .Va macros

> Little or none of this is anything mandoc will ever have to care about.

As you see above, mandoc does encounter some of these tasks as well.

Some of what you said above (not necessarily all of it) sounds as if you
are about to expose internal implementation details to the end user.
If you do that, some fool out there will sooner or later use such
internals, eventually even in manual pages, and then mandoc(1) may
indeed be forced to deal with it.

Yours,
  Ingo