Re: Getting semantically-correct mdoc fonts outside of requests

[Ingo Schwarze <schwarze@usta.de>]

Hi Nab,

Nab wrote on Sat, May 28, 2022 at 09:03:13PM +0200:

> This is something I've run my head into again and again while using
> tbl(7) tables ‒ since you cannot usefully execute mdoc requests

I assume you mean "mdoc macros" here.
No such thing as "mdoc requests" exists.

Except in very exceptional cases, it is bad style to use tbl(7)
inside mdoc(7).  Whenever possible, use the .Bl macro instead,
preferably .Bl -tag where possible, or .Bl -column when you really
need a table with more than two columns.

If you do have a very exceptional case (that never happened to me
even though i have used mdoc(7) a lot), then keep your usage of tbl(7)
as simple as possible.  All the fancy features are only implemented
for compatibility with legacy pages written in bad style.
Using macros inside tbl(7) certainly isn't simple.  If you do need
macros in the table, go for .Bl, that's what it was designed for.

The above explains why the problem barely exists in mdoc(7).
However, it does exist in man(7) where nothing like .Bl is
available, and where consequently embedding tbl(7) is much more
common than in mdoc(7).

Until support for man(7) macros inside tbl(7) gets implemented in 
mandoc(1), you have two options:

 1. Preferably, use the font specifiers in the tbl(7) layout,
    for example: https://man.openbsd.org/tbl.7#b

 2. If for some reason, option 1 does not work, for example
    because you need more than one font in the same cell,
    use explicit \f escapes.

Yes, the above both use presentational rather than semantic markup,
but that is normal for man(7) in general.

> while in a table, I've been either hardcoding fonts or in recent
> passes doing
>   .ie n .ds fAr I
>   .el   .ds fAr CI
> (with a preprocessing pass for mandoc which pretends to be nroff even
>  when it's typesetting;

The mandoc(1) program never does real typesetting.  Even the PostScript
and PDF output modes in mandoc(1) are driven by the terminal formatter.
That is why mandoc(1) always runs in nroff mode and never in troff mode.
Besides, in mandoc(1), neither -Tps nor -Tpdf support any constant-width
font.

For mdoc(7), preprocessing is useless because the mdoc(7) source
code is intended to be installed on the end-user's system,
so usually, there is no system component that could run any kind
of preprocessor.

At least for mandoc(1), you don't really want "CI" for .Ar:
 * For terminal output, the "C" makes no difference.
 * With mandoc(1), PS and PDF output is basically just wrapped
   terminal output, so "C" makes no difference either.
 * For HTML out, we have:
      $ printf '.Ar foo' | mandoc -mdoc -Thtml
     [...]
     <var class="Ar">foo</var>
   and then in the default mandoc.css:
     .Ar { font-style: italic; font-weight: normal; }
   So there is no "C" either.

Which means that if you put "CI" for .Ar inside tables,
you just make the .Ar inside the table look different
from the .Ar outside, in HTML output mode.

> groff needs I/CI distinctions since tty output
> is 4-font only and C? fonts render as R).

What's wrong with just using \fI in n mode and \f(CI in t mode,
with both groff and mandoc, in case you absolutely insist on
mixing mdoc and tbl, which you probably shouldn't?

The style of your manual page will of course be horrible because
not only are you mixing mdoc(7) and tbl(1), but you would be
using low-level roff like \f, .ds, and .if on top of that.

> This does work, but (a) it's ass and (b) duplicates the macro package,
> badly.
> 
> groff's doc.tmac sets doc-??-font strings for all the semantic macros,
> such that \*[doc-Nm-font] expands to \fB under nroff
> and \f(CB (+ a font size reset) under troff, d-Pa-f to I/C, &c.
> Now, mandoc's mdoc doesn't really allow for that in a trivial fashion,
> especially in its much richer -Thtml output which doesn't trivially map
> to/from 8 fonts, but, well, that's my best attempt at prior art.

For HTML output, the whole point of mandoc(1) is writing class=
attributes, for example class=Ar, and leaving font selection to CSS.
So until support for mdoc(7) inside tbl(7) gets implemented in
mandoc(1), there is no way to get good HTML output from mandoc(1)
when you use words that need class= markup inside tbl(7) code, and
there is no workaround either.  Just don't use tbl(7) in mdoc(7),
it doesn't work well and would be bad style even if it did work.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv