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

[Ihor Radchenko <yantar92@posteo.net>]

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

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

You looked up wrong file.
Not org-man.el, but ox-man.el.
It is a part of Org mode since forever (introduced before Org 4.12a -
the first tagged release in our git repo - Jan 31, 2008; 16 years ago).

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

You can do the following to try exporting to man from Emacs 29.4:

1. emacs -Q
2. M-: (require 'ox-man) RET
3. Open a sample .org file
4. C-c C-e M m

(4) will produce a man file named after the .org file, in the same directory.

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

1. We want to avoid breaking cases when \fC did work (it is a minimum)
2. Ideally, we want things to work in _more_ cases
3. Even more ideally, we want things to work in all the cases

If (1) is not possible, compromises will have to be made. I hope that we
do not have to make compromises.

Also, what if we leave \fC and add \f[CR]/.EX on top?
AFAIU, the worst case scenario for \fC is that it does nothing. By
leaving it there, we thus retain old working exports working while also
adding appropriate format when \f[CR] is supported.

>> From my reading of man 7 man, .EX/.EE are more suitable for paragraph
>> markup:
> ...
> Yes.  `EX`/`EE` works only with "displays".

May you elaborate about the meaning of "displays"?

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

In non-inclusive manner though. (cases when \fC works are not a subset
of cases where EX/EE works). Correct me if I am wrong.

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

Do I understand correctly that blank line is sometimes interpreted as
vertical spacing and sometimes ignored?

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

May black sometimes be different from the default color?

> 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

Thanks! This might be a good thing to add to our tests.

-- 
Ihor Radchenko // yantar92,
Org mode maintainer,
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>