[PATCH] ioctl.2: note "int request" form, HISTORYise a bit

[PATCH] ioctl.2: note "int request" form, HISTORYise a bit

[наб]

[-- 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 --]

Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit

[Jakub Wilk]

* наб <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

Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit

[наб]

[-- 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 --]

Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit

[Alejandro Colomar]

[-- 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 --]

[PATCH] ioctl.2: note "int request" form, HISTORYise a bit

[наб]

[-- 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 --]

Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit

[Alejandro Colomar]

[-- 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 --]

Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit

[G. Branden Robinson]

[-- 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 --]

Re: [PATCH] ioctl.2: note "int request" form, HISTORYise a bit

[Alejandro Colomar]

[-- 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 --]