[BUG] "\fC" macro in ox-man.el [9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)]

[BUG] "\fC" macro in ox-man.el [9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)]

[Xiyue Deng]

Remember to cover the basics, that is, what you expected to happen and
what in fact did happen.  You don't know how to make a good report?  See

     https://orgmode.org/manual/Feedback.html#Feedback

Your bug report will be posted to the Org mailing list.
------------------------------------------------------------------------

(This was first reported to Emacs at
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=69483)

"mu4e"[1] (a popular Emacs mail client) uses Org to generate its
manpages.  However, the generated output contains macros that are not
understood by groff.  After some debugging, Jeremy traced this back to
the macro "\fC" used in ox-man.el[2].  Git history shows that this may
have been there since the beginning.  We tried to find a documentation
for the "\fC" macro but has not been able to find one.  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.

Emacs  : GNU Emacs 29.2 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.38, cairo version 1.16.0)
 of 2024-01-20, modified by Debian
Package: Org mode version 9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)

Re: [BUG] "\fC" macro in ox-man.el [9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)]

[Ihor Radchenko]

Xiyue Deng <manphiz@gmail.com> writes:

> (This was first reported to Emacs at
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=69483)
>
> "mu4e"[1] (a popular Emacs mail client) uses Org to generate its
> manpages.  However, the generated output contains macros that are not
> understood by groff.  After some debugging, Jeremy traced this back to
> the macro "\fC" used in ox-man.el[2].  Git history shows that this may
> have been there since the beginning.  We tried to find a documentation
> for the "\fC" macro but has not been able to find one.  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.

This is not an unknown problem. AFAIU, the \fC macro is widely used for
troff, although it is not supported by groff. Check out the ongoing
discussion at https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1049968#15

They suggest the following instead of \fC:

   The best solution known to me is to use an extension to the man(7)
   language.  It first appeared in Ninth Edition Unix (1986) and was
   adopted by a groff release in 2009.  That is the `EX`/`EE` macro pair,
   which sets a monospaced display.  (In other words, filling is disabled
   and a monospaced font selected if necessary.)

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [BUG] "\fC" macro in ox-man.el [9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)]

[Xiyue Deng]

Hi Ihor,

Ihor Radchenko <yantar92@posteo.net> writes:

> Xiyue Deng <manphiz@gmail.com> writes:
>
>> (This was first reported to Emacs at
>> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=69483)
>>
>> "mu4e"[1] (a popular Emacs mail client) uses Org to generate its
>> manpages.  However, the generated output contains macros that are not
>> understood by groff.  After some debugging, Jeremy traced this back to
>> the macro "\fC" used in ox-man.el[2].  Git history shows that this may
>> have been there since the beginning.  We tried to find a documentation
>> for the "\fC" macro but has not been able to find one.  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.
>
> This is not an unknown problem. AFAIU, the \fC macro is widely used for
> troff, although it is not supported by groff. Check out the ongoing
> discussion at https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1049968#15
>
> They suggest the following instead of \fC:
>
>    The best solution known to me is to use an extension to the man(7)
>    language.  It first appeared in Ninth Edition Unix (1986) and was
>    adopted by a groff release in 2009.  That is the `EX`/`EE` macro pair,
>    which sets a monospaced display.  (In other words, filling is disabled
>    and a monospaced font selected if necessary.)

I'm not very familiar with roff so my understanding may be off.
According to the `Safe subset' section in man(7), they mentioned the
following:

,----
| Font changes (ft and the \f escape sequence) should only have the
| values 1, 2, 3, 4, R, I, B, P, or CW (the ft command may also have no
| parameters).
`----

Does it mean `\fC' should be replaced by `\f[CW]'?

Also CCing Jeremy who may have a better idea on how this should be
handled.

-- 
Xiyue Deng

Re: [BUG] "\fC" macro in ox-man.el [9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)]

[Ihor Radchenko]

Xiyue Deng <manphiz@gmail.com> writes:

> I'm not very familiar with roff so my understanding may be off.
> According to the `Safe subset' section in man(7), they mentioned the
> following:
>
> ,----
> | Font changes (ft and the \f escape sequence) should only have the
> | values 1, 2, 3, 4, R, I, B, P, or CW (the ft command may also have no
> | parameters).
> `----
>
> Does it mean `\fC' should be replaced by `\f[CW]'?

I am not sure

man 7 groff has

      Fonts often have trademarked names, and even Free Software fonts
      can require renaming upon modification. groff maintains a
      convention that a de‐ vice’s serif font family is given the name
      T (“Times”), its sans-serif family H (“Helvetica”), and its
      monospaced family C (“Courier”). Histori‐ cal inertia has driven
      groff’s font identifiers to short uppercase abbreviations of font
      names, as with TR, TB, TI, TBI, and a special font S.

So, \fC refers to "Courier".

I did not find any text description of CW font, but my groff
installation has usr/share/groff/1.23.0/font/devdvi/CW font spec:

    name CW
    special
    ...

for comparison, /usr/share/groff/1.23.0/font/devps/CR has

    name CR
    internalname Courier
    ...

which looks more suitable. But CR is not listed in "safe" subset
(man 7 man)

Also, neither CW nor CR work with html output:

with \fC

    .TH "" "1" 
    .PP
    \fBThis is test\fP 
    \fCcode a+b\fP here a+b.

yields (groff -Thtml test.man)

<p><b>This is test</b> <tt>code a+b</tt> here a+b.</p>

Note <tt> tag.

but with \f[CW]

    .TH "" "1" 
    .PP
    \fBThis is test\fP 
    \f[CW]code a+b\fP here a+b.

<p><b>This is test</b> code a+b here a+b.</p>

