* [PATCH] ioctl.2: note "int request" form, HISTORYise a bit @ 2023-09-04 14:29 наб 2023-09-04 15:41 ` Jakub Wilk 2023-09-13 15:24 ` Alejandro Colomar 0 siblings, 2 replies; 8+ messages in thread From: наб @ 2023-09-04 14:29 UTC (permalink / raw) To: Alejandro Colomar (man-pages); +Cc: linux-man [-- Attachment #1: Type: text/plain, Size: 2540 bytes --] Bit me in https://github.com/thecoshman/http/issues/155: musl (and, thus, bionic) takes an int! Kill the "POSIX says 'request' is int" comment, POSIX says nothing about ioctl: it invented tc[gs]etattr() and tc[gs]etwinsize() to avoid having ioctl() at all, and STREAMS is long dead from POSIX. Note how the interface evolved in HISTORY. The NetBSD CVS has revision 1.1 date: 1993-03-21 10:45:37 +0100; author: cgd; state: Exp; branches: 1.1.1; Initial revision ---------------------------- revision 1.1.1.2 date: 1995-02-27 11:49:43 +0100; author: cgd; state: Exp; lines: +6 -6; from Lite ---------------------------- revision 1.1.1.1 date: 1993-03-21 10:45:37 +0100; author: cgd; state: Exp; lines: +0 -0; initial import of 386bsd-0.1 sources ---------------------------- and it's char * in 1.1.1.1 and 1.1.1.2 but ... in 1.1, so hell knows. Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> --- man2/ioctl.2 | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) 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" .fi .SH DESCRIPTION The @@ -103,7 +102,40 @@ .SH VERSIONS .SH STANDARDS None. .SH HISTORY -Version\~7 AT&T UNIX. +Version\~7 AT&T UNIX has +.nf +.ti +.5i +.BI "ioctl(int " fildes ", int " request ", struct sgttyb *" argp ); +.fi +(where +.B struct sgttyb +has historically been used by +.BR stty (2) +and +.BR gtty(2), +and is polymorphic by request type (like a +.B void * +would be, if it had been available)). +.PP +SysIII documents +.I arg +without a type at all. +.PP +4.3BSD has +.nf +.ti +.5i +.BI "ioctl(int " d ", unsigned long " request ", char *" argp ); +.fi +(with +.B char * +similarly in for +.BR "void *" ). +.PP +SysVr4 has +.nf +.ti +.5i +.BI "int ioctl(int " fildes ", int " request ", ... /* " arg " */);" +.fi .SH NOTES In order to use this call, one needs an open file descriptor. Often the -- 2.39.2 [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit 2023-09-04 14:29 [PATCH] ioctl.2: note "int request" form, HISTORYise a bit наб @ 2023-09-04 15:41 ` Jakub Wilk 2023-09-04 15:58 ` наб 2023-09-13 15:24 ` Alejandro Colomar 1 sibling, 1 reply; 8+ messages in thread From: Jakub Wilk @ 2023-09-04 15:41 UTC (permalink / raw) To: наб; +Cc: Alejandro Colomar, linux-man * наб <nabijaczleweli@nabijaczleweli.xyz>, 2023-09-04 16:29: >POSIX says nothing about ioctl: Yes it does say _something_: https://pubs.opengroup.org/onlinepubs/9699919799/functions/ioctl.html >STREAMS is long dead from POSIX. What do you mean? -- Jakub Wilk ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit 2023-09-04 15:41 ` Jakub Wilk @ 2023-09-04 15:58 ` наб 0 siblings, 0 replies; 8+ messages in thread From: наб @ 2023-09-04 15:58 UTC (permalink / raw) To: Jakub Wilk; +Cc: Alejandro Colomar, linux-man [-- Attachment #1: Type: text/plain, Size: 670 bytes --] On Mon, Sep 04, 2023 at 05:41:50PM +0200, Jakub Wilk wrote: > * наб <nabijaczleweli@nabijaczleweli.xyz>, 2023-09-04 16:29: > > POSIX says nothing about ioctl: > Yes it does say _something_: > https://pubs.opengroup.org/onlinepubs/9699919799/functions/ioctl.html Shaded OB XSR (obsolescent, STREAMS), FUTURE DIREXIONS say "we're removing this next release" (effectively). Linux doesn't have STREAMS, so this doesn't apply, and even if it did, > > STREAMS is long dead from POSIX. > What do you mean? It's obsolescent in issue 7 and completely gone from issue 8, and ioctl() is completely gone with it: STANDARDS None. is correct. Best, [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit 2023-09-04 14:29 [PATCH] ioctl.2: note "int request" form, HISTORYise a bit наб 2023-09-04 15:41 ` Jakub Wilk @ 2023-09-13 15:24 ` Alejandro Colomar 2023-09-13 16:02 ` наб 1 sibling, 1 reply; 8+ messages in thread From: Alejandro Colomar @ 2023-09-13 15:24 UTC (permalink / raw) To: наб; +Cc: linux-man, G. Branden Robinson, Jakub Wilk [-- Attachment #1.1: Type: text/plain, Size: 3300 bytes --] Hi наб, On 2023-09-04 16:29, наб wrote: > Bit me in https://github.com/thecoshman/http/issues/155: > musl (and, thus, bionic) takes an int! > > Kill the "POSIX says 'request' is int" comment, > POSIX says nothing about ioctl: Please reword that; while it will say nothing soon, the current standard is Issue 7, which still says. Something like your reply to Jakub should be enough. > it invented tc[gs]etattr() and tc[gs]etwinsize() to avoid having > ioctl() at all, and STREAMS is long dead from POSIX. > > Note how the interface evolved in HISTORY. The NetBSD CVS has > revision 1.1 > date: 1993-03-21 10:45:37 +0100; author: cgd; state: Exp; > branches: 1.1.1; > Initial revision > ---------------------------- > revision 1.1.1.2 > date: 1995-02-27 11:49:43 +0100; author: cgd; state: Exp; lines: +6 > -6; > from Lite > ---------------------------- > revision 1.1.1.1 > date: 1993-03-21 10:45:37 +0100; author: cgd; state: Exp; lines: +0 > -0; > initial import of 386bsd-0.1 sources > ---------------------------- > and it's char * in 1.1.1.1 and 1.1.1.2 but ... in 1.1, so hell knows. > > Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> > --- > man2/ioctl.2 | 40 ++++++++++++++++++++++++++++++++++++---- > 1 file changed, 36 insertions(+), 4 deletions(-) > > 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. > .fi > .SH DESCRIPTION > The > @@ -103,7 +102,40 @@ .SH VERSIONS > .SH STANDARDS > None. > .SH HISTORY > -Version\~7 AT&T UNIX. > +Version\~7 AT&T UNIX has > +.nf > +.ti +.5i I prefer using man(7) macros. Please use .PP .in +4n .nf stuff here .fi .in .PP If you want to prevent the blanks that this adds, you can enclose that in .PD 0 / .PD (.in is not a man(7) macro, but it is already widespread.) Cheers, Alex > +.BI "ioctl(int " fildes ", int " request ", struct sgttyb *" argp ); > +.fi > +(where > +.B struct sgttyb > +has historically been used by > +.BR stty (2) > +and > +.BR gtty(2), > +and is polymorphic by request type (like a > +.B void * > +would be, if it had been available)). > +.PP > +SysIII documents > +.I arg > +without a type at all. > +.PP > +4.3BSD has > +.nf > +.ti +.5i > +.BI "ioctl(int " d ", unsigned long " request ", char *" argp ); > +.fi > +(with > +.B char * > +similarly in for > +.BR "void *" ). > +.PP > +SysVr4 has > +.nf > +.ti +.5i > +.BI "int ioctl(int " fildes ", int " request ", ... /* " arg " */);" > +.fi > .SH NOTES > In order to use this call, one needs an open file descriptor. > Often the -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5 [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH] ioctl.2: note "int request" form, HISTORYise a bit 2023-09-13 15:24 ` Alejandro Colomar @ 2023-09-13 16:02 ` наб 2023-09-13 16:44 ` Alejandro Colomar 0 siblings, 1 reply; 8+ messages in thread From: наб @ 2023-09-13 16:02 UTC (permalink / raw) To: Alejandro Colomar; +Cc: linux-man, G. Branden Robinson, Jakub Wilk [-- Attachment #1: Type: text/plain, Size: 2712 bytes --] Bit me in https://github.com/thecoshman/http/issues/155: musl (and, thus, bionic) takes an int! Kill the "POSIX says 'request' is int" comment; prior to Issue 7, ioctl() is shaded STREAMS, it's obsolescent in Issue 7, and gone completely in Issue 8. The POSIX interface has never been supported by Linux, and the common ioctl() interface has never existed in POSIX or the SUS. Note how the interface evolved in HISTORY. The NetBSD CVS has revision 1.1 date: 1993-03-21 10:45:37 +0100; author: cgd; state: Exp; branches: 1.1.1; Initial revision ---------------------------- revision 1.1.1.2 date: 1995-02-27 11:49:43 +0100; author: cgd; state: Exp; lines: +6 -6; from Lite ---------------------------- revision 1.1.1.1 date: 1993-03-21 10:45:37 +0100; author: cgd; state: Exp; lines: +0 -0; initial import of 386bsd-0.1 sources ---------------------------- and it's char * in 1.1.1.1 and 1.1.1.2 but ... in 1.1, so hell knows. Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> --- man2/ioctl.2 | 52 ++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 4 deletions(-) diff --git a/man2/ioctl.2 b/man2/ioctl.2 index 6b55d47c9..d52f245c7 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" .fi .SH DESCRIPTION The @@ -103,7 +102,52 @@ .SH VERSIONS .SH STANDARDS None. .SH HISTORY -Version\~7 AT&T UNIX. +Version\~7 AT&T UNIX has +.PD 0 +.in +4n +.nf +.BI "ioctl(int " fildes ", int " request ", struct sgttyb *" argp ); +.fi +.in +.PP +.PD +(where +.B struct sgttyb +has historically been used by +.BR stty (2) +and +.BR gtty(2), +and is polymorphic by request type (like a +.B void * +would be, if it had been available)). +.PP +SysIII documents +.I arg +without a type at all. +.PP +4.3BSD has +.PD 0 +.in +4n +.nf +.BI "ioctl(int " d ", unsigned long " request ", char *" argp ); +.fi +.in +.PP +.PD +(with +.B char * +similarly in for +.BR "void *" ). +.PP +SysVr4 has +.PD 0 +.in +4n +.nf +.BI "int ioctl(int " fildes ", int " request ", ... /* " arg " */);" +.fi +.in +.PP +.PD .SH NOTES In order to use this call, one needs an open file descriptor. Often the -- 2.39.2 [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit 2023-09-13 16:02 ` наб @ 2023-09-13 16:44 ` Alejandro Colomar 2023-09-13 17:49 ` G. Branden Robinson 0 siblings, 1 reply; 8+ messages in thread From: Alejandro Colomar @ 2023-09-13 16:44 UTC (permalink / raw) To: наб; +Cc: linux-man, G. Branden Robinson, Jakub Wilk [-- Attachment #1.1: Type: text/plain, Size: 5028 bytes --] Hi, 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. From RFC 9110: http-URI = "http" "://" authority path-abempty [ "?" query ] path-abempty is defined in RFC 3986: path-abempty = *( "/" segment ) segment = *pchar pchar = unreserved / pct-encoded / sub-delims / ":" / "@" As you can see, ':' is allowed in a URI path. For your curiosity, here's the definition of other elements, per RFC 3986 too: unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" pct-encoded = "%" HEXDIG HEXDIG sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" reserved = gen-delims / sub-delims gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" Here's what uri(7) has to say: Writing a URI When written, URIs should be placed inside double quotes (e.g., "http://www.kernel.org"), enclosed in angle brackets (e.g., <http://lwn.net>), or placed on a line by themselves. A warning for those who use double‐quotes: never move extraneous punctua‐ tion (such as the period ending a sentence or the comma in a list) inside a URI, since this will change the value of the URI. Instead, use angle brackets instead, or switch to a quoting sys‐ tem that never includes extraneous characters inside quotation marks. This latter system, called the ’new’ or ’logical’ quoting system by "Hart’s Rules" and the "Oxford Dictionary for Writers and Editors", is preferred practice in Great Britain and in vari‐ ous European languages. Older documents suggested inserting the prefix "URL:" just before the URI, but this form has never caught on. > musl (and, thus, bionic) takes an int! > > Kill the "POSIX says 'request' is int" comment; > prior to Issue 7, ioctl() is shaded STREAMS, > it's obsolescent in Issue 7, > and gone completely in Issue 8. > The POSIX interface has never been supported by Linux, > and the common ioctl() interface has never existed in POSIX or the SUS. > > Note how the interface evolved in HISTORY. The NetBSD CVS has > revision 1.1 > date: 1993-03-21 10:45:37 +0100; author: cgd; state: Exp; > branches: 1.1.1; > Initial revision > ---------------------------- > revision 1.1.1.2 > date: 1995-02-27 11:49:43 +0100; author: cgd; state: Exp; lines: +6 > -6; > from Lite > ---------------------------- > revision 1.1.1.1 > date: 1993-03-21 10:45:37 +0100; author: cgd; state: Exp; lines: +0 > -0; > initial import of 386bsd-0.1 sources > ---------------------------- > and it's char * in 1.1.1.1 and 1.1.1.2 but ... in 1.1, so hell knows. > > Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> Patch applied. Cheers, Alex > --- > man2/ioctl.2 | 52 ++++++++++++++++++++++++++++++++++++++++++++++++---- > 1 file changed, 48 insertions(+), 4 deletions(-) > > diff --git a/man2/ioctl.2 b/man2/ioctl.2 > index 6b55d47c9..d52f245c7 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" [while applying, changed to use the \f[...] form.] > .fi > .SH DESCRIPTION > The > @@ -103,7 +102,52 @@ .SH VERSIONS > .SH STANDARDS > None. > .SH HISTORY > -Version\~7 AT&T UNIX. > +Version\~7 AT&T UNIX has > +.PD 0 > +.in +4n > +.nf > +.BI "ioctl(int " fildes ", int " request ", struct sgttyb *" argp ); > +.fi > +.in > +.PP > +.PD > +(where > +.B struct sgttyb > +has historically been used by > +.BR stty (2) > +and > +.BR gtty(2), [added a missing space while applying.] > +and is polymorphic by request type (like a > +.B void * > +would be, if it had been available)). > +.PP > +SysIII documents > +.I arg > +without a type at all. > +.PP > +4.3BSD has > +.PD 0 > +.in +4n > +.nf > +.BI "ioctl(int " d ", unsigned long " request ", char *" argp ); > +.fi > +.in > +.PP > +.PD > +(with > +.B char * > +similarly in for > +.BR "void *" ). > +.PP > +SysVr4 has > +.PD 0 > +.in +4n > +.nf > +.BI "int ioctl(int " fildes ", int " request ", ... /* " arg " */);" > +.fi > +.in > +.PP > +.PD > .SH NOTES > In order to use this call, one needs an open file descriptor. > Often the -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5 [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit 2023-09-13 16:44 ` Alejandro Colomar @ 2023-09-13 17:49 ` G. Branden Robinson 2023-09-13 21:23 ` Alejandro Colomar 0 siblings, 1 reply; 8+ messages in thread From: G. Branden Robinson @ 2023-09-13 17:49 UTC (permalink / raw) To: Alejandro Colomar; +Cc: наб, linux-man, Jakub Wilk [-- Attachment #1: Type: text/plain, Size: 2604 bytes --] 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] 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.) 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? 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. 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.) [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit 2023-09-13 17:49 ` G. Branden Robinson @ 2023-09-13 21:23 ` Alejandro Colomar 0 siblings, 0 replies; 8+ messages in thread From: Alejandro Colomar @ 2023-09-13 21:23 UTC (permalink / raw) To: G. Branden Robinson; +Cc: наб, linux-man, Jakub Wilk [-- Attachment #1.1: Type: text/plain, Size: 3327 bytes --] 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 #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 833 bytes --] ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2023-09-13 21:23 UTC | newest] Thread overview: 8+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2023-09-04 14:29 [PATCH] ioctl.2: note "int request" form, HISTORYise a bit наб 2023-09-04 15:41 ` Jakub Wilk 2023-09-04 15:58 ` наб 2023-09-13 15:24 ` Alejandro Colomar 2023-09-13 16:02 ` наб 2023-09-13 16:44 ` Alejandro Colomar 2023-09-13 17:49 ` G. Branden Robinson 2023-09-13 21:23 ` Alejandro Colomar
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).