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

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

Hi Ihor,

At 2024-12-31T18:15:57+0000, Ihor Radchenko wrote:
> "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.

D'oh!  Thanks.

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

Thank you very much.  I'll test out my proposed changes locally.

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

As noted in the other subthread, that is the case.  Terminal emulators
generally don't support rendering fonts from multiple families
simultaneously.  (3) is an unreachable goal with present terminal
emulator technology and for the foreseeable future.

> > Yes.  `EX`/`EE` works only with "displays".
> 
> May you elaborate about the meaning of "displays"?

Sure.

https://www.gnu.org/software/groff/manual/groff.html.node/Displays-and-Keeps.html

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

It's an incomplete overlap, yes.  But it's easier to get `EX`/`EE`
support on systems that lack support for a font `C` than vice versa.

A document can define its own `EX` and `EE` macros if necessary.  We
have portable and permissively licensed implementations that we
encourage anyone to use.

https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/an-ext.tmac?h=1.23.0

So ox-man.el might add the macro definitions in lines 162-172 and
178-186 to the preamble of the generated document (that is, immediately
after the `TH` call) to be _sure_ `EX` and `EE` will be available.

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

Yes.  A blank line is ignored when the formatter's "no-space mode" is
enabled.

https://www.gnu.org/software/groff/manual/groff.html.node/Manipulating-Spacing.html#index-mode_002c-no_002dspace-_0028ns_0029

That's mainly for information.  Generally we discourage the use of *roff
requests in man(7) documents.  As groff_man_style(7) says:

   Portability
[...]
     The two major features that control formatting in the roff language
     are requests and escape sequences.  Since the man macros are
     implemented in terms of these, one can, in principle, supplement
     the functionality of man with these lower‐level elements where
     necessary.

     However, use of roff requests (apart from the empty request “.”)
     risks poor rendering when your page is processed by non‐roff
     formatters that attempt to interpret page sources.  (Historically,
     this was commonly attempted for HTML conversion.)  Requests may
     make assumptions that do not hold in an HTML environment.  Many of
     these programs don’t interpret the full roff language (let alone
     extensions): they may be incapable of handling numeric expressions,
     control structures, or register, string, and macro definitions.
     Such limitations can lead to portions of a document being presented
     incomprehensibly or omitted altogether.

     The wise man author quotes multi‐word section and subsection
     headings; the .SH and .SS macros of man(7) implementations
     descended from Seventh Edition Unix supported six arguments at
     most.  This restriction also applied to the .B, .I, .SM, and font
     style alternation macros.

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

Yes, but it's impossible to know what the default color is; there is
interface for GNU troff to obtain this information from the output
device (and even if there were, due to device-independent troff's
multi-stage architecture, which groff also uses, there is no way[1] to
use that information to make decisions in the *roff(1) language altering
the document's formatting in response to it.

Also, explicitly selecting `\m[black]` as you are is going to backfire
on terminals using a black background--the text will become invisible!

(If you/your users haven't seen that often, or ever, it's likely because
some environments, including man(1) programs, if aware of groff, arrange
to disable the output of SGR escape sequences from groff's output driver
for terminals, grotty(1).  So the good news is, on those systems, the
problem I just described won't happen.  The bad news is, _all_ of the
`\m` and `\M` escape sequences you produce will be completely ignored.)

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

I forgot to mention the `-z` option.  You'll want that, too.  That will
suppress ordinary output so you get nothing _but_ diagnostic messages.

Regards,
Branden

[1] No _straightforward_ way.  In light of recent discussions I've had
    with Deri James, I'd be remiss if I didn't mention device extension
    commands.  But using these to get the formatter's idea of the stroke
    color deliberately out of sync with the output device's does _not_
    seem like a promising line of development to me.

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