Re: [BUG] bug in 'ox-man?

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

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

[please CC me in replies; I am not subscribed to emacs-orgmode]

At 2024-04-14T11:20:28+0000, Ihor Radchenko wrote:

>From ef3fa244d1a32c2cce3616a6dffc9c3dcafd4e34 Mon Sep 17 00:00:00 2001
Message-ID: <ef3fa244d1a32c2cce3616a6dffc9c3dcafd4e34.1713093571.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Sun, 14 Apr 2024 14:05:59 +0300
Subject: [PATCH] ox-man: Escape backslash characters in verbatim examples

* lisp/ox-man.el (org-man--protect-example): New helper function
protecting special escape characters inside literal examples.
(org-man-example-block):
(org-man-inline-src-block):
(org-man-src-block):
(org-man-table): Protect contents that is intended to be rendered
verbatim.

Reported-by: Greg Minshall <minshall@umich.edu>
Link: https://orgmode.org/list/2924644.1643637646@apollo2.minshall.org
---
 lisp/ox-man.el | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

[snip]
      ;; Do not use a special package: transcode it verbatim.
      (t
-      (concat ".RS\n.nf\n" "\\fC" "\n" code "\n"
+      (concat ".RS\n.nf\n" "\\fC" "\n" (org-man--protect-example code) "\n"
               "\\fP\n.fi\n.RE\n")))))

I suggest something like:

-      (concat ".RS\n.nf\n" "\\fC" "\n" code "\n"
-              "\\fP\n.fi\n.RE\n")))))
+      (concat ".RS\n.nf\n" ".EX\n" ".P\n" (org-man--protect-example code) ".P\n"
+              ".EE\n.fi\n.RE\n")))))

I replaced inlined `\fC` and `\fP` escape sequences with `EX` and `EE`
macro calls, respectively.

I also think I perceive the use of empty lines as paragraph separators.
These look bad when typesetting (as opposed to terminal rendering).  So
I changed them to be `P` paragraphing macro calls instead.

Also, the `nf` request is redundant with the `EX` macro call and `fi`
with `EE`; I left them in because they are harmless and positively
useful if you're producing a man page for consumption by a non-groff
troff that doesn't support the `EX` and `EE` macros.  (mandoc(1)
correctly renders `EX` and `EE`.)

groff_man(7):
            .EX and .EE are extensions introduced in Ninth Edition Unix.
            Documenter’s Workbench, Heirloom Doctools, and Plan 9
            troffs, and mandoc (since 1.12.2) also support them.
            Solaris troff does not.  See subsection “Use of extensions”
            below.

Unless support for Solaris 10 troff is important to you (Solaris 11 uses
groff), `nf` and `fi` are unnecessary and you can take them out too.

Regards,
Branden

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