From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id ECGfOc4jdGepVQAA62LTzQ:P1 (envelope-from ) for ; Tue, 31 Dec 2024 17:03:11 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id ECGfOc4jdGepVQAA62LTzQ (envelope-from ) for ; Tue, 31 Dec 2024 18:03:11 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b="AHqQdzZ/"; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1735664590; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=kZO8L8nFYB/NOdI1T3iScawdqVRrl4r8NfK8RZdehB0=; b=BN5Ujw8pkABNAiRKcS82bwZIEYUZxWVrcllBUuUfDWOp1lRINd7J4vxrj0lprnZqfZz5x9 7yUDOwoa8yfQg4uDF3SOqAPotJ5cS579bJqx5frDNGZy1ZKoZgAoi9iPZmKUVroZTAlz24 T40YhS0NIjqdvyHkYtDuzC1AuZSuZVyr/hL6eqF/XyiI53guuDisZeaomlpZIgKZdoxpim TjOo+094oEsDfDstayuy3R4jt6p8+TMXFOeQmPkfCH5U+y3RqaGSjTfkkUt2xlWJTQwFdf LWZYDofU7syw0t6P8IiDl7PooqzDmoX7xYY4TCIaJDCfkuvGu3TOlYjRTpjeRQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b="AHqQdzZ/"; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gmail.com ARC-Seal: i=1; s=key1; d=yhetil.org; t=1735664590; a=rsa-sha256; cv=none; b=YrjsMNLtCsO6PtUWmfHsb/96qGa6LcjOVaHQo7E9rQrqmVeCQcPt1LOMD42Xy5zozfSAqt ZZ602PZIj7iEti0amBjZ4/uJ8g6Hk0vcuK3GzwGmqaUNweuO+2OfJ7R87kwlXXhEasazbT KabAQCnPffaLO77uEtWRQq1SlpWZU6UHSv9gl8qWSMy8WMBwtYMxt3N7LgUMKn/Pk8fWYD VMgSq+GIxXgliWocfLKVOXl2uiduB3o3ODcWOtJ7O/4HkU54DYlHl/fHjml2M3CfsTXcBN WuN/kl5c0lB7Aea7l0W//b9QhtB38XtV9tK1wYZgdD0+kRN8zBDK1gJi8oOVGw== Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id C30918FBD7 for ; Tue, 31 Dec 2024 18:03:09 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tSfcw-0003KX-0j; Tue, 31 Dec 2024 12:01:54 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tSfbp-0002uX-N3; Tue, 31 Dec 2024 12:00:59 -0500 Received: from mail-oi1-x22b.google.com ([2607:f8b0:4864:20::22b]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tSfbm-00009C-NF; Tue, 31 Dec 2024 12:00:45 -0500 Received: by mail-oi1-x22b.google.com with SMTP id 5614622812f47-3eb8559b6b0so5604194b6e.1; Tue, 31 Dec 2024 09:00:39 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1735664438; x=1736269238; darn=gnu.org; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:from:to:cc:subject:date:message-id:reply-to; bh=kZO8L8nFYB/NOdI1T3iScawdqVRrl4r8NfK8RZdehB0=; b=AHqQdzZ/S2Aq0LG4nZ/AW1YvCtyeUbgJfvixd5sQD+46E8NsHJQZZoMi9D+xJd1hbU KAF9n+zbAksD1fiW8GTeJdDv2JANQOdWacSOiZJlwZkBTVJuPWi/3rbthtqj3R6Fq2hW 1qlEK9WbsYdhQWtOfClkUbBWiyVb4Gndw7feY6x/W6UIPc+pzfSA45ELLQL6BY6SsoB/ O5JyKMbOwPKpnzrP7Kxu2P4mYcKukvatxHBrUFWz+A/dvxc4Ogj1+AxwoNppar80EMtG TIe7yZIbX/ZMfJ68szSGpEnr1/HQEooOVqqrjMj/YxXapppHiEQAEbXPVyV1s7OGoWGQ OKtQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1735664438; x=1736269238; h=in-reply-to:content-disposition:mime-version:references:message-id :subject:cc:to:from:date:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=kZO8L8nFYB/NOdI1T3iScawdqVRrl4r8NfK8RZdehB0=; b=SS7QNngrH1gBm0kYZ78P/Eilfu9QpiHTFkBawFd/BGgAg1bo6VlK91Yl1KmJj2+a5H ArjvW4l9pdViThMY74Lt7PngRGxlMtQNxJKaP1mwzQ4wiO+1uVMRHzbBv79Cjb8AhxjI cyV1I/K35WxVRvcBfQKEdJ0AC2a0H91K1UPFJXSzPpop0Qmv91ADFAOIeYqGT0KIDpgE eJ0gdAYmxiLFMyzYe6wXOCQfS2QiBirvh4I0OMfXBwGJ0PsoRvhC8VN0WczcEqbqU1r5 EKvk8VW/T2X3JVsWtgfPZYZVZMvcrtBBiSqWeHfF6Iygxyw24CmHTFxr/0s97037lR1f KCJg== X-Forwarded-Encrypted: i=1; AJvYcCU5IXRXNZLt5Gr7n4F0ic/Yzecj7I0xKNhNbN+2v//XCykuQsIOs0M2AU7K78xsIuyx49YzXQ==@gnu.org X-Gm-Message-State: AOJu0YxTAqR7sLA3/02ttgJ9BovL4cfXZepJfTqMY4+CsG/i/Sil3QPj DP5qJmyANFWlICCrW4o1LzgjsTGuUXEuIDocbyCpW2zcC5vumanH X-Gm-Gg: ASbGncuXxa2fPM9zVwpzMfAjWHSzaK+fCBIL8FXGie1E/BoLXegnIvNCOCRZR/x7604 rxJZkR/GB8e5sgEQl5Uz8DJdl9YWKuWGzkzL8AW/Oevmnc4wNv8mtc0qMX+3Lin4VFJuSAKYsI+ +Cq1kb9egTi1CZD/C11Z9hdxor3Zl28NPycygmjaLT8TVJRfQtf2qeqKtpFJg+AFVHKi3drCXeM 1KPsZIuPr6O80TfOOY4VP4lN2HNSTPEys9gn32EZKGi+00= X-Google-Smtp-Source: AGHT+IGDYzlM50oH9DEdxSLOyzrzMAcxQNqU/RzYJ3Jy5jqlhsYOBlthVKgeqHfaGEm0vMyryrgFFw== X-Received: by 2002:a05:6808:1ded:b0:3eb:5d3a:5b20 with SMTP id 5614622812f47-3ed88ee5daemr20921418b6e.4.1735664438332; Tue, 31 Dec 2024 09:00:38 -0800 (PST) Received: from illithid ([2600:1700:957d:1d70::49]) by smtp.gmail.com with ESMTPSA id 5614622812f47-3ece2693da6sm6972797b6e.37.2024.12.31.09.00.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 31 Dec 2024 09:00:36 -0800 (PST) Date: Tue, 31 Dec 2024 11:00:34 -0600 From: "G. Branden Robinson" To: Ihor Radchenko Cc: emacs-orgmode@gnu.org, groff@gnu.org, Ingo Schwarze Subject: Re: [BUG] "\fC" macro in ox-man.el [9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)] Message-ID: <20241231170034.nzmponxxjppqrhf5@illithid> References: <20241218172040.tyytdhbyl7annyli@illithid> <87ttav7mii.fsf@localhost> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="gilto3eg7o5kqoee" Content-Disposition: inline In-Reply-To: <87ttav7mii.fsf@localhost> Received-SPF: pass client-ip=2607:f8b0:4864:20::22b; envelope-from=g.branden.robinson@gmail.com; helo=mail-oi1-x22b.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Scanner: mx11.migadu.com X-Migadu-Spam-Score: -10.86 X-Spam-Score: -10.86 X-Migadu-Queue-Id: C30918FBD7 X-TUID: TKTjhAtAET14 --gilto3eg7o5kqoee Content-Type: text/plain; protected-headers=v1; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Subject: Re: [BUG] "\fC" macro in ox-man.el [9.6.15 (release_9.6.15 @ /usr/share/emacs/29.2/lisp/org/)] MIME-Version: 1.0 [Ingo: see bottom of message for a possible mandoc(1) bug in footnote 2] Hi Ihor, At 2024-12-22T15:41:57+0000, Ihor Radchenko wrote: > "G. Branden Robinson" writes: >=20 > >> Jeremy suggests that "C" may be an old alias for Courier, and if > >> that's the case it should be changed to "\f[CR]". Would be great > >> if Org people can confirm. > > > > That is good advice and it is what I recommend if you're writing in > > "raw" roff. The context of the discussion is not ultra-clear to me; > > is ox-man.el a replacement for the old GNU Emacs man pager, "woman"? >=20 > Nope. ox-man is a converter between Org markup and Man page sources: >=20 > Given the following Org markup: >=20 > *This is test* > ~code a+b~ here a+b. >=20 > [*...* is bold markup. ~...~ is code markup.] >=20 > we aim to produce a valid man file that approximates the initial Org > markup as much as possible: >=20 > .TH "" "1"=20 > .PP > \fBThis is test\fP > \fCcode a+b\fP here a+b. 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). So I'll make some recommendations unfortunately without the benefit of having field-tested them. > 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; this was not thought to be a need when Brian Kernighan refactored the troff of Seventh Edition Unix for device-independence circa 1980. When James Clark wrote groff in about 1989, he tried to standardize font names across devices. But he also accommodated users of AT&T troff, providing aliases for many of the font names used by its dpost(1) output driver, and also didn't write all the diagnostic messages he could have, with the consequence that `\fC` sometimes worked, but also often silently failed, and few people noticed the difference. The last factor especially applies to users of terminals, where changing the font family in this manner is impossible anyway. `\f(CR` will work with groff, Heirloom Doctools troff, and neatroff. It won't work with mandoc(1) 1.14.6 (or earlier, I suspect), but then neither does `\fC`.[1][2] It won't work with Solaris 10 troff (and therefore Illumos troff) or Plan 9 from User Space troff. Given that, you might as well spell the escape sequence as `\f[CR]`, using GNU troff syntax for arbitrary-length escape sequence arguments. You can say either `\fP` or `\f[]` to restore the previous typeface. > Ok. But will it work inline? There is no portable way to achieve that across all known man(7) (or troff(1)) implementations. But if you care only about the formatters I mentioned as groff-compatible above, then `\f[CR]whatever\f[]` should work fine. > From my reading of man 7 man, .EX/.EE are more suitable for paragraph > markup: >=20 > .EX > .EE Begin and end example. After .EX, filling is disabled > and a constant-width (monospaced) font is selected. > Calling .EE enables filling and restores the previous > font. >=20 > These macros are extensions introduced in Ninth Edition > Research Unix. Systems running that troff, or those > from Documenter=E2=80=99s Workbench, Heirloom Doctools, or = Plan > 9 troff support them. To be certain your page will be > portable to systems that do not, copy their definitions > from the an-ext.tmac file of a groff installation. Yes. `EX`/`EE` works only with "displays". But it is worth noting that `EX`/`EE` is _more_ portable than `\fC`. > Ok. So much for testing via man->HTML exporter. > > What about PDF? groff's PDF support is pretty good. I use it all the time myself. Here's an exhibit of dogfooding: https://www.gnu.org/software/groff/manual/groff-man-pages.pdf In groff 1.24, that document will be about 75% smaller in file size (due to subsetting of embedded fonts), and will feature hyperlinks for all man page cross references, internally where applicable, and as "man:" URIs for external references. So. To my recommendations: Going by and ignoring indentation, I would change line 369 to: (format "\\f[CR]%s\\f[]" and line 438 to: (format "\\f[CR]\n%s\n\\f[]" and line 538 to: (format ".RS\n.EX\n\\m[black]%s\\m[]\n.EE\n.RE\n" and lines 543-544 to: (concat ".RS\n.EX\n" (org-man--protect-example code) "\n" ".EE\n.RE\n"))))) and line 758 to: (format ".RS\n.EX\n%s\n.EE\n.RE\n\n" (I would also delete that trailing "\n". Avoid blank lines in man(7) input.[3]) and line 782 to: (format ".RS\n.EX\n\\m[black]%s\\m[]\n.EE\n.RE" (org-man--protect-example c= ode)))))) and finally line 844 to: (format ".EX\n%s\n.EE" (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.) You can test a generated man(7) document by asking groff(1) and man(7) to lint it. $ groff -ww -rCHECKSTYLE=3D3 -man my-org-doc.man Please let me know if/how I can be of further assistance. Regards, Branden [1] If you "lint" your document, mandoc(1) will even tell you so. $ mandoc -T lint blah.man mandoc: blah.man:5:12: WARNING: invalid escape sequence: \fC [2] Actually, it looks like `\f(CR` (or `\f[CR]`) _should_ work with HTML output in mandoc(1). It brackets the word with a "span" element using the "Li" class (a reference to the mdoc(7) `Li` macro--mandoc(1)'s authors and maintainers are big-time mdoc(7) partisans). But, nothing in the `head` element bothers to define the `Li` class when formatting a man(7) document. This seems like a bug in mandoc(1) to me. mandoc(1) uses an external program to produce PDF from HTML, so inspecting its PDF output tells you nothing that its HTML output doesn't. [3] groff_man_style(7): =E2=80=A2 The empty request (.), which does nothing, vertically space= s the input file for readability by the document maintainer. Do not put blank (empty) lines in a man page source document. Some man(1) programs =E2=80=9Csqueeze=E2=80=9D multiple blank output lin= es into one. Regards, Branden --gilto3eg7o5kqoee Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAmd0IysACgkQ0Z6cfXEm bc7EwA/+I2rzLeBbTBpyjS8BrhjOOMqAAoqmkD5P7wlUzFwnXm7z/qIEWIfcovez zTScVwAz1SoPhwWFDpme2iWwUuif2Jb/Na4NNS+1LjftaeA8bdY7gLfUVbFGTaGe q3cPkaXAfbUFJRx0k1YY9gyvT65BYPQvooWiOoyt96T5kVGlJJ49ZmXGGOlCh+Js TgtIglPm+gAguXgc0+dHUzXLbKLW82sPkI4879NJqINNAPm78siOiIB8jV+L77i/ F9snjsvZpb3fCmY8pFffvGL2IFuU+ykabtcdvr8sBYaIHDe6uoQ4qQ8izHu1KjAv qvmnkCvKTXcJncwHR3KlxX6GuxYSn/juBhpq4hC+yWTixhFPQ0de4qNeta96vPMM tBbQcyYyo62AYJmT6CEuc6IBMMgDOUKa6eXR2VFYpv84S6qz6feK6zzdmz9h2WBY AANhpAssKMg7UC0PWarJmW6SPLhiOlZWENDeuFygbJBOjrABJFvo1vrjp5KZMUuf Puf7iuCHJZe7iXIpu5ilCKBLGoCHx9mX2cNNATORvpjiEC7iMwRdJeoaHiO4690z 9dO9CENyueoxhNOIssEA4IRLtScWbD4QpL56Pm2tUnkrwzQOyUlPqztQbRffQU3h p9CmMPK+5YvxjmziDtMTkmkZghaUCb0BMjzU5mCASY5H9+KJlKc= =b9Sd -----END PGP SIGNATURE----- --gilto3eg7o5kqoee--