No special markup is applied to the code.

Same for \f[CR].

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [BUG] "\fC" macro in ox-man.el [9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)]

[Jeremy Sowden]

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

On 2024-03-13, at 11:25:23 +0000, Ihor Radchenko wrote:
> On 2024-03-11, at 17:06:17 -0700, Xiyue Deng wrote:
> > Ihor Radchenko writes:
> > > Xiyue Deng writes:
> > > > (This was first reported to Emacs at
> > > > https://debbugs.gnu.org/cgi/bugreport.cgi?bug=69483)
> > > >
> > > > "mu4e"[1] (a popular Emacs mail client) uses Org to generate its
> > > > manpages.  However, the generated output contains macros that
> > > > are not understood by groff.  After some debugging, Jeremy
> > > > traced this back to the macro "\fC" used in ox-man.el[2].  Git
> > > > history shows that this may have been there since the beginning.
> > > > We tried to find a documentation for the "\fC" macro but has not
> > > > been able to find one.  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.
> > >
> > > This is not an unknown problem. AFAIU, the \fC macro is widely
> > > used for troff, although it is not supported by groff. Check out
> > > the ongoing discussion at
> > > https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1049968#15
> > >
> > > They suggest the following instead of \fC:
> > >
> > >    The best solution known to me is to use an extension to the
> > >    man(7) language.  It first appeared in Ninth Edition Unix
> > >    (1986) and was adopted by a groff release in 2009.  That is the
> > >    `EX`/`EE` macro pair, which sets a monospaced display.  (In
> > >    other words, filling is disabled and a monospaced font selected
> > >    if necessary.)

Thanks for the pointer.  Mildly embarrassed that I didn't find this when
I was doing the initial triage in Debian. :)

> > I'm not very familiar with roff so my understanding may be off.
> > According to the `Safe subset' section in man(7), they mentioned the
> > following:
> >
> > ,----
> > | Font changes (ft and the \f escape sequence) should only have the
> > | values 1, 2, 3, 4, R, I, B, P, or CW (the ft command may also have no
> > | parameters).
> > `----
> >
> > Does it mean `\fC' should be replaced by `\f[CW]'?
>
> I am not sure
>
> man 7 groff has
>
>       Fonts often have trademarked names, and even Free Software fonts
>       can require renaming upon modification. groff maintains a
>       convention that a device’s serif font family is given the name T
>       (“Times”), its sans-serif family H (“Helvetica”), and its
>       monospaced family C (“Courier”). Historical inertia has driven
>       groff’s font identifiers to short uppercase abbreviations of
>       font names, as with TR, TB, TI, TBI, and a special font S.
>
> So, \fC refers to "Courier".
>
> I did not find any text description of CW font, but my groff
> installation has usr/share/groff/1.23.0/font/devdvi/CW font spec:
>
>     name CW
>     special
>     ...
>
> for comparison, /usr/share/groff/1.23.0/font/devps/CR has
>
>     name CR
>     internalname Courier
>     ...
>
> which looks more suitable. But CR is not listed in "safe" subset (man
> 7 man)
>
> Also, neither CW nor CR work with html output:
>
> with \fC
>
>     .TH "" "1"
>     .PP
>     \fBThis is test\fP
>     \fCcode a+b\fP here a+b.
>
> yields (groff -Thtml test.man)
>
> <p><b>This is test</b> <tt>code a+b</tt> here a+b.</p>
>
> Note <tt> tag.
>
> but with \f[CW]
>
>     .TH "" "1"
>     .PP
>     \fBThis is test\fP
>     \f[CW]code a+b\fP here a+b.
>
> <p><b>This is test</b> code a+b here a+b.</p>
>
> No special markup is applied to the code.
>
> Same for \f[CR].
>
> > Also CCing Jeremy who may have a better idea on how this should be
> > handled.

What I did for the mu4e man-pages was to patch them to alias font C to B:

    .ftr C B

My initial assumption when I first looked into this is that the font to
use would be `CR`, not `CW`.  Doing this with `CR` does seem to work:

    $ cat /space/azazel/tmp/test.man 
    .ftr C CR

    .TH "" "1"
    .PP
    \fBThis is test\fP
    \fCcode a+b\fP here a+b.
    $ groff -Thtml /space/azazel/tmp/test.man | tail -5 | head -2
    <p style="margin-top: 1em"><b>This is test</b> <tt>code
    a+b</tt> here a+b.</p>

However, as you observe, `\f[CR]` doesn't (nor does `\f(CR`).  I note
that groff's HTML support is stated in the grohtml(1) man-page to be in
beta.  Haven't checked the source to determine whether that is what's
going on here.

In any case, my understanding from reading the conversation in the
Debian bug-report is that this issue affects multiple roff generators in
Debian.  Therefore, it probably makes sense to consult within Debian
before asking the maintainers of those generators to make changes.  I
need to go over that conversation again and think about this more.

J.

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

Re: [BUG] "\fC" macro in ox-man.el [9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)]

[Ihor Radchenko]

Jeremy Sowden <azazel@debian.org> writes:

> In any case, my understanding from reading the conversation in the
> Debian bug-report is that this issue affects multiple roff generators in
> Debian.  Therefore, it probably makes sense to consult within Debian
> before asking the maintainers of those generators to make changes.  I
> need to go over that conversation again and think about this more.

It looks like the final fix they arrived to is
https://github.com/cpuguy83/go-md2man/commit/d85280db9b54b5747fe8cf9380a9f278e1a352d3
- use \fB and drop \fC completely.
For Org mode, it would imply rendering things like fixed-width text in
bold... I doubt that it is a good idea at all.

That said, I still have not the slightest clue what we can do to get rid
of the warning.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>