Getting semantically-correct mdoc fonts outside of requests

Getting semantically-correct mdoc fonts outside of requests

[наб]

[-- Attachment #1: Type: text/plain, Size: 981 bytes --]

Hi!

This is something I've run my head into again and again while using
tbl(7) tables ‒ since you cannot usefully execute mdoc requests 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; groff needs I/CI distinctions since tty output
 is 4-font only and C? fonts render as R).

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.

So: is there a better way?

Best,
наб

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Getting semantically-correct mdoc fonts outside of requests

[Ingo Schwarze]

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

Re: Getting semantically-correct mdoc fonts outside of requests

[наб]

[-- Attachment #1: Type: text/plain, Size: 5524 bytes --]

Hi!

On Sun, May 29, 2022 at 12:28:59AM +0200, Ingo Schwarze wrote:
> 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.

Yes.

> 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.

Yes. This is why I specifically asked "how would you use mdoc macros in
tbl", not "how do you make a table in mdoc" (also, notably, the groff
manual disagrees:
  Don't abuse this list type!  For more complicated cases it might be
  far better and easier to use tbl(1), the table preprocessor.
and, indeed, it is better, because it has table decorations. Because I'm
(trying to) write a table, not, as mandoc's mdoc(7) puts it, a
"columnated list").

> 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.

This is why I didn't ask "how do you set a font".

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

Taking this as a "not possible, don't want to support".

> > 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.

Fair, I guess.

> 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.

Which is why I'm /pre/processing it /before/ it's distributed.

> 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.

Indeed. I had been working off my openbsd-derived stylesheet which I
(apparently) modified to have .Ar be CI, not I.

> 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.

Except that depends on the styling. Which is why I wanted to replicate
the actual output you get from mandoc's mdoc package..

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

This is what I'm doing, yes.

> 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.

Which is, again, why I wanted to write this page better. To your
unceasing puritan objections.

> > 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.

At least here we agree.

> 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.

Well, I've never had problems (save for this one).

Ah well,
наб

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Getting semantically-correct mdoc fonts outside of requests

[наб]

[-- Attachment #1: Type: text/plain, Size: 642 bytes --]

Hi!

I rotated this in my head overnight, and have decided that the
least-worst solution compatibility-wise is to do
  .if !ddoc-Ar-font .ds doc-Ar-font \fI
  .if !ddoc-Li-font .ds doc-Li-font \f(CR
  .if !ddoc-Nm-font .ds doc-Nm-font \fB
  .if !ddoc-Pa-font .ds doc-Pa-font \fI
&c., which is correct for groff mdoc (OOB)
and mandoc (by font-matching the default styling);
with a custom style, this can trivially be made to match by injecting
  printf '.ds doc-%s-font \\f[%s]\n' Ar CI  Nm CB  [macro font]...
for -Thtml output, since that's where you specify -Ostyle anyway.

Thanks for your input on this :)

Best,
наб

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]