discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: наб <nabijaczleweli@nabijaczleweli.xyz>
To: Ingo Schwarze <schwarze@usta.de>
Cc: discuss@mandoc.bsd.lv
Subject: Re: Getting semantically-correct mdoc fonts outside of requests
Date: Sun, 29 May 2022 02:15:00 +0200	[thread overview]
Message-ID: <20220529001500.gnxuiiawdegcjwy7@tarta.nabijaczleweli.xyz> (raw)
In-Reply-To: <YpKiKzty5g1bdd2r@asta-kit.de>

[-- 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 --]

  reply	other threads:[~2022-05-29  0:15 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-05-28 19:03 наб
2022-05-28 22:28 ` Ingo Schwarze
2022-05-29  0:15   ` наб [this message]
2022-05-29 17:34     ` наб

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20220529001500.gnxuiiawdegcjwy7@tarta.nabijaczleweli.xyz \
    --to=nabijaczleweli@nabijaczleweli.xyz \
    --cc=discuss@mandoc.bsd.lv \
    --cc=schwarze@usta.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).