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 WO+fLPuIdmeTUgAA62LTzQ:P1 (envelope-from ) for ; Thu, 02 Jan 2025 12:39:23 +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 WO+fLPuIdmeTUgAA62LTzQ (envelope-from ) for ; Thu, 02 Jan 2025 13:39:23 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=Z0ZvtbAg; 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=1735821563; 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=KNshBE3do9/QKMIJl+fCm5xnCt8Zie2kEDCootl928U=; b=AvnDnO4lTabgeyC1IHJFUyMnyshzcjrhsAmOsb2HZSqfwSHZNZeI3Bchdi72O3EDygHoqO l3ujRzSMYa5ASaAlTwEmZmF7t+cZkd6JaWtLNTuZr6p+2aSRim38KdAOYkPVX812Mj1xy7 wHoibjFiRIM/id/xSfXRArIYhJ0Q90yloo+qiZSSOWQEtQKzj8qLCYRkc60Zmy2gu0IAB4 WwmJWZSbp/XspsBLh/zRTxk3qDuljRMJC8jT7MifIsxshW9Zxvs+md1OT1XQMv4gChzG50 eFGBfHsLOU4OiiUbtjjgwKQOkjoYZWK9QYD+Tola/KEhD7sdTsdPvNjmHZEMDA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b=Z0ZvtbAg; 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=1735821563; a=rsa-sha256; cv=none; b=Y6KXkXpSm554Ln0fLSJymmq2q7Az+ARb1EWuibkiQmYjDY8/Me4yCnSoIlb80KwDeuUAsc jtV/F3MgtOHhe8wNPYoQ9SCFgIdQsviXKfZX+IAXWeY/DSpQZChxThZHQUIyZ3+2CVoION CftrY4QGqDeYb0fAjugYtrx4q9xJLU9hV7EVAU3imODvvxoOjvjp2bDhFT8DMOPuDX7IWH K5Kx9cxXQivNvq9t8O5SDjLcCwJ10YZG+eLB1xVVqnimbu0znyCH19dvhEV28l/vBWXOn3 ouJOHJ4Vy5yfjWnLj7AxqJncRuS8Ge1m++VQTqMZ9+W/mvZjQqZ0eKd5jC+ZsA== 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 2E17E7FA0B for ; Thu, 02 Jan 2025 13:39:23 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tTKTI-00041P-Jf; Thu, 02 Jan 2025 07:38:40 -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 1tTKTB-000417-LV; Thu, 02 Jan 2025 07:38:33 -0500 Received: from mail-ot1-x32d.google.com ([2607:f8b0:4864:20::32d]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tTKT9-0006ML-8i; Thu, 02 Jan 2025 07:38:33 -0500 Received: by mail-ot1-x32d.google.com with SMTP id 46e09a7af769-71e173ed85bso5160724a34.3; Thu, 02 Jan 2025 04:38:30 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1735821509; x=1736426309; 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=KNshBE3do9/QKMIJl+fCm5xnCt8Zie2kEDCootl928U=; b=Z0ZvtbAgOWVoFNPImmzB3ctd0FZeahX+TuYCBtpopT87DNwbC93llZbtzMIGhsYbVL xS1lh99MOdUqInvamnvFJbNgTLYQNdr0au/uqWXMfuxKDJEpXxbA+4f79p7XV84TRNhz 9eaotQgj1vdQMfRmqHpWcCytmqYyTQ7ztFrGHNhiDgdr9Rj5RGL8t/cdXuIKANWmvSxg BxSkZWjMlfmTLa5AlOrLJz8fhCWerX59I7WPznXSwWpESidDXUk13WH5Pv6cLNMDLJT7 5STUPGcAV2Djs+hYBNiTtwLTaVheRcBvWLhk5ss4o1hlYeWLj9XJvng5zZ5MxdXY+lTv D2Pw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1735821509; x=1736426309; 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=KNshBE3do9/QKMIJl+fCm5xnCt8Zie2kEDCootl928U=; b=WCqOEvGxA4mk1PALROoHF7r8smsDyhic64ktLcUjoeibhPOC+9vQTwA29xj+kbPQou VhUdaGmztcRSAdtU9EV/norO7eCNtpHx1Woc53Nq21KG2x/+3YL2P6+3H8A6YXOYYvna gbkRR/M7tK3hiF3mslIF24K0eVEd7xvF33vE/46/sgCrLp95kGIK9DxgFkwheQf9sWS+ MLy1Sv3gF9alA1H1ATC4qhgZXchkcochmwyK5b7QAKkTSrcWUB8+ZbTSnJYmTwGMenGY PSMWjGY6ltwuZkNwhaIkOQqYBTDBhleqIc9VTGaTCpw0U9tKbCx/92Y30tqN8vJg9O1c NyrA== X-Forwarded-Encrypted: i=1; AJvYcCXQdyhfBlkw3Cf0MDwPj3h8R8G49moLa4cq9gWKsXhU6Lo6YbI9clZ0c/FwcvwKXccvpXNmkA==@gnu.org X-Gm-Message-State: AOJu0YzSL8oltgn2rOAuf856ObVtIr57ZUoWAmDWKTji9xYG2hWU2MpK AuLn3Ok8fsz4DP7ICm5vLWvN0NdpTZAWaamyE55jO3Ls9mIKAqObBPH5Iw== X-Gm-Gg: ASbGncs8qwdjIIk4Db4gL0VHltsaF21TE9shYKnjvTjaks+NmaDeocwRT3rgV//yrcd +uzzvcjKBc+7b76UmLucX18AYTbKtj7ngIwpt5Fu+00Fz7VRym0yo+bc2GGER3D+zEDlk49AZSu WQtzUjXCOnNorqNsF8x/zRCjv2lUuEtYVlsRcWPVCexoXyt1gpnEUpOTqMZw00rVkSnJnCSH9n9 CO7cWJsQIRQXNonsI3V3hTMojq1qz/rLO/Xz1w43UtslLs= X-Google-Smtp-Source: AGHT+IGIgZkjvKviXK4uzKon+Ii9uPL0UxxaOCPc+6JW3NtCmeJ8aPBS71ESvn0p5dWnW38QvdFbNg== X-Received: by 2002:a05:6830:f8e:b0:717:fe7d:a19e with SMTP id 46e09a7af769-720ff6da125mr27932862a34.11.1735821509276; Thu, 02 Jan 2025 04:38:29 -0800 (PST) Received: from illithid ([2600:1700:957d:1d70::49]) by smtp.gmail.com with ESMTPSA id 006d021491bc7-5f4db618700sm7191234eaf.23.2025.01.02.04.38.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 02 Jan 2025 04:38:27 -0800 (PST) Date: Thu, 2 Jan 2025 06:38:25 -0600 From: "G. Branden Robinson" To: Ihor Radchenko Cc: emacs-orgmode@gnu.org, groff@gnu.org 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: <20250102123825.vfoj7dcjhjawdhaq@illithid> References: <20241218172040.tyytdhbyl7annyli@illithid> <87ttav7mii.fsf@localhost> <20241231170034.nzmponxxjppqrhf5@illithid> <87bjwrhg6a.fsf@localhost> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="ngfugdyhaxunu4bl" Content-Disposition: inline In-Reply-To: <87bjwrhg6a.fsf@localhost> Received-SPF: pass client-ip=2607:f8b0:4864:20::32d; envelope-from=g.branden.robinson@gmail.com; helo=mail-ot1-x32d.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: -11.06 X-Spam-Score: -11.06 X-Migadu-Queue-Id: 2E17E7FA0B X-TUID: QZFRfcRvQz8Y --ngfugdyhaxunu4bl 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 Hi Ihor, At 2024-12-31T18:15:57+0000, Ihor Radchenko wrote: > "G. Branden Robinson" writes: >=20 > > 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). >=20 > 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). >=20 > > So I'll make some recommendations unfortunately without the benefit > > of having field-tested them. >=20 > You can do the following to try exporting to man from Emacs 29.4: >=20 > 1. emacs -Q > 2. M-: (require 'ox-man) RET > 3. Open a sample .org file > 4. C-c C-e M m >=20 > (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 >=20 > 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". >=20 > May you elaborate about the meaning of "displays"? Sure. https://www.gnu.org/software/groff/manual/groff.html.node/Displays-and-Keep= s.html > > But it is worth noting that `EX`/`EE` is _more_ portable than `\fC`. >=20 > 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=3D1.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]) >=20 > 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-Spac= ing.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=E2=80=90level elements where necessary. However, use of roff requests (apart from the empty request =E2=80=9C.= =E2=80=9D) risks poor rendering when your page is processed by non=E2=80=90roff 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=E2=80=99t interpret the full roff language (let alo= ne 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=E2=80=90word 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.) >=20 > 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=3D3 -man my-org-doc.man >=20 > 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. --ngfugdyhaxunu4bl Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCAAdFiEEh3PWHWjjDgcrENwa0Z6cfXEmbc4FAmd2iLoACgkQ0Z6cfXEm bc78lQ//XJMOXl8V24yqtJHM/cFf7LzcYw9sO3gW+Vn4v9WpujpdpxT6eWUKC65H uy3nhlcJvT8tjcLwD6iCT2yS3c7LeBWCNq0aGOWeKUUs2ZoaYJ7yd0MBFOoGn8aM r9MgE3cEfSoI64iIO3dTVHlB698C6e9FpmWk0rtwhCOTJ6hVxBKMTGIGhNzvf6+H 7b14Nx1GotVDz3zcNByZVKutywEBF9RMvAUxCt0I8wl9NmJsDR2pMkccw5IIX+YR WXyuPhAlZPT1xz5d7TLtLhPSrAQxpxGpO+YbuVvO92mIaMD5n1lKI6oabVWiv2yz g6TeHFp31zLxBpOW/jT94Q9HclmJIX+DDQDE+K52UDevZs5b9jYwlmUT/GltBgsK OYfagpCroDviHzxOnHTXt128en31j3DCOWto78pJdnQhjOlDLT1V8x+Mk3sV8cCI oLR5lAGePOeWJXSjKay6zA9UwpH2cVFiTIbQv0gHngf+yGXnutxXIZQckSvywv8f yrDD4O3wYp6UA4oWfGAcyQ5EH08s4ZUO6x0hptWiD2esjKSvV7QCTGuXh0kY/sGq SXq1ncnKMyTRMjDMEeYXPiIxU64Fe42FDz1jn+xy4+7hUzKoI08HUBT7FfwaKi2g FADpZZdtFUN83yze6DrgvCFHx8tfDDyw+birsC6mmXV+/L780o0= =uA82 -----END PGP SIGNATURE----- --ngfugdyhaxunu4bl--