[PATCH] posix.py: ffix: Correctly format URIs

$ man 7 uri 2>/dev/null \
  |sed -n '/Writing a URI/,/^$/p';
   Writing a URI
       When  written, URIs should be placed inside double quotes
       (e.g., "http://www.kernel.org"), enclosed in angle brack‐
       ets  (e.g.,  <http://lwn.net>),  or  placed  on a line by
       themselves.  A warning for those who  use  double-quotes:
       never  move  extraneous  punctuation  (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 system
       that  never  includes extraneous characters inside quota‐
       tion marks.  This latter  system,  called  the  'new'  or
       'logical'  quoting  system by "Hart's Rules" and the "Ox‐
       ford Dictionary for Writers and  Editors",  is  preferred
       practice  in Great Britain and hackers worldwide (see the
       Jargon  File's   section   on   Hacker   Writing   Style,
       ⟨http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html⟩,
       for more information).   Older
       documents  suggested inserting the prefix "URL:" just be‐
       fore the URI, but this form has never caught on.

Enclose URIs in <>.  It is especially important in this case, as
the URIs are followed by '.'.
From "" or <>, I prefer <>, as they are less used in other
contexts, so they are more easily read as URIs.

This also fixes the extraneous space that was used to separate
the URIs from the final period.
In some cases, the period ended in a line of its own.

Also enclose them in [.UR/.UE].

Signed-off-by: Alejandro Colomar <redacted>
---

Hello Michael,

This patch is for man-pages-posix.git.
I found that the link in uri(7) is broken,
but I found that same document here:
http://www.catb.org/jargon/html/writing-style.html
I'll patch uri.7 to fix that link.

That was a very interesting read.
I got why you tend to use "xxxx (xxxx.)" and not "xxxx (xxxx).",
the latter being _much_ more common in Spanish (and other languages)
(actually, I've never read the former in Spanish).

Regards,

Alex

 posix.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/posix.py b/posix.py
index 55e401a..27f6207 100755
--- a/posix.py
+++ b/posix.py

@@ -337,14 +337,16 @@ for file in sys.argv[2:]:
       "Electrical and Electronics Engineers, Inc and The Open Group.\n"
       "In the event of any discrepancy between this version and the original IEEE and\n"
       "The Open Group Standard, the original IEEE and The Open Group Standard\n"
-      "is the referee document. The original Standard can be obtained online at\n"
-      "http://www.opengroup.org/unix/online.html .\n"
+      "is the referee document.  The original Standard can be obtained online at\n"
+      ".UR <http://www.opengroup.org/unix/online.html>\n"
+      ".UE .\n"
       ".PP\n"
       "Any typographical or formatting errors that appear\n"
       "in this page are most likely\n"
       "to have been introduced during the conversion of the source files to\n"
-      "man page format. To report such errors, see\n"
-      "https://www.kernel.org/doc/man-pages/reporting_bugs.html .\n"
+      "man page format.  To report such errors, see\n"
+      ".UR <https://www.kernel.org/doc/man-pages/reporting_bugs.html>\n"
+      ".UE .\n"
       )
 
     text = "".join(lines)

-- 
2.30.0

Hi Michael, Branden,

On 1/9/21 8:58 PM, Alejandro Colomar wrote:

$ man 7 uri 2>/dev/null \
  |sed -n '/Writing a URI/,/^$/p';
   Writing a URI
       When  written, URIs should be placed inside double quotes
       (e.g., "http://www.kernel.org"), enclosed in angle brack‐
       ets  (e.g.,  <http://lwn.net>),  or  placed  on a line by
       themselves.  A warning for those who  use  double-quotes:
       never  move  extraneous  punctuation  (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 system
       that  never  includes extraneous characters inside quota‐
       tion marks.  This latter  system,  called  the  'new'  or
       'logical'  quoting  system by "Hart's Rules" and the "Ox‐
       ford Dictionary for Writers and  Editors",  is  preferred
       practice  in Great Britain and hackers worldwide (see the
       Jargon  File's   section   on   Hacker   Writing   Style,
       ⟨http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html⟩,
       for more information).   Older
       documents  suggested inserting the prefix "URL:" just be‐
       fore the URI, but this form has never caught on.

Enclose URIs in <>.  It is especially important in this case, as
the URIs are followed by '.'.
From "" or <>, I prefer <>, as they are less used in other
contexts, so they are more easily read as URIs.

This also fixes the extraneous space that was used to separate
the URIs from the final period.
In some cases, the period ended in a line of its own.

Also enclose them in [.UR/.UE].

I was wondering if, instead of hardcoding <>,
it would be possible to make .UR/.UE embed those characters.
It would make the code more generic, but I don't know if it is feasible
or desirable.

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

On 1/9/21 8:58 PM, Alejandro Colomar wrote:

$ man 7 uri 2>/dev/null \
  |sed -n '/Writing a URI/,/^$/p';
   Writing a URI
       When  written, URIs should be placed inside double quotes
       (e.g., "http://www.kernel.org"), enclosed in angle brack‐
       ets  (e.g.,  <http://lwn.net>),  or  placed  on a line by
       themselves.  A warning for those who  use  double-quotes:
       never  move  extraneous  punctuation  (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 system
       that  never  includes extraneous characters inside quota‐
       tion marks.  This latter  system,  called  the  'new'  or
       'logical'  quoting  system by "Hart's Rules" and the "Ox‐
       ford Dictionary for Writers and  Editors",  is  preferred
       practice  in Great Britain and hackers worldwide (see the
       Jargon  File's   section   on   Hacker   Writing   Style,
       ⟨http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html⟩,
       for more information).   Older
       documents  suggested inserting the prefix "URL:" just be‐
       fore the URI, but this form has never caught on.

Enclose URIs in <>.  It is especially important in this case, as
the URIs are followed by '.'.
From "" or <>, I prefer <>, as they are less used in other
contexts, so they are more easily read as URIs.

This also fixes the extraneous space that was used to separate
the URIs from the final period.
In some cases, the period ended in a line of its own.

Also enclose them in [.UR/.UE].

Signed-off-by: Alejandro Colomar <redacted>

Hi Michael,

I forgot to setup the email.
Please fix it.

Thanks,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Hi Alex,

I've noticed you've started formatting your emails like recommended
*roff input.  ;-)

I have, however, taken the liberty of reformatting them conventionally
for brevity.

At 2021-01-09T22:07:09+0100, Alejandro Colomar (man-pages) wrote:

Hi Michael, Branden,
On 1/9/21 8:58 PM, Alejandro Colomar wrote:

[...]

quoted

Enclose URIs in <>.  It is especially important in this case, as the
URIs are followed by '.'.  From "" or <>, I prefer <>, as they are
less used in other contexts, so they are more easily read as URIs.

[...]

quoted

Also enclose them in [.UR/.UE].

I was wondering if, instead of hardcoding <>, it would be possible to
make .UR/.UE embed those characters.  It would make the code more
generic, but I don't know if it is feasible or desirable.

Not only is it possible, but the groff_man(7) .UR/.UE extension macros
have been doing this automatically since they were introduced in January
2007.

They use left and right angle bracket special character escapes (Unicode
U+2039 and U+203A)[1]; the output drivers degrade these to less-than and
greater-than signs if the former glyphs are unavailable, or if the
formatter is not groff[2].

Here are some of the relevant portions of tmac/an-ext.tmac.

[...]
  .\" groff has glyph entities for angle brackets.
  .ie \n(.g \{\
  .  ds la \(la\"
  .  ds ra \(ra\"
  .\}
  .el \{\
  .  ds la <\"
  .  ds ra >\"
  .  \" groff's man macros control hyphenation with this register.
  .  nr HY 1
  .\}
[...]
  .\" End URL.
  .de UE
[...]
  .    nh
  \\*(la\\*(m1\\*(ra\c
  .    ie \n(.g \&\\$*\"
  .    el \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\"
  .    hy \\n(HY
[...]
  ..

The macro has a lot of conditional logic to support multiple formatters,
include non-groff ones--it attempts to be usable even with old AT&T
troff.  For the same reason, the register and string names used are
short and unfriendly.  It also does special things when formatting for
groff's HTML output device, which I do not show above.  But the heart of
the matter for terminal output is the line

  \\*(la\\*(m1\\*(ra\c

which uses the left and right angle bracket strings defined previously.

Let me know if you could use the above in annotated form.

If something in your test environment is preventing the angle brackets
from being rendered, maybe I could help you troubleshoot it?

Regards,
Branden

[1] https://man7.org/linux/man-pages/man7/groff_char.7.html#Glyph_tables
[2] Technically, if the formatter does not claim groff compatibility by
    setting the .g register to a positive value.

Hi Branden,

On 1/10/21 7:50 AM, G. Branden Robinson wrote:

Hi Alex,

I've noticed you've started formatting your emails like recommended
*roff input.  ;-)

Yes.  Before I filled until the margin, but when I edited something at
the begining (especially when writing on the editor and not directly on
Thunderbird), I had to fix all the lines to fit the margin.

So to solve it, I decided to cut the lines at meaningful point, much
before the margin, as when writing manual pages, so that if I edit text
at the begining I don't have to edit every line.

That habit extended to what you can see :)

I have, however, taken the liberty of reformatting them conventionally
for brevity.

No problem.  Just a nitpick: when reading the mail from the phone, it
wraps around col 70 (more or less; it's not monospace, so it's an
experimental approximation), so many of the lines you compacted, expand
to a line and a word or so, effectively occupying 2 lines each, and
therefore occupying even more space than originally.

That's also the reason when I render a manual page and copy it's
contents to an email, I tend to use 68-col (or less) terminals, so that
text is nicely formatted on phones too.

At 2021-01-09T22:07:09+0100, Alejandro Colomar (man-pages) wrote:

quoted

Hi Michael, Branden,
On 1/9/21 8:58 PM, Alejandro Colomar wrote:

[...]

quoted

quoted

Enclose URIs in <>.  It is especially important in this case, as the
URIs are followed by '.'.  From "" or <>, I prefer <>, as they are
less used in other contexts, so they are more easily read as URIs.

[...]

quoted

quoted

Also enclose them in [.UR/.UE].

I was wondering if, instead of hardcoding <>, it would be possible to
make .UR/.UE embed those characters.  It would make the code more
generic, but I don't know if it is feasible or desirable.

Not only is it possible, but the groff_man(7) .UR/.UE extension macros
have been doing this automatically since they were introduced in January
2007.

They use left and right angle bracket special character escapes (Unicode
U+2039 and U+203A)[1]; the output drivers degrade these to less-than and
greater-than signs if the former glyphs are unavailable, or if the
formatter is not groff[2].

Here are some of the relevant portions of tmac/an-ext.tmac.

[...]
  .\" groff has glyph entities for angle brackets.
  .ie \n(.g \{\
  .  ds la \(la\"
  .  ds ra \(ra\"
  .\}
  .el \{\
  .  ds la <\"
  .  ds ra >\"
  .  \" groff's man macros control hyphenation with this register.
  .  nr HY 1
  .\}
[...]
  .\" End URL.
  .de UE
[...]
  .    nh
  \\*(la\\*(m1\\*(ra\c
  .    ie \n(.g \&\\$*\"
  .    el \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9\"
  .    hy \\n(HY
[...]
  ..

The macro has a lot of conditional logic to support multiple formatters,
include non-groff ones--it attempts to be usable even with old AT&T
troff.  For the same reason, the register and string names used are
short and unfriendly.  It also does special things when formatting for
groff's HTML output device, which I do not show above.  But the heart of
the matter for terminal output is the line

  \\*(la\\*(m1\\*(ra\c

which uses the left and right angle bracket strings defined previously.

Let me know if you could use the above in annotated form.

If something in your test environment is preventing the angle brackets
from being rendered, maybe I could help you troubleshoot it?

Regards,
Branden

Hmm, I might have read a few URLs that didn't use .UR/.UE to think that
they didn't render a character; I don't know.  After your email, I
checked, and yes, it renders some character (the character depends on
the terminal: on tty I've seen a diamond, and on the xfce terminal
something similar (but slightly different) to a parenthesis).

So I'll send a v2 patch removing the <>.

Thanks!

Alex

[1] https://man7.org/linux/man-pages/man7/groff_char.7.html#Glyph_tables
[2] Technically, if the formatter does not claim groff compatibility by
    setting the .g register to a positive value.

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

$ man 7 uri 2>/dev/null \
  |sed -n '/Writing a URI/,/^$/p';
   Writing a URI
       When  written, URIs should be placed inside double quotes
       (e.g., "http://www.kernel.org"), enclosed in angle brack‐
       ets  (e.g.,  <http://lwn.net>),  or  placed  on a line by
       themselves.  A warning for those who  use  double-quotes:
       never  move  extraneous  punctuation  (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 system
       that  never  includes extraneous characters inside quota‐
       tion marks.  This latter  system,  called  the  'new'  or
       'logical'  quoting  system by "Hart's Rules" and the "Ox‐
       ford Dictionary for Writers and  Editors",  is  preferred
       practice  in Great Britain and hackers worldwide (see the
       Jargon  File's   section   on   Hacker   Writing   Style,
       ⟨http://www.fwi.uva.nl/~mes/jargon/h
       /HackerWritingStyle.html⟩, for more information).   Older
       documents  suggested inserting the prefix "URL:" just be‐
       fore the URI, but this form has never caught on.

Enclose URIs in .UR/.UE,
which encloses the URIs in between <> (or similar characters).
It is especially important in this case,
as the URIs are followed by '.'.

This also fixes the extraneous space that was used to
separate the URIs from the final period.
In some cases, the period ended in a line of its own.

Signed-off-by: Alejandro Colomar <redacted>
---
 posix.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/posix.py b/posix.py
index 55e401a..60271cc 100755
--- a/posix.py
+++ b/posix.py

@@ -337,14 +337,16 @@ for file in sys.argv[2:]:
       "Electrical and Electronics Engineers, Inc and The Open Group.\n"
       "In the event of any discrepancy between this version and the original IEEE and\n"
       "The Open Group Standard, the original IEEE and The Open Group Standard\n"
-      "is the referee document. The original Standard can be obtained online at\n"
-      "http://www.opengroup.org/unix/online.html .\n"
+      "is the referee document.  The original Standard can be obtained online at\n"
+      ".UR http://www.opengroup.org/unix/online.html\n"
+      ".UE .\n"
       ".PP\n"
       "Any typographical or formatting errors that appear\n"
       "in this page are most likely\n"
       "to have been introduced during the conversion of the source files to\n"
-      "man page format. To report such errors, see\n"
-      "https://www.kernel.org/doc/man-pages/reporting_bugs.html .\n"
+      "man page format.  To report such errors, see\n"
+      ".UR https://www.kernel.org/doc/man-pages/reporting_bugs.html\n"
+      ".UE .\n"
       )
 
     text = "".join(lines)

-- 
2.30.0

On 1/10/21 7:50 AM, G. Branden Robinson wrote:

quoted

They use left and right angle bracket special character escapes 
(Unicode U+2039 and U+203A)

I think that's a bug in groff. It should use plain <> for URLs, at least 
for tty output devices.

* Alejandro Colomar [off-list ref], 2021-01-10, 15:35:

I checked, and yes, it renders some character (the character depends on 
the terminal: on tty I've seen a diamond, and on the xfce terminal 
something similar (but slightly different) to a parenthesis).

Your console font doesn't support U+2039/U+203A and uses diamond as a 
replacement character.

I have this in /etc/groff/mdoc.local and /etc/groff/mdoc.local as a 
work-around:

.  if '\V[TERM]'linux' \
.    tr \[la]<
.  if '\V[TERM]'linux' \
.    tr \[ra]>

(In the long run, I should probably fix the font instead.)

-- 
Jakub Wilk

[redirecting to groff@gnu.org; Reply-To set]

Hi Jakub!

At 2021-01-12T21:51:15+0100, Jakub Wilk wrote:

quoted

On 1/10/21 7:50 AM, G. Branden Robinson wrote:

[regarding groff's an-ext.tmac's .UR/.UE macros]

quoted

quoted

They use left and right angle bracket special character escapes
(Unicode U+2039 and U+203A)

I think that's a bug in groff. It should use plain <> for URLs, at
least for tty output devices.

Even for TTY devices that can render angle brackets just fine?  Can you
say why?

* Alejandro Colomar [off-list ref], 2021-01-10, 15:35:

quoted

I checked, and yes, it renders some character (the character depends
on the terminal: on tty I've seen a diamond, and on the xfce
terminal something similar (but slightly different) to a
parenthesis).

Your console font doesn't support U+2039/U+203A and uses diamond as a
replacement character.

I have this in /etc/groff/mdoc.local and /etc/groff/mdoc.local as a
work-around:

.  if '\V[TERM]'linux' \
.    tr \[la]<
.  if '\V[TERM]'linux' \
.    tr \[ra]>

(In the long run, I should probably fix the font instead.)

I think this may be another use case for the .soquiet and .msoquiet[1]
requests I have proposed to support possibly-nonexistent or
permission-blocked opens of files; in this case, something like
$HOME/.troffrc or $XDG_DATA_HOME/troffrc.

I don't share Jakub's preference but, with the right tools, I'd defend
to the death his right to configure it.  :D

Thoughts?

Regards,
Branden

[1] Or .sofailok or .msofailok or whatever we end up calling them.

Ping!

On 1/10/21 3:57 PM, Alejandro Colomar wrote:

Hi Alex,

On 1/10/21 3:57 PM, Alejandro Colomar wrote:

$ man 7 uri 2>/dev/null \
  |sed -n '/Writing a URI/,/^$/p';
   Writing a URI
       When  written, URIs should be placed inside double quotes
       (e.g., "http://www.kernel.org"), enclosed in angle brack‐
       ets  (e.g.,  <http://lwn.net>),  or  placed  on a line by
       themselves.  A warning for those who  use  double-quotes:
       never  move  extraneous  punctuation  (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 system
       that  never  includes extraneous characters inside quota‐
       tion marks.  This latter  system,  called  the  'new'  or
       'logical'  quoting  system by "Hart's Rules" and the "Ox‐
       ford Dictionary for Writers and  Editors",  is  preferred
       practice  in Great Britain and hackers worldwide (see the
       Jargon  File's   section   on   Hacker   Writing   Style,
       ⟨http://www.fwi.uva.nl/~mes/jargon/h
       /HackerWritingStyle.html⟩, for more information).   Older
       documents  suggested inserting the prefix "URL:" just be‐
       fore the URI, but this form has never caught on.

Enclose URIs in .UR/.UE,
which encloses the URIs in between <> (or similar characters).
It is especially important in this case,
as the URIs are followed by '.'.

This also fixes the extraneous space that was used to
separate the URIs from the final period.
In some cases, the period ended in a line of its own.

Signed-off-by: Alejandro Colomar <redacted>

Thanks. Patch applied.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Hi Alex,

On 1/10/21 3:57 PM, Alejandro Colomar wrote:

$ man 7 uri 2>/dev/null \
  |sed -n '/Writing a URI/,/^$/p';
   Writing a URI
       When  written, URIs should be placed inside double quotes
       (e.g., "http://www.kernel.org"), enclosed in angle brack‐
       ets  (e.g.,  <http://lwn.net>),  or  placed  on a line by
       themselves.  A warning for those who  use  double-quotes:
       never  move  extraneous  punctuation  (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 system
       that  never  includes extraneous characters inside quota‐
       tion marks.  This latter  system,  called  the  'new'  or
       'logical'  quoting  system by "Hart's Rules" and the "Ox‐
       ford Dictionary for Writers and  Editors",  is  preferred
       practice  in Great Britain and hackers worldwide (see the
       Jargon  File's   section   on   Hacker   Writing   Style,
       ⟨http://www.fwi.uva.nl/~mes/jargon/h
       /HackerWritingStyle.html⟩, for more information).   Older
       documents  suggested inserting the prefix "URL:" just be‐
       fore the URI, but this form has never caught on.

Enclose URIs in .UR/.UE,
which encloses the URIs in between <> (or similar characters).
It is especially important in this case,
as the URIs are followed by '.'.

This also fixes the extraneous space that was used to
separate the URIs from the final period.
In some cases, the period ended in a line of its own.

Signed-off-by: Alejandro Colomar <redacted>

Thanks. Patch applied.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Hi Jakub and Branden,

On 1/12/21 9:51 PM, Jakub Wilk wrote:

quoted

On 1/10/21 7:50 AM, G. Branden Robinson wrote:

quoted

They use left and right angle bracket special character escapes
(Unicode U+2039 and U+203A)

I think that's a bug in groff. It should use plain <> for URLs, at least
for tty output devices.

* Alejandro Colomar [off-list ref], 2021-01-10, 15:35:

quoted

I checked, and yes, it renders some character (the character depends
on the terminal: on tty I've seen a diamond, and on the xfce terminal
something similar (but slightly different) to a parenthesis).

Your console font doesn't support U+2039/U+203A and uses diamond as a
replacement character.

I have this in /etc/groff/mdoc.local and /etc/groff/mdoc.local as a
work-around:

.  if '\V[TERM]'linux' \
.    tr \[la]<
.  if '\V[TERM]'linux' \
.    tr \[ra]>

(In the long run, I should probably fix the font instead.)

After seeing Branden's answer to Michael (Escaping hyphens),
I've seen groff_char(7), and I found that my tty correctly supports
U+2039 and U+203A.  I clearly see the symbols I would expect: something
quite similar to plain <>, but a bit more obtuse.

In the XFCE terminal, I also see something quite expected: a slightly
smaller version of <>.

But both show me very different characters for .UR/.UE.
tty displays a diamond, and XFCE term displays (a weird version of)
round parentheses.

So... does it mean there's a bug in .UR/.UE?

Thanks,

Alex

* Alejandro Colomar [off-list ref], 2021-01-21, 20:54:

On 1/12/21 9:51 PM, Jakub Wilk wrote:

quoted

quoted

On 1/10/21 7:50 AM, G. Branden Robinson wrote:

quoted

They use left and right angle bracket special character escapes 
(Unicode U+2039 and U+203A)

I think that's a bug in groff. It should use plain <> for URLs, at least
for tty output devices.

* Alejandro Colomar [off-list ref], 2021-01-10, 15:35:

quoted

I checked, and yes, it renders some character (the character depends 
on the terminal: on tty I've seen a diamond, and on the xfce terminal 
something similar (but slightly different) to a parenthesis).

Your console font doesn't support U+2039/U+203A and uses diamond as a 
replacement character.

I have this in /etc/groff/mdoc.local and /etc/groff/mdoc.local as a 
work-around:

.  if '\V[TERM]'linux' \
.    tr \[la]<
.  if '\V[TERM]'linux' \
.    tr \[ra]>

(In the long run, I should probably fix the font instead.)

After seeing Branden's answer to Michael (Escaping hyphens), I've seen 
groff_char(7), and I found that my tty correctly supports U+2039 and 
U+203A.  I clearly see the symbols I would expect: something quite 
similar to plain <>, but a bit more obtuse.

In the XFCE terminal, I also see something quite expected: a slightly 
smaller version of <>.

But both show me very different characters for .UR/.UE.
tty displays a diamond, and XFCE term displays (a weird version of) 
round parentheses.

So... does it mean there's a bug in .UR/.UE?

Or a bug in Branden. ;-)

Contrary to what he wrote, and what I parroted, .UR/.UE use U+27E8 and 
U+27E9 as delimiters.

-- 
Jakub Wilk

On 1/21/21 9:14 PM, Jakub Wilk wrote:
[...]

quoted

So... does it mean there's a bug in .UR/.UE?

Or a bug in Branden. ;-)>
Contrary to what he wrote, and what I parroted, .UR/.UE use U+27E8 and
U+27E9 as delimiters.

Ahh, that's it!
Will have to patch it... :-P

At 2021-01-21T21:14:26+0100, Jakub Wilk wrote:

quoted

After seeing Branden's answer to Michael (Escaping hyphens), I've
seen groff_char(7), and I found that my tty correctly supports
U+2039 and U+203A.  I clearly see the symbols I would expect:
something quite similar to plain <>, but a bit more obtuse.

In the XFCE terminal, I also see something quite expected: a
slightly smaller version of <>.

But both show me very different characters for .UR/.UE.  tty
displays a diamond, and XFCE term displays (a weird version of)
round parentheses.

So... does it mean there's a bug in .UR/.UE?

Or a bug in Branden. ;-)

Contrary to what he wrote, and what I parroted, .UR/.UE use U+27E8 and
U+27E9 as delimiters.

Mea culpa.  I don't know where I got U+2039 and U+203A.  It wasn't from
checking groff_char(7), which correctly documents the special character
escapes.  (Which softens the blow--I'd rather be wrong on a mailing list
thread than in a man page.)

U+2039 and U+203A are "single {left,right}-pointing angle quotation
mark" per Unicode.  Their groff special character escapes are \[fo] and
\[fc], respectively.  (I don't know the mnemonic that inspired the
"f" in the name.)

U+27E8 and U+27E9 are "mathematical {left,right} angle bracket" per
Unicode.  Their groff special character escapes are \[la] and \[ra],
respectively.  I _assume_, without having interviewed Werner Lemberg or
Eric Raymond on the subject, that angle brackets were chosen for .UR/.UE
(and .MT/.ME) in continuity with existing practice elsewhere.

If your terminals' font coverage refuses to support U+27E[89]
reasonably, you can remap the characters.  This is good fodder for
man.local[1], recently discussed here in another thread.

.if '\*[.T]'utf8' \{\
.  char \[la] \[Fo]
.  char \[ra] \[Fc]
.\}

...or you can just put < and > in place of \[Fo] and \[Fc] if you
prefer.

(The conditional checks the output driver being used for rendering.  It
keeps the glyphs from being remapped for PostScript of PDF output, for
instance.)

It may happen that you want to alter the character mappings only for
some terminal types, perhaps because some terminal emulator uses fonts
with a meager glyph repertoire.  Here's an example of how to do a string
comparison against an environment variable.

.if '\*[.T]'utf8'
.  if '\V[TERM]'linux' \{\
.    char \[la] \[Fo]
.    char \[ra] \[Fc]
.\}

In any event, if any font designed for use with terminal emulators
claims Unicode coverage and lacks glyphs for any of the special
character escapes in groff_char(7), I would regard that as a bug in the
font that should be reported to its maintainers.  The list of groff
special escapes has been stable for several years and is not expected to
change[2]; if I recall correctly, the previous groff maintainer Werner
Lemberg felt it should be frozen.

Regards,
Branden

[1] available at /etc/groff/man.local on Debian-based systems
[2] This does not mean that macro packages cannot extend the list, and
    in fact there is a pending contribution from Dorai Sitaram called
    rfc1345.tmac which adds all the digraphs from Vim (which are in turn
    based on RFC 1345) to the repertoire, and should be a nice
    convenience for users familiar with those.  I plan to merge it prior
    to the release of groff 1.23.0.  Authors of man pages intended for
    broad portability, however, should not source this macro file.  It
    remains to be seen what other implementations like Heirloom Doctools
    troff and mandoc do about it.

At 2021-01-22T10:35:56+0100, Jakub Wilk wrote:

* G. Branden Robinson [off-list ref], 2021-01-22, 14:23:

quoted

U+2039 and U+203A are "single {left,right}-pointing angle quotation
mark" per Unicode.  Their groff special character escapes are \[fo]
and \[fc], respectively.  (I don't know the mnemonic that inspired
the "f" in the name.)

"French", I guess:
https://en.wikipedia.org/wiki/French_quotes#French

Thanks.  That's probably true, alas for the poor overlooked Finns,
Swedes, Greeks, Hungarians, Portuguese...

quoted

.  char \[la] \[Fo]
.  char \[ra] \[Fc]

Should be lowercase "f" here.

You're right: we have both kinds--Country _and_ Western!

       «        \[Fo]   u00AB     left double chevron
       »        \[Fc]   u00BB     right double chevron
       ‹        \[fo]   u2039     left single chevron
       ›        \[fc]   u203A     right single chevron
[from groff_char(7) in the forthcoming groff 1.23.0]

I don't think I've ever seen URLs bracketed «like this».

On the other hand, because \[Fo] and \[Fc] are in the ISO 8859 character
sets, aren't they much more likely to be supported by the Linux console
driver?

Regards,
Branden

* G. Branden Robinson [off-list ref], 2021-01-22, 14:23:

U+2039 and U+203A are "single {left,right}-pointing angle quotation 
mark" per Unicode.  Their groff special character escapes are \[fo] and 
\[fc], respectively.  (I don't know the mnemonic that inspired the "f" 
in the name.)

"French", I guess:
https://en.wikipedia.org/wiki/French_quotes#French

.  char \[la] \[Fo]
.  char \[ra] \[Fc]

Should be lowercase "f" here.

-- 
Jakub Wilk

On 1/22/21 11:07 AM, G. Branden Robinson wrote:

At 2021-01-22T10:35:56+0100, Jakub Wilk wrote:

quoted

* G. Branden Robinson [off-list ref], 2021-01-22, 14:23:

quoted

U+2039 and U+203A are "single {left,right}-pointing angle quotation
mark" per Unicode.  Their groff special character escapes are \[fo]
and \[fc], respectively.  (I don't know the mnemonic that inspired
the "f" in the name.)

"French", I guess:
https://en.wikipedia.org/wiki/French_quotes#French

Thanks.  That's probably true, alas for the poor overlooked Finns,
Swedes, Greeks, Hungarians, Portuguese...

quoted

quoted

.  char \[la] \[Fo]
.  char \[ra] \[Fc]

Should be lowercase "f" here.

You're right: we have both kinds--Country _and_ Western!

        «        \[Fo]   u00AB     left double chevron
        »        \[Fc]   u00BB     right double chevron
        ‹        \[fo]   u2039     left single chevron
        ›        \[fc]   u203A     right single chevron
[from groff_char(7) in the forthcoming groff 1.23.0]

I don't think I've ever seen URLs bracketed «like this».

On the other hand, because \[Fo] and \[Fc] are in the ISO 8859 character
sets, aren't they much more likely to be supported by the Linux console
driver?

For that same reason we could conclude that <> (less than, greater than) 
have even better support :)

I'd use either u2039/A, or plain <>.

Regards,

Alex

Regards,
Branden

-- 
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

On 1/9/21 8:58 PM, Alejandro Colomar wrote:

$ man 7 uri 2>/dev/null \
  |sed -n '/Writing a URI/,/^$/p';
   Writing a URI
       When  written, URIs should be placed inside double quotes
       (e.g., "http://www.kernel.org"), enclosed in angle brack‐
       ets  (e.g.,  <http://lwn.net>),  or  placed  on a line by
       themselves.  A warning for those who  use  double-quotes:
       never  move  extraneous  punctuation  (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 system
       that  never  includes extraneous characters inside quota‐
       tion marks.  This latter  system,  called  the  'new'  or
       'logical'  quoting  system by "Hart's Rules" and the "Ox‐
       ford Dictionary for Writers and  Editors",  is  preferred
       practice  in Great Britain and hackers worldwide (see the
       Jargon  File's   section   on   Hacker   Writing   Style,
       ⟨http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html⟩,
       for more information).   Older
       documents  suggested inserting the prefix "URL:" just be‐
       fore the URI, but this form has never caught on.

Enclose URIs in <>.  It is especially important in this case, as
the URIs are followed by '.'.
From "" or <>, I prefer <>, as they are less used in other
contexts, so they are more easily read as URIs.

This also fixes the extraneous space that was used to separate
the URIs from the final period.
In some cases, the period ended in a line of its own.

Also enclose them in [.UR/.UE].

Signed-off-by: Alejandro Colomar <redacted>
---

Hello Michael,

This patch is for man-pages-posix.git.
I found that the link in uri(7) is broken,
but I found that same document here:
http://www.catb.org/jargon/html/writing-style.html
I'll patch uri.7 to fix that link.

That was a very interesting read.
I got why you tend to use "xxxx (xxxx.)" and not "xxxx (xxxx).",
the latter being _much_ more common in Spanish (and other languages)
(actually, I've never read the former in Spanish).

Hey Michael,

Ping!

I'm still very interested in knowing your thoughts about the Hacker
Writing Style from the Jargon File, and more specifically about the
so-called `new' or `logical' quoting method[1].  Especially you being
both a hacker and a writer :-).

[1]: http://www.catb.org/jargon/html/writing-style.html

I'll quote the most important part here so you don't need to follow the
link (but I recommend it, though):

[[
Hackers tend to use quotes as balanced delimiters like parentheses, much
to the dismay of American editors. Thus, if “Jim is going” is a phrase,
and so are “Bill runs” and “Spock groks”, then hackers generally prefer
to write: “Jim is going”, “Bill runs”, and “Spock groks”. This is
incorrect according to standard American usage (which would put the
continuation commas and the final period inside the string quotes);
however, it is counter-intuitive to hackers to mutilate literal strings
with characters that don't belong in them. Given the sorts of examples
that can come up in discussions of programming, American-style quoting
can even be grossly misleading. When communicating command lines or
small pieces of code, extra characters can be a real pain in the neck.

Consider, for example, a sentence in a vi tutorial that looks like this:

    Then delete a line from the file by typing “dd”.

Standard usage would make this

    Then delete a line from the file by typing “dd.”

but that would be very bad — because the reader would be prone to type
the string d-d-dot, and it happens that in vi(1), dot repeats the last
command accepted. The net result would be to delete two lines!

The Jargon File follows hackish usage throughout.

Interestingly, a similar style is now preferred practice in Great
Britain, though the older style (which became established for
typographical reasons having to do with the aesthetics of comma and
quotes in typeset text) is still accepted there. Hart's Rules and the
Oxford Dictionary for Writers and Editors call the hacker-like style
‘new’ or ‘logical’ quoting. This returns British English to the style
many other languages (including Spanish, French, Italian, Catalan, and
German) have been using all along.
]]

BTW, I should remind myself to fix the link in uri.7.

Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Hi Alex,

At 2021-01-22T11:50:02+0100, Alejandro Colomar (man-pages) wrote:

On 1/22/21 11:07 AM, G. Branden Robinson wrote:

quoted

I don't think I've ever seen URLs bracketed «like this».

On the other hand, because \[Fo] and \[Fc] are in the ISO 8859
character sets, aren't they much more likely to be supported by the
Linux console driver?

For that same reason we could conclude that <> (less than, greater
than) have even better support :)

I'd use either u2039/A, or plain <>.

The less and greater than signs are already used to bracket URLs using
the .UR and .UE requests on non-UTF-8 devices and non-groff formatters.

If funny characters (or the Unicode replacement character) are rendering
around the URLs in your terminal window, then there are a few
possibilities.

1.  Something is misconfigured; try a stock groff installation in an
    xterm.
2.  The font you're using in your terminal emulator lacks adequate glyph
    coverage; a look at groff_char(7) may help determine this.
3.  Your terminal emulator inadequately supports some aspect of UTF-8.

/usr/share/groff/1.22.4/tmac/an-ext.tmac:
    43  .\" groff has glyph entities for angle brackets.
    44  .ie \n(.g \{\
    45  .  ds la \(la\"
    46  .  ds ra \(ra\"
    47  .\}
    48  .el \{\
    49  .  ds la <\"
    50  .  ds ra >\"
    51  .  \" groff's man macros control hyphenation with this register.
    52  .  nr HY 1
    53  .\}

The above chunk of the groff man(7) extension macros has not been
changed in 14 years, and no changes to the above string definitions are
planned.  (Nor do I anticipate changes to the value of the HY register,
since it's present for non-groff formatters, but it's a completely
separate issue.)

$ grep -B 1 -Ew '(la|ra)' /usr/share/groff/1.22.4/font/dev{ascii,latin1}/*

/usr/share/groff/1.22.4/font/devascii/B-<       24      0       0074
/usr/share/groff/1.22.4/font/devascii/B:la      "
--
/usr/share/groff/1.22.4/font/devascii/B->       24      0       0076
/usr/share/groff/1.22.4/font/devascii/B:ra      "
--
/usr/share/groff/1.22.4/font/devascii/BI-<      24      0       0074
/usr/share/groff/1.22.4/font/devascii/BI:la     "
--
/usr/share/groff/1.22.4/font/devascii/BI->      24      0       0076
/usr/share/groff/1.22.4/font/devascii/BI:ra     "
--
/usr/share/groff/1.22.4/font/devascii/I-<       24      0       0074
/usr/share/groff/1.22.4/font/devascii/I:la      "
--
/usr/share/groff/1.22.4/font/devascii/I->       24      0       0076
/usr/share/groff/1.22.4/font/devascii/I:ra      "
--
/usr/share/groff/1.22.4/font/devascii/R-<       24      0       0074
/usr/share/groff/1.22.4/font/devascii/R:la      "
--
/usr/share/groff/1.22.4/font/devascii/R->       24      0       0076
/usr/share/groff/1.22.4/font/devascii/R:ra      "
--
/usr/share/groff/1.22.4/font/devlatin1/B-<      24      0       0074
/usr/share/groff/1.22.4/font/devlatin1/B:la     "
--
[...and so on...]

The \(la and \(ra special character escapes map to < and > respectively
for non-UTF-8 terminal devices in groff.

So, as it happens, do \(fo and \(fc.

Here's a simple reproducer you can feed to "nroff -man" or "groff -Tutf8
-man".

	.TH foo 1
	.UR bar
	.UE

Regards,
Branden

Hi Alex,

On Fri, 22 Jan 2021 at 13:37, Alejandro Colomar (man-pages)
[off-list ref] wrote:

On 1/9/21 8:58 PM, Alejandro Colomar wrote:

quoted

$ man 7 uri 2>/dev/null \
  |sed -n '/Writing a URI/,/^$/p';
   Writing a URI
       When  written, URIs should be placed inside double quotes
       (e.g., "http://www.kernel.org"), enclosed in angle brack‐
       ets  (e.g.,  <http://lwn.net>),  or  placed  on a line by
       themselves.  A warning for those who  use  double-quotes:
       never  move  extraneous  punctuation  (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 system
       that  never  includes extraneous characters inside quota‐
       tion marks.  This latter  system,  called  the  'new'  or
       'logical'  quoting  system by "Hart's Rules" and the "Ox‐
       ford Dictionary for Writers and  Editors",  is  preferred
       practice  in Great Britain and hackers worldwide (see the
       Jargon  File's   section   on   Hacker   Writing   Style,
       ⟨http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html⟩,
       for more information).   Older
       documents  suggested inserting the prefix "URL:" just be‐
       fore the URI, but this form has never caught on.

Enclose URIs in <>.  It is especially important in this case, as
the URIs are followed by '.'.
From "" or <>, I prefer <>, as they are less used in other
contexts, so they are more easily read as URIs.

This also fixes the extraneous space that was used to separate
the URIs from the final period.
In some cases, the period ended in a line of its own.

Also enclose them in [.UR/.UE].

Signed-off-by: Alejandro Colomar <redacted>
---

Hello Michael,

This patch is for man-pages-posix.git.
I found that the link in uri(7) is broken,
but I found that same document here:
http://www.catb.org/jargon/html/writing-style.html
I'll patch uri.7 to fix that link.

That was a very interesting read.
I got why you tend to use "xxxx (xxxx.)" and not "xxxx (xxxx).",

Sorry... I don't understand what you are referring to in the previous line.

quoted

the latter being _much_ more common in Spanish (and other languages)
(actually, I've never read the former in Spanish).

Hey Michael,

Ping!

I'm still very interested in knowing your thoughts about the Hacker
Writing Style from the Jargon File, and more specifically about the
so-called `new' or `logical' quoting method[1].  Especially you being
both a hacker and a writer :-).

[1]: http://www.catb.org/jargon/html/writing-style.html

So, I regard the Jargon File and HWS as no real authority on anything,
and I'm not even sure we should refer to them in a manual page. Much
of the writing there is rather polemical. But, that said...

I'll quote the most important part here so you don't need to follow the
link (but I recommend it, though):

[[
Hackers tend to use quotes as balanced delimiters like parentheses, much
to the dismay of American editors. Thus, if “Jim is going” is a phrase,
and so are “Bill runs” and “Spock groks”, then hackers generally prefer
to write: “Jim is going”, “Bill runs”, and “Spock groks”. This is
incorrect according to standard American usage (which would put the
continuation commas and the final period inside the string quotes);
however, it is counter-intuitive to hackers to mutilate literal strings
with characters that don't belong in them. Given the sorts of examples
that can come up in discussions of programming, American-style quoting
can even be grossly misleading. When communicating command lines or
small pieces of code, extra characters can be a real pain in the neck.

Consider, for example, a sentence in a vi tutorial that looks like this:

    Then delete a line from the file by typing “dd”.

Standard usage would make this

    Then delete a line from the file by typing “dd.”

but that would be very bad — because the reader would be prone to type
the string d-d-dot, and it happens that in vi(1), dot repeats the last
command accepted. The net result would be to delete two lines!

The Jargon File follows hackish usage throughout.

Interestingly, a similar style is now preferred practice in Great
Britain, though the older style (which became established for
typographical reasons having to do with the aesthetics of comma and
quotes in typeset text) is still accepted there. Hart's Rules and the
Oxford Dictionary for Writers and Editors call the hacker-like style
‘new’ or ‘logical’ quoting. This returns British English to the style
many other languages (including Spanish, French, Italian, Catalan, and
German) have been using all along.
]]

Like many programmers, I find the Logical Style, ahhh, logical. And in
a fixed-width font, the visual argument for putting periods and commas
inside the quotes (the American style) doesn't apply. The
counterargument is that in most every other aspect, man-pages follows
American conventions.

I imagine that in man-pages there's a mix of both styles, since I'm
not sure if I've ever taken care about this.

So, what to do... Given that man-pages are primarily rendered to
fix-width displays, and the confusion that can sometimes occur in a
technical context if following the American style, I would not oppose
switching everything British/Logical style.

Maybe others have opinions to offer.

BTW, I should remind myself to fix the link in uri.7.

I'd be inclined to remove the URL. Mention of the Logical Style in
Hart's rules and the British style is good enough, I think.

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Hi Branden,

On 1/22/21 3:51 PM, G. Branden Robinson wrote:

Hi Alex,

At 2021-01-22T11:50:02+0100, Alejandro Colomar (man-pages) wrote:

quoted

On 1/22/21 11:07 AM, G. Branden Robinson wrote:

quoted

I don't think I've ever seen URLs bracketed «like this».

On the other hand, because \[Fo] and \[Fc] are in the ISO 8859
character sets, aren't they much more likely to be supported by the
Linux console driver?

For that same reason we could conclude that <> (less than, greater
than) have even better support :)

I'd use either u2039/A, or plain <>.

The less and greater than signs are already used to bracket URLs using
the .UR and .UE requests on non-UTF-8 devices and non-groff formatters.

If funny characters (or the Unicode replacement character) are rendering
around the URLs in your terminal window, then there are a few
possibilities.

1.  Something is misconfigured; try a stock groff installation in an
     xterm.
2.  The font you're using in your terminal emulator lacks adequate glyph
     coverage; a look at groff_char(7) may help determine this.
3.  Your terminal emulator inadequately supports some aspect of UTF-8.

I'll investigate with the tools you gave me below.
Right now, the only thing I know is that I'm using Debian Sid's 
defaults.  I never touched groff's config files.  And thanks, for the 
man.local code snippet!

Thanks,

Alex

/usr/share/groff/1.22.4/tmac/an-ext.tmac:
     43  .\" groff has glyph entities for angle brackets.
     44  .ie \n(.g \{\
     45  .  ds la \(la\"
     46  .  ds ra \(ra\"
     47  .\}
     48  .el \{\
     49  .  ds la <\"
     50  .  ds ra >\"
     51  .  \" groff's man macros control hyphenation with this register.
     52  .  nr HY 1
     53  .\}

The above chunk of the groff man(7) extension macros has not been
changed in 14 years, and no changes to the above string definitions are
planned.  (Nor do I anticipate changes to the value of the HY register,
since it's present for non-groff formatters, but it's a completely
separate issue.)

$ grep -B 1 -Ew '(la|ra)' /usr/share/groff/1.22.4/font/dev{ascii,latin1}/*

/usr/share/groff/1.22.4/font/devascii/B-<       24      0       0074
/usr/share/groff/1.22.4/font/devascii/B:la      "
--
/usr/share/groff/1.22.4/font/devascii/B->       24      0       0076
/usr/share/groff/1.22.4/font/devascii/B:ra      "
--
/usr/share/groff/1.22.4/font/devascii/BI-<      24      0       0074
/usr/share/groff/1.22.4/font/devascii/BI:la     "
--
/usr/share/groff/1.22.4/font/devascii/BI->      24      0       0076
/usr/share/groff/1.22.4/font/devascii/BI:ra     "
--
/usr/share/groff/1.22.4/font/devascii/I-<       24      0       0074
/usr/share/groff/1.22.4/font/devascii/I:la      "
--
/usr/share/groff/1.22.4/font/devascii/I->       24      0       0076
/usr/share/groff/1.22.4/font/devascii/I:ra      "
--
/usr/share/groff/1.22.4/font/devascii/R-<       24      0       0074
/usr/share/groff/1.22.4/font/devascii/R:la      "
--
/usr/share/groff/1.22.4/font/devascii/R->       24      0       0076
/usr/share/groff/1.22.4/font/devascii/R:ra      "
--
/usr/share/groff/1.22.4/font/devlatin1/B-<      24      0       0074
/usr/share/groff/1.22.4/font/devlatin1/B:la     "
--
[...and so on...]

The \(la and \(ra special character escapes map to < and > respectively
for non-UTF-8 terminal devices in groff.

So, as it happens, do \(fo and \(fc.

Here's a simple reproducer you can feed to "nroff -man" or "groff -Tutf8
-man".

	.TH foo 1
	.UR bar
	.UE

Regards,
Branden

-- 
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

On 1/22/21 4:13 PM, Michael Kerrisk (man-pages) wrote:

Hi Alex,

On Fri, 22 Jan 2021 at 13:37, Alejandro Colomar (man-pages)
[off-list ref] wrote:

quoted

On 1/9/21 8:58 PM, Alejandro Colomar wrote:

quoted

$ man 7 uri 2>/dev/null \
   |sed -n '/Writing a URI/,/^$/p';
    Writing a URI
        When  written, URIs should be placed inside double quotes
        (e.g., "http://www.kernel.org"), enclosed in angle brack‐
        ets  (e.g.,  <http://lwn.net>),  or  placed  on a line by
        themselves.  A warning for those who  use  double-quotes:
        never  move  extraneous  punctuation  (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 system
        that  never  includes extraneous characters inside quota‐
        tion marks.  This latter  system,  called  the  'new'  or
        'logical'  quoting  system by "Hart's Rules" and the "Ox‐
        ford Dictionary for Writers and  Editors",  is  preferred
        practice  in Great Britain and hackers worldwide (see the
        Jargon  File's   section   on   Hacker   Writing   Style,
        ⟨http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html⟩,
        for more information).   Older
        documents  suggested inserting the prefix "URL:" just be‐
        fore the URI, but this form has never caught on.

Enclose URIs in <>.  It is especially important in this case, as
the URIs are followed by '.'.
 From "" or <>, I prefer <>, as they are less used in other
contexts, so they are more easily read as URIs.

This also fixes the extraneous space that was used to separate
the URIs from the final period.
In some cases, the period ended in a line of its own.

Also enclose them in [.UR/.UE].

Signed-off-by: Alejandro Colomar <redacted>
---

Hello Michael,

This patch is for man-pages-posix.git.
I found that the link in uri(7) is broken,
but I found that same document here:
http://www.catb.org/jargon/html/writing-style.html
I'll patch uri.7 to fix that link.

That was a very interesting read.
I got why you tend to use "xxxx (xxxx.)" and not "xxxx (xxxx).",

Sorry... I don't understand what you are referring to in the previous line.

It has happened already a few times that you corrected a patch of mine 
(or you corrected the corrections I sent to others' patches), because of 
using "... foo)." and you changed it to be "... foo.)" (see 
[off-list ref]) as an example).

quoted

quoted

the latter being _much_ more common in Spanish (and other languages)
(actually, I've never read the former in Spanish).

Hey Michael,

Ping!

I'm still very interested in knowing your thoughts about the Hacker
Writing Style from the Jargon File, and more specifically about the
so-called `new' or `logical' quoting method[1].  Especially you being
both a hacker and a writer :-).

[1]: http://www.catb.org/jargon/html/writing-style.html

So, I regard the Jargon File and HWS as no real authority on anything,
and I'm not even sure we should refer to them in a manual page. Much
of the writing there is rather polemical. But, that said...

I don't regard it as an authority either, and yes, it's unnecessarily 
polemical, but there are still some entries that have some useful 
information, like this one about the different quoting methods, IMHO.

quoted

I'll quote the most important part here so you don't need to follow the
link (but I recommend it, though):

[[
Hackers tend to use quotes as balanced delimiters like parentheses, much
to the dismay of American editors. Thus, if “Jim is going” is a phrase,
and so are “Bill runs” and “Spock groks”, then hackers generally prefer
to write: “Jim is going”, “Bill runs”, and “Spock groks”. This is
incorrect according to standard American usage (which would put the
continuation commas and the final period inside the string quotes);
however, it is counter-intuitive to hackers to mutilate literal strings
with characters that don't belong in them. Given the sorts of examples
that can come up in discussions of programming, American-style quoting
can even be grossly misleading. When communicating command lines or
small pieces of code, extra characters can be a real pain in the neck.

Consider, for example, a sentence in a vi tutorial that looks like this:

     Then delete a line from the file by typing “dd”.

Standard usage would make this

     Then delete a line from the file by typing “dd.”

but that would be very bad — because the reader would be prone to type
the string d-d-dot, and it happens that in vi(1), dot repeats the last
command accepted. The net result would be to delete two lines!

The Jargon File follows hackish usage throughout.

Interestingly, a similar style is now preferred practice in Great
Britain, though the older style (which became established for
typographical reasons having to do with the aesthetics of comma and
quotes in typeset text) is still accepted there. Hart's Rules and the
Oxford Dictionary for Writers and Editors call the hacker-like style
‘new’ or ‘logical’ quoting. This returns British English to the style
many other languages (including Spanish, French, Italian, Catalan, and
German) have been using all along.
]]

Like many programmers, I find the Logical Style, ahhh, logical. And in
a fixed-width font, the visual argument for putting periods and commas
inside the quotes (the American style) doesn't apply. The
counterargument is that in most every other aspect, man-pages follows
American conventions.

For that counterpart I'd argue an easy one: we already made some 
rational exceptions, such as s/dgment/dgement/ ;-).

I imagine that in man-pages there's a mix of both styles, since I'm
not sure if I've ever taken care about this.

Yes, there is.

So, what to do... Given that man-pages are primarily rendered to
fix-width displays, and the confusion that can sometimes occur in a
technical context if following the American style, I would not oppose
switching everything British/Logical style.

Maybe others have opinions to offer.

I strongly vote for the European quoting method, for logical reasons. 
Pun intended :-).

quoted

BTW, I should remind myself to fix the link in uri.7.

I'd be inclined to remove the URL. Mention of the Logical Style in
Hart's rules and the British style is good enough, I think.

I'm not against keeping the link, but I wouldn't oppose a removal either.

Thanks,

Michael

Thanks,

Alex

-- 
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Hi Alex,

On Fri, 22 Jan 2021 at 19:19, Alejandro Colomar (man-pages)
[off-list ref] wrote:

On 1/22/21 4:13 PM, Michael Kerrisk (man-pages) wrote:

quoted

Hi Alex,

On Fri, 22 Jan 2021 at 13:37, Alejandro Colomar (man-pages)
[off-list ref] wrote:

[...]

quoted

quoted

quoted

That was a very interesting read.
I got why you tend to use "xxxx (xxxx.)" and not "xxxx (xxxx).",

Sorry... I don't understand what you are referring to in the previous line.

It has happened already a few times that you corrected a patch of mine
(or you corrected the corrections I sent to others' patches), because of
using "... foo)." and you changed it to be "... foo.)" (see
[off-list ref]) as an example).

I don't know what the reference you cite resolves to...

quoted

quoted

quoted

the latter being _much_ more common in Spanish (and other languages)
(actually, I've never read the former in Spanish).

Hey Michael,

Ping!

I'm still very interested in knowing your thoughts about the Hacker
Writing Style from the Jargon File, and more specifically about the
so-called `new' or `logical' quoting method[1].  Especially you being
both a hacker and a writer :-).

[1]: http://www.catb.org/jargon/html/writing-style.html

So, I regard the Jargon File and HWS as no real authority on anything,
and I'm not even sure we should refer to them in a manual page. Much
of the writing there is rather polemical. But, that said...

I don't regard it as an authority either, and yes, it's unnecessarily
polemical, but there are still some entries that have some useful
information, like this one about the different quoting methods, IMHO.

[...]

quoted

Like many programmers, I find the Logical Style, ahhh, logical. And in
a fixed-width font, the visual argument for putting periods and commas
inside the quotes (the American style) doesn't apply. The
counterargument is that in most every other aspect, man-pages follows
American conventions.

For that counterpart I'd argue an easy one: we already made some
rational exceptions, such as s/dgment/dgement/ ;-).

I knew you'd do that ;-).

quoted

I imagine that in man-pages there's a mix of both styles, since I'm
not sure if I've ever taken care about this.

Yes, there is.

quoted

So, what to do... Given that man-pages are primarily rendered to
fix-width displays, and the confusion that can sometimes occur in a
technical context if following the American style, I would not oppose
switching everything British/Logical style.

Maybe others have opinions to offer.

I strongly vote for the European quoting method, for logical reasons.
Pun intended :-).

I'm okay with making the switch to Logical Style.

quoted

quoted

BTW, I should remind myself to fix the link in uri.7.

I'd be inclined to remove the URL. Mention of the Logical Style in
Hart's rules and the British style is good enough, I think.

I'm not against keeping the link, but I wouldn't oppose a removal either.

I removed it.

Thanks,

Michael