[PATCH] uri.7: ffix

[PATCH] uri.7: ffix

[Alejandro Colomar]

Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man7/uri.7 | 51 ++++++++++++++++++++++++++++++++-------------------
 1 file changed, 32 insertions(+), 19 deletions(-)

diff --git a/man7/uri.7 b/man7/uri.7
index 19fe70f2f..51cf6b4e4 100644
--- a/man7/uri.7
+++ b/man7/uri.7
@@ -29,25 +29,38 @@
 .SH NAME
 uri, url, urn \- uniform resource identifier (URI), including a URL or URN
 .SH SYNOPSIS
-.nf
-.HP 0.2i
-URI = [ absoluteURI | relativeURI ] [ "#" fragment ]
-.HP
-absoluteURI = scheme ":" ( hierarchical_part | opaque_part )
-.HP
-relativeURI = ( net_path | absolute_path | relative_path ) [ "?" query ]
-.HP
-scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
-         "file" | "man" | "info" | "whatis" | "ldap" | "wais" | \&...
-.HP
-hierarchical_part = ( net_path | absolute_path ) [ "?" query ]
-.HP
-net_path = "//" authority [ absolute_path ]
-.HP
-absolute_path = "/"  path_segments
-.HP
-relative_path = relative_segment [ absolute_path ]
-.fi
+.SY URI
+= [ absoluteURI | relativeURI ] [ "#" fragment ]
+.YS
+.PP
+.SY absoluteURI
+= scheme ":" ( hierarchical_part | opaque_part )
+.YS
+.PP
+.SY relativeURI
+= ( net_path | absolute_path | relative_path ) [ "?" query ]
+.YS
+.PP
+.SY scheme
+= "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
+"file" | "man" | "info" | "whatis" | "ldap" | "wais" | \&...
+.YS
+.PP
+.SY hierarchical_part
+= ( net_path | absolute_path ) [ "?" query ]
+.YS
+.PP
+.SY net_path
+= "//" authority [ absolute_path ]
+.YS
+.PP
+.SY absolute_path
+= "/"  path_segments
+.YS
+.PP
+.SY relative_path
+= relative_segment [ absolute_path ]
+.YS
 .SH DESCRIPTION
 A Uniform Resource Identifier (URI) is a short string of characters
 identifying an abstract or physical resource (for example, a web page).
-- 
2.40.1

Re: [PATCH] uri.7: ffix

[G. Branden Robinson]

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

Hi Alex,

At 2023-04-29T21:46:43+0200, Alejandro Colomar wrote:
> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>  man7/uri.7 | 51 ++++++++++++++++++++++++++++++++-------------------
>  1 file changed, 32 insertions(+), 19 deletions(-)

Looks okay to me.  Glad to see deprecated things going away.

You might include the equals sign within the (double-quoted) `SY`
argument so that any indented lines align _after_ the equals sign rather
than under it, but that's a cosmetic detail and I don't know how it
comports with your other style conventions for man-pages(7).

Do you prefer

scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
         "file" | "man" | "info" | "whatis" | "ldap" | "wais" | ...

or

scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
       "file" | "man" | "info" | "whatis" | "ldap" | "wais" | ...

?

Regards,
Branden

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

Re: [PATCH] uri.7: ffix

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1571 bytes --]

Hi Branden,

On 4/30/23 01:07, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-04-29T21:46:43+0200, Alejandro Colomar wrote:
>> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
>> Signed-off-by: Alejandro Colomar <alx@kernel.org>
>> ---
>>  man7/uri.7 | 51 ++++++++++++++++++++++++++++++++-------------------
>>  1 file changed, 32 insertions(+), 19 deletions(-)
> 
> Looks okay to me.  Glad to see deprecated things going away.
> 
> You might include the equals sign within the (double-quoted) `SY`
> argument so that any indented lines align _after_ the equals sign rather
> than under it, but that's a cosmetic detail and I don't know how it
> comports with your other style conventions for man-pages(7).
> 
> Do you prefer
> 
> scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
>          "file" | "man" | "info" | "whatis" | "ldap" | "wais" | ...

I certainly prefer this; the reason I didn't put it into .SY was the
boldness of '=', but I may wrokaround that somehow...  Last resort, I
could use \f[R].

How are you doing with the regression?  Were you able to notice it in
the second set of PDFs?

BTW, I was going to ask you related to another warning I saw: What are
\f[C] and \f[CW]?

Cheers,
Alex

> 
> or
> 
> scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
>        "file" | "man" | "info" | "whatis" | "ldap" | "wais" | ...
> 
> ?
> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

Re: [PATCH] uri.7: ffix

[G. Branden Robinson]

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

At 2023-04-30T01:53:18+0200, Alejandro Colomar wrote:
> > scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" |
> >          "file" | "man" | "info" | "whatis" | "ldap" | "wais" | ...
> 
> I certainly prefer this; the reason I didn't put it into .SY was the
> boldness of '=', but I may wrokaround that somehow...  Last resort, I
> could use \f[R].

Yes.  This may be one of those rare cases where a font selection escape
sequence is the best solution.

> How are you doing with the regression?  Were you able to notice it in
> the second set of PDFs?

I haven't dug into it yet.  I find myself with a lot of emails to
answer...

> BTW, I was going to ask you related to another warning I saw: What are
> \f[C] and \f[CW]?

Two different names, from different traditions, for naming a
constant-width typeface.  (In groff, or any device-independent troff
taking a cue from PostScript, more than one constant-width face is
available on typesetting devices, and you would write 'CR' instead of
'C' or 'CW'.  But ultimately what faces are available depends on the
device for which you're formatting.  In the groff 1.23.0 man pages, this
matter is much clarified.  See its grodvi(1), grohtml(1), grolbp(1),
grolj4(1), gropdf(1), grops(1), grotty(1), and gxditview(1) man pages.

Not too long ago I discovered what I think is the ultimate origin of
`CW` usage as a face name, in the Unix System III manual.  I'll follow
up with more on that as time permits.

In man pages, no face names are truly portable apart from 'R', 'I', and
'B'.  That's what existed in 1979.  You can do sneaky things beyond
that, and I have.  But those are the ones you can count on.

Regards,
Branden

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