Re: (off topic?) Docbook? Re: manlint?

[Ingo Schwarze]

Hi James,

James K. Lowden wrote on Tue, Sep 29, 2020 at 11:27:20AM -0400:

> or, mdoc style
> 
> .SH Id foo Class bar
> Your title here

That absolutely isn't mdoc(7) style.

You are discussing a problem that has been solved years ago, and
the solution has proven very successful in practical use: mdoc(7)
style is that you *never* specify the class manually but the macro
name *is* the class.  So, the arguments of an .Sh macro get assigned
class "Sh", and you can use CSS to format elements having the class.
That also makes a lot of sense because specifying the semantic
function (i.e., "class") of a piece of text is the whole point of
a macro in the first place.

Then, mdoc(7) style is to usually *not* specify the ID manually
either but instead just use the text content itself, if required
by HTTP or URI syntax with minimal transformations.  Several years
of practical experience show that specifying the ID manually is
very rarely needed.  Here are some typical examples:

  https://man.openbsd.org/mandoc.1#HTML_Output
  https://mandoc.bsd.lv/pta/man/pta.1.html#b
  https://man.voidlinux.org/man1/tmplgen.1#DESCRIPTION
  https://www.freebsd.org/cgi/man.cgi?query=freebsd-update#COMMANDS
  
https://jlk.fjfi.cvut.cz/arch/manpages/man/extra/yasm/yasm_arch.7.en#BITS_Setting

Then, for the rare cases where it is necessary to specify than an
anchor is desired at some place (which is rare, too, usually even
that can be implied from the code itself), mdoc(7) style is to
insert the ".Tg" (tag) macro.  It has been implemented on January
19, 2020, and has proven useful since, even though it is needed
relatively rarely.  It is documented here:

  https://man.openbsd.org/mdoc.7#Tg~2

The .Tg macro typically does not need any argument because
its argument just defaults to the argument of the macro being tagged,
similar to fully automatic tagging as explained above with the example
of .Sh.  Typical exemple:

  https://man.openbsd.org/route.8#exec

Corresponding source code:

  .Bl -tag -width Fl
  .It Xo
  .Nm route
  .Op Fl T Ar rtable
  .Tg
  .Cm exec
  .Op Ar command ...
  .Xc
  Execute a command forcing the process ...

In even rarer cases, the ID can be specified explicitly as an
argument to the .Tg macro:

  https://man.openbsd.org/ddb.4#examine

Corresponding source code:

  .Tg examine
  .It Xo
  .Oo Ic e Oc Ns
  .Ic x Ns Op Ic amine
  .Op Cm /bhlqaAxzodurcsmiI
  .Op Ar addr Ns
  .Op Ic \&, Ns Ar count
  .Xc
  Display the contents at address

It is *not* a coincidence that these examples are very complicated.
Unless stuff is very complicated, .Tg is pointless in the first place
because everything works completely automatically whithout any need
for the author to manually specify what to tag.

Admittedly, i did not yet implement .Tg for groff.  It might be
possible, but i consider it low priority because groff HTML output
is low quality in the first place and there is not much that can be
done about the fundamental weaknesses, so adding fancy features on
top of something that is unavoidably weak and fragile seems a bit
like wasting time.

Besides, it is not a big problem that groff does not support .Tg.
That .Tg is always on its own line is among the most important
aspects of its design, so formatters not supporting it just ignore
it and no harm is done.

I do not doubt that similar features could be implemented in other
macro sets that support samantic markup.  For man(7), however, there
is relatively little hope because with negligibly exceptions, man(7)
is designed as a *physical* markup language and man(7) macros usually
provide no clues what the function of the marked-up words is.  Trying
to add class and ID support on top of a *physical* markup language
looks like a fool's errand to me...

All the same, limited fully automatic assignment of classes and IDs
even works for man(7):

  https://man.openbsd.org/cvs#import
  https://man.openbsd.org/gcc#c

> I would like to think that we could compatibly add attributes
> to macros that don't take arguments.

Adding attributes isn't needed, and when it comes to defining syntax,
less is more.  Remember that authors will not be amused because they
have to type in all that syntax you are inventing.  I expect they
will be more pleased if they can focus on the content.  Consequently,
strive to design the macro sets such that classes and IDs work
automatically, for other macro sets just like for mdoc(7).

Yours,
  Ingo