Hi guys, I recently stumbled across this commit:
commit db0faabe1d63abc710c2997077fec467b783fa13 Author: Pádraig Brady <[email protected]> Date: Fri May 1 18:48:39 2026 +0100 doc: reference detailed "numeric mode" info from chmod.1 Note were links are not supported (like on Solaris or FreeBSD), the text still displays normally. * man/chmod.x: Link from "numeric mode" in chmod man page, to more detailed online info. diff --git a/man/chmod.x b/man/chmod.x index 39749f0bf..4a20c5b43 100644 --- a/man/chmod.x +++ b/man/chmod.x @@ -49,7 +49,9 @@ users who are members of the file's group (\fBg\fP), and the permissions granted to users that are in neither of the two preceding categories (\fBo\fP). .PP -A numeric mode is from one to four octal digits (0\-7), derived by +.ds cU https://www.gnu.org/software/coreutils/manual/html_node +A \X'tty: link \*(cU/Numeric-Modes.html'\fBnumeric mode\fP\X'tty: link' +is from one to four octal digits (0\-7), derived by adding up the bits with values 4, 2, and 1. Omitted digits are assumed to be leading zeros. The first digit selects the set user ID (4) and set group ID (2) and ... Holy cow! I of course appreciate usage of the support for OSC 8 hyperlinks that I slaved over to get into grotty(1) for groff 1.23 (July 2023), but this is an unnecessarily hard-core way to achieve what you're doing, and moreover deprives users of groff's HTML and PDF output from enjoying the convenience of the hyperlink. May I propose the following alternative? A .UR https://\:www\:.gnu\:.org/\:software/\:coreutils/\:manual/\ \:html_node/\:Numeric\-Modes\:.html .B "numeric mode" .UE is from one to four octal digits (0\-7), derived by Advantages: 1. More portable. A non-GNU roff, or alternative formatter like mandoc(1), or one of the many man2html(1) programs of the world, will not get confused by the \X escape sequences and risk losing track of the text "numeric mode" on the line. Specifically, Plan 9 from User Space and Heirloom Doctools troffs do fine with it, but DWB 3.3 and Solaris 10 troffs (which is available for non-Solaris machines) do not, producing this instead: $ solaris10 nroff -man /tmp/brain.man | ul | cat -s User Commands foo(1) Name foo - bar Description Baz. A tlhumeric modetlis from one to four octal digits (0-7), derived by adding up the bits with values 4, 2, and 1. Omitted digits are assumed to be leading zeros. groff test suite Last change: 2026-05-29 1 2. With groff, you get a hyperlink in the HTML and PDF output formats as well. 3. If the output device is incapable of hyperlinking, the URL is formatted as text so that the user can at least copy-and-paste their way to the linked resource. $ nroff -r LL=72n -rU=0 -m an /tmp/salad.man foo(1) General Commands Manual foo(1) Name foo - bar Description Baz. A numeric mode ⟨https://www.gnu.org/software/coreutils/manual/ html_node/Numeric-Modes.html⟩ is from one to four octal digits (0-7), derived by adding up the bits with values 4, 2, and 1. Omitted digits are assumed to be leading zeros. groff test suite 2026‐05‐29 foo(1) To facilitate this graceful fallback, I added formatting hints to the hyperlink, taking care to specify hyphenless break points and to ensure that the correct glyph (U+002D) renders for the hyphen in the URL. 4. groff's `UR`/`UE` and `MT`/`ME` macros are designed to permit graceful degradation of output on implementations that don't implement them. *roff formatters silently ignore calls of undefined macros.[1] So, with my proposed approach, you get this on a conservative old troff like Solaris 10's. $ solaris10 nroff -man /tmp/salad.man | ul | cat -s User Commands foo(1) Name foo - bar Description Baz. A numeric mode is from one to four octal digits (0-7), derived by adding up the bits with values 4, 2, and 1. Omitted digits are assumed to be leading zeros. groff test suite Last change: 2026-05-29 1 The URL is missing, but the text is unmolested. What do you think? Regards, Branden [1] If I were Hermes Conrad, I'd say that these formatters create an empty macro of the given name and then interpolate it. An empty macro does nothing.
signature.asc
Description: PGP signature
