Hi Branden, On 2023-09-13 19:49, G. Branden Robinson wrote: > Hi Alex, > > At 2023-09-13T17:24:53+0200, Alejandro Colomar wrote: >>> diff --git a/man2/ioctl.2 b/man2/ioctl.2 >>> index 6b55d47c9..a658da354 100644 >>> --- a/man2/ioctl.2 >>> +++ b/man2/ioctl.2 >>> @@ -20,9 +20,8 @@ .SH SYNOPSIS >>> .nf >>> .B #include <sys/ioctl.h> >>> .PP >>> -.BI "int ioctl(int " fd ", unsigned long " request ", ...);" >>> -.\" POSIX says 'request' is int, but glibc has the above >>> -.\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705 >>> +.BI "int ioctl(int " fd ", unsigned long " request ", ...);" "\fR /* glibc, BSD */\fP" >>> +.BI "int ioctl(int " fd ", int " request ", ...);" "\fR /* musl, other UNIX */\fP" >> >> LGTM. > [...] >> [while applying, changed to use the \f[...] form.] > > It's a shame the ellipsis is in italics. This will underline it on > terminals when the user hasn't gone out of their way to exercise the > italic attribute.[1] It's in bold. :| > Also, it is idiomatic to write ellipses with `\|` > escape sequences internally separating the dots; this looks better on > typesetters. (It wouldn't matter when a monospaced font is used, but > the Linux man-pages don't do that for synopses.) We could do that. If you want to prepare a global patch for that :) > > Perhaps consider... > > +.BI "int ioctl(int " fd ", unsigned long " request ", \f[R].\|.\|.\f[]);" "\f[R] /* glibc, BSD */\f[]" > +.BI "int ioctl(int " fd ", int " request ", \f[R].\|.\|.\f[]);" "\f[R] /* musl, other UNIX */\f[]" > > What do you think? Not for this patch, but a global one after this one, yeah, could be. > > At 2023-09-13T18:44:53+0200, Alejandro Colomar wrote: >> On 2023-09-13 18:02, наб wrote: >>> Bit me in https://github.com/thecoshman/http/issues/155: >> >> Be careful with URIs. They _must_ be enclosed within <>. See uri(7). >> Otherwise, the ':' can be understood as part of the URI. > > groff's `UR`/`UE` macros have been available since 2009 for this > purpose. mandoc(1) supports them, as does Heirloom Doctools troff (the > latter because it incorporates an old but usable copy of an-ext.tmac). > With man.7 now (in Git) sourcing groff_man.7, I expect the quantity of > submissions using `UR` and `UE` to increase. > > Also, I thought наб was just mentioning the URL in the email, not adding > it to the man(7) document per se. Yep, it was in the commit message, and that's why it should be properly written (and even if it was only an email, not in the commit message, it would be nice to write proper URIs). For example, when I tried to open it, it opened the page ending in ':'. Cheers, Alex > > But for grins, if one wanted наб's exact words in a man page, despite > their informal register, here's what you'd do. > > Bit me in > .UR https://github.com/thecoshman/http/issues/155 > .UE : > > Regards, > Branden > > [1] In groff 1.24, they may no longer have to go out of their way, but > might get italics automatically. > > https://lists.gnu.org/archive/html/groff/2023-09/msg00027.html > > (I still owe Lennart a review of v3.) -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature.asc
Description: OpenPGP digital signature
