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
