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