"G. Branden Robinson" <g.branden.robin...@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>
