[Ingo: see bottom of message for a possible mandoc(1) bug in footnote 2]

Hi Ihor,

At 2024-12-22T15:41:57+0000, Ihor Radchenko wrote:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> 
> >> Jeremy suggests that "C" may be an old alias for Courier, and if
> >> that's the case it should be changed to "\f[CR]".  Would be great
> >> if Org people can confirm.
> >
> > That is good advice and it is what I recommend if you're writing in
> > "raw" roff.  The context of the discussion is not ultra-clear to me;
> > is ox-man.el a replacement for the old GNU Emacs man pager, "woman"?
> 
> Nope. ox-man is a converter between Org markup and Man page sources:
> 
> Given the following Org markup:
> 
>   *This is test*
>   ~code a+b~ here a+b.
> 
>  [*...* is bold markup. ~...~ is code markup.]
> 
> we aim to produce a valid man file that approximates the initial Org
> markup as much as possible:
> 
>     .TH "" "1" 
>     .PP
>     \fBThis is test\fP
>     \fCcode a+b\fP here a+b.

I understand now.  I've taken some time to learn a bit more about Org
mode, and also that org-man.el seems to be something close to the
bleeding edge; in a Debian unstable chroot it was not provided by the
version of GNU Emacs (29.4) nor the "elpa-org" package (9.7.16).

So I'll make some recommendations unfortunately without the benefit of
having field-tested them.

> And this discussion was about using \fC to represent "code" (also,
> "fixed width" and tables). We use \fC historically, and it is not very
> clear what could be a replacement that does not break Man export
> compared to previously produced results.

The answer depends on how portable you want your man(7) output to be.  A
major reason is that font names are not portable across output devices;
this was not thought to be a need when Brian Kernighan refactored the
troff of Seventh Edition Unix for device-independence circa 1980.  When
James Clark wrote groff in about 1989, he tried to standardize font
names across devices.  But he also accommodated users of AT&T troff,
providing aliases for many of the font names used by its dpost(1) output
driver, and also didn't write all the diagnostic messages he could have,
with the consequence that `\fC` sometimes worked, but also often
silently failed, and few people noticed the difference.  The last factor
especially applies to users of terminals, where changing the font family
in this manner is impossible anyway.

`\f(CR` will work with groff, Heirloom Doctools troff, and neatroff.

It won't work with mandoc(1) 1.14.6 (or earlier, I suspect), but then
neither does `\fC`.[1][2]  It won't work with Solaris 10 troff (and
therefore Illumos troff) or Plan 9 from User Space troff.

Given that, you might as well spell the escape sequence as `\f[CR]`,
using GNU troff syntax for arbitrary-length escape sequence arguments.
You can say either `\fP` or `\f[]` to restore the previous typeface.

> Ok. But will it work inline?

There is no portable way to achieve that across all known man(7) (or
troff(1)) implementations.  But if you care only about the formatters I
mentioned as groff-compatible above, then `\f[CR]whatever\f[]` should
work fine.

> From my reading of man 7 man, .EX/.EE are more suitable for paragraph
> markup:
> 
>        .EX
>        .EE    Begin and end example.  After .EX, filling is disabled
>               and a constant-width (monospaced) font is selected.
>               Calling .EE enables filling and restores the previous
>               font.
> 
>               These macros are extensions introduced in Ninth Edition
>               Research Unix.  Systems running that troff, or those
>               from Documenter’s Workbench, Heirloom Doctools, or Plan
>               9 troff support them.  To be certain your page will be
>               portable to systems that do not, copy their definitions
>               from the an-ext.tmac file of a groff installation.

Yes.  `EX`/`EE` works only with "displays".

But it is worth noting that `EX`/`EE` is _more_ portable than `\fC`.

> Ok. So much for testing via man->HTML exporter.
>
> What about PDF?

groff's PDF support is pretty good.  I use it all the time myself.

Here's an exhibit of dogfooding:

https://www.gnu.org/software/groff/manual/groff-man-pages.pdf

In groff 1.24, that document will be about 75% smaller in file size (due
to subsetting of embedded fonts), and will feature hyperlinks for all
man page cross references, internally where applicable, and as "man:"
URIs for external references.

So.  To my recommendations:

Going by
<https://github.com/emacs-mirror/emacs/blob/master/lisp/org/ox-man.el>
and ignoring indentation,

I would change line 369 to:

(format "\\f[CR]%s\\f[]"

and line 438 to:

(format "\\f[CR]\n%s\n\\f[]"

and line 538 to:

(format ".RS\n.EX\n\\m[black]%s\\m[]\n.EE\n.RE\n"

and lines 543-544 to:

(concat ".RS\n.EX\n" (org-man--protect-example code) "\n"
        ".EE\n.RE\n")))))

and line 758 to:

(format ".RS\n.EX\n%s\n.EE\n.RE\n\n"

(I would also delete that trailing "\n".  Avoid blank lines in man(7)
input.[3])

and line 782 to:

(format ".RS\n.EX\n\\m[black]%s\\m[]\n.EE\n.RE" (org-man--protect-example code))))))

and finally line 844 to:

(format ".EX\n%s\n.EE"

(As another aside, the stroke color selection escape sequences `\m` are
(a) GNU troff extensions, albeit supported by the same formatters that
`\f[CR]` is, but (b) probably unnecessary because nothing else in this
entire file seems to use any other color for anything.)

You can test a generated man(7) document by asking groff(1) and man(7)
to lint it.

$ groff -ww -rCHECKSTYLE=3 -man my-org-doc.man

Please let me know if/how I can be of further assistance.

Regards,
Branden

[1] If you "lint" your document, mandoc(1) will even tell you so.

    $ mandoc -T lint blah.man
    mandoc: blah.man:5:12: WARNING: invalid escape sequence: \fC

[2] Actually, it looks like `\f(CR` (or `\f[CR]`) _should_ work with
    HTML output in mandoc(1).  It brackets the word with a "span"
    element using the "Li" class (a reference to the mdoc(7) `Li`
    macro--mandoc(1)'s authors and maintainers are big-time mdoc(7)
    partisans).  But, nothing in the `head` element bothers to define
    the `Li` class when formatting a man(7) document.  This seems like a
    bug in mandoc(1) to me.

    mandoc(1) uses an external program to produce PDF from HTML, so
    inspecting its PDF output tells you nothing that its HTML output
    doesn't.

[3] groff_man_style(7):

     •  The empty request (.), which does nothing, vertically spaces the
        input file for readability by the document maintainer.  Do not
        put blank (empty) lines in a man page source document.  Some
        man(1) programs “squeeze” multiple blank output lines into one.

Regards,
Branden