Re: [PATCH v4 1/1] man/man3/aligned_alloc.3: HISTORY: Document bogus specification from C11

[Alejandro Colomar <alx@kernel.org>]

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

Hi Branden,

On Mon, Dec 22, 2025 at 06:15:24PM -0600, G. Branden Robinson wrote:
> Hi Alex,
> 
> Content looks great; as you've likely guessed, I have commentary only on
> man(7) markup.
> 
> At 2025-12-22T22:33:09+0100, Alejandro Colomar wrote:
> > I've rewritten the entire subsection from scratch, similar to the
> > email I wrote detailing the history of the specification.  I think
> > this is explains the turbulent history of this API better, and allows
> > programmers to decide if they want to trust this API or not.
> > 
> > Does this look good?
> 
> At 2025-12-22T22:33:13+0100, Alejandro Colomar wrote:
> > Document the turbulent past of aligned_alloc(), and how libraries have
> > actually implemented it.
> 
> Nice summary!

Thanks! :-)

> [...]
> > +the specification of this function had
> > +.UR https://port70.net/~nsz/c/c11/n1570.html#7.22.3.1p2
> > +several issues
> > +.UE .
> [...]
> > +.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/summary.htm#dr_460
> > +DR460
> > +.UE
> [...]
> > +.UR https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2072.htm
> > +N2072
> > +.UE
> 
> I'd put hyphenless break points after each sequence of slashes in these
> URLs, and before each dot.
> 
> I`d spell these `-`s as `\-` so that they appear as hyphen-minuses when
> printed, not as hyphens.

Yup; thanks for the reminder!  Also fixed the \[ti].


Have a lovely night!
Alex

> 
> groff_man_style(7):
>    Hyperlink macros
> ...
>      Prepare arguments to MR, MT, and UR for typesetting; they can
>      appear in the output.  Use special character escape sequences to
>      encode Unicode basic Latin characters where necessary, particularly
>      the hyphen‐minus.  (See subsection “Portability” below.)  URIs can
>      be lengthy; rendering them can result in jarring adjustment or
>      variations in line length, or troff warnings when one is longer
>      than an output line.  The application of non‐printing break point
>      escape sequences \: after each slash (or series thereof), and
>      before each dot (or series thereof) is recommended as a rule of
>      thumb.  The former practice avoids forcing a trailing slash in a
>      URI onto a separate output line, and the latter helps the reader to
>      avoid mistakenly interpreting a dot at the end of a line as a
>      period (or multiple dots as an ellipsis).  Thus,
>             .UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
>      has several potential break points in the URI shown.  Consider
>      adding break points before or after at signs in email addresses,
>      and question marks, ampersands, and number signs in HTTP(S) URIs.
> ...
> Portability
> ...
>      \-     Minus sign.  \- produces the basic Latin hyphen‐minus
>             (U+002D) specifying Unix command‐line options and frequently
>             used in file names.  “-” is a hyphen in roff; some output
>             devices format it as U+2010 (hyphen).
> 
> I recently noticed someone on StackExchange opining that "man" (they
> weren't clear on whether they meant the man(1) librarian or the man(7)
> macro language) doesn't support URLS: "unlike man, at least [lynx(1)]
> supports links!".
> 
> That claim is a combination of falsehood, misleading implication, and
> out-of-dateness.  It's not man(1) that needs to support hyperlinks in a
> terminal, but the pager[1], and less(1) does, since version 661 (June
> 2024).  grotty(1) has offered OSC 8 links since groff 1.23.0, July 2023.
> 
> Regards,
> Branden
> 
> [1] ...or the terminal emulator, in the event one uses cat(1) as the
>     pager or runs "nroff -man" directly, like a hard-bitten,
>     two-fisted-drinking, shirtless veteran of the Unix Wars.
> 
>     (You can leave Australia, but 'Straya never truly leaves you.)



-- 
<https://www.alejandro-colomar.es>

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