Skip to contentSkip to conversation

posix.py: ffix: Correctly format URIs

PATCH Superseded Alejandro Colomar 5 participants 24 messages Jan 9, 2021 – Jan 23, 2021 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 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].

---

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(-)
posix.py +6 -4
index 55e401a..27f6207 100755
@@ -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)
Signature · 1 line
2.30.0
#1 lore raw

Hi Michael, Branden,

Quoted 27 lines · Alejandro Colomar
$ 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.

Quoted 5 lines

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

Quoted 49 lines

---

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(-)
posix.py +6 -4
index 55e401a..27f6207 100755
@@ -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)
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#2 lore raw

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.

Quoted 2 lines · Alejandro Colomar (man-pages)

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

[...]

Quoted 3 lines
Quoted 3 lines

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 5 lines
Quoted 1 line

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.

#3 lore raw

Hi Branden,

Quoted 4 lines · G. Branden Robinson

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 :)

Quoted 3 lines

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.

Quoted 61 lines
Quoted 2 lines · Alejandro Colomar (man-pages)

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

[...]

Quoted 3 lines
Quoted 3 lines

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 5 lines
Quoted 1 line

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.

Quoted 7 lines

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

Quoted 5 lines

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

Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#4 lore raw

PATCH v2 1/1 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 .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.

---
 posix.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
posix.py +6 -4
index 55e401a..60271cc 100755
@@ -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)
Signature · 1 line
2.30.0
#5 lore raw

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

Ping!

Quoted 62 lines · Alejandro Colomar
$ 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.

---
 posix.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
posix.py +6 -4
index 55e401a..60271cc 100755
@@ -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)
#6 lore raw
In reply to Alejandro Colomar

Hi Alex,

Quoted 27 lines · Alejandro Colomar
$ 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 '.'.

Quoted 5 lines

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.

Thanks. Patch applied.

Cheers,

Michael

Quoted 30 lines
---
 posix.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
posix.py +6 -4
index 55e401a..60271cc 100755
@@ -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)
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#7 lore raw
In reply to Alejandro Colomar

Hi Alex,

Quoted 27 lines · Alejandro Colomar
$ 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 '.'.

Quoted 5 lines

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.

Thanks. Patch applied.

Cheers,

Michael

Quoted 30 lines
---
 posix.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
posix.py +6 -4
index 55e401a..60271cc 100755
@@ -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)
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#8 lore raw
In reply to Alejandro Colomar (man-pages)
Quoted 2 lines · G. Branden Robinson
Quoted 1 line

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 <[email protected]>, 2021-01-10, 15:35:

Quoted 1 line

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.)

Signature · 1 line
Jakub Wilk
#9 lore raw

[redirecting to [email protected]; Reply-To set]

Hi Jakub!

Quoted 1 line · Jakub Wilk
Quoted 1 line · G. Branden Robinson

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

Quoted 5 lines
Quoted 2 lines
Quoted 2 lines

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?

Quoted 12 lines

* Alejandro Colomar <[email protected]>, 2021-01-10, 15:35:

Quoted 4 lines

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:

Quoted 6 lines

. 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.

#10 lore raw
In reply to Jakub Wilk

Hi Jakub and Branden,

Quoted 18 lines · Jakub Wilk
Quoted 3 lines · G. Branden Robinson
Quoted 2 lines

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 <[email protected]>, 2021-01-10, 15:35:

Quoted 3 lines

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:

Quoted 7 lines

.  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

#11 lore raw

* Alejandro Colomar <[email protected]>, 2021-01-21, 20:54:

Quoted 22 lines · Jakub Wilk
Quoted 11 lines
Quoted 2 lines · G. Branden Robinson
Quoted 1 line

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 <[email protected]>, 2021-01-10, 15:35:

Quoted 1 line

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.

Quoted 9 lines

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.)

Quoted 8 lines

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.

Signature · 1 line
Jakub Wilk
#12 lore raw

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

Quoted 7 lines
Quoted 2 lines

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

#13 lore raw
In reply to Jakub Wilk
Quoted 12 lines · Jakub Wilk
Quoted 12 lines

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.

Quoted 6 lines
Quoted 1 line

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.

#14 lore raw

* G. Branden Robinson <[email protected]>, 2021-01-22, 14:23:

Quoted 1 line

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

Quoted 2 lines

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

Should be lowercase "f" here.

Signature · 1 line
Jakub Wilk
#15 lore raw
Quoted 8 lines · Jakub Wilk

* G. Branden Robinson <[email protected]>, 2021-01-22, 14:23:

Quoted 4 lines

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 4 lines
Quoted 2 lines

. 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

#16 lore raw
Quoted 24 lines · G. Branden Robinson
Quoted 8 lines · Jakub Wilk

* G. Branden Robinson <[email protected]>, 2021-01-22, 14:23:

Quoted 4 lines

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 4 lines
Quoted 2 lines

. 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
Quoted 7 lines

[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

Quoted 4 lines

Regards,
Branden

Signature · 4 lines
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#17 lore raw

Hi Alex,

Quoted 11 lines · Alejandro Colomar (man-pages)
Quoted 5 lines · G. Branden Robinson

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

#18 lore raw

Hi Branden,

Quoted 22 lines · G. Branden Robinson

Hi Alex,

Quoted 11 lines · Alejandro Colomar (man-pages)
Quoted 5 lines · G. Branden Robinson

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.

Quoted 6 lines

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

Quoted 65 lines

/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

Signature · 4 lines
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#19 lore raw
In reply to Alejandro Colomar
Quoted 27 lines · Alejandro Colomar
$ 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.

Quoted 7 lines

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

Hi Michael,

I forgot to setup the email.
Please fix it.

Thanks,

Alex

Quoted 48 lines

---

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(-)
posix.py +6 -4
index 55e401a..27f6207 100755
@@ -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)
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#20 lore raw

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

In reply to Alejandro Colomar
Quoted 44 lines · Alejandro Colomar
$ 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].

---

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.

Quoted 4 lines

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

Quoted 34 lines

Regards,

Alex

 posix.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)
posix.py +6 -4
index 55e401a..27f6207 100755
@@ -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)
Signature · 3 lines
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#21 lore raw

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

Hi Alex,

Quoted 40 lines · Alejandro Colomar (man-pages)
Quoted 38 lines · Alejandro Colomar
$ 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].

---

Hello Michael,

Quoted 8 lines
Quoted 8 lines

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 5 lines
Quoted 2 lines

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

Hey Michael,

Quoted 8 lines

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...

Quoted 30 lines

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.

Quoted 9 lines

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.

Quoted 1 line

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

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#22 lore raw

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

Quoted 50 lines · Michael Kerrisk (man-pages)

Hi Alex,

Quoted 46 lines · Alejandro Colomar (man-pages)
Quoted 44 lines · Alejandro Colomar
$ 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].

---

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.

Quoted 4 lines
Quoted 2 lines
Quoted 2 lines

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 <[email protected]>) as an example).

Quoted 13 lines
Quoted 13 lines
Quoted 3 lines

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 :-).

Quoted 6 lines
Quoted 1 line

[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 40 lines
Quoted 30 lines

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.

Quoted 9 lines

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

Quoted 5 lines

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/ ;-).

Quoted 4 lines

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 6 lines

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 6 lines
Quoted 2 lines

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.

Quoted 4 lines

Thanks,

Michael

Thanks,

Alex

Signature · 4 lines
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
#23 lore raw

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

Hi Alex,

Quoted 6 lines · Alejandro Colomar (man-pages)
Quoted 4 lines · Michael Kerrisk (man-pages)

Hi Alex,

On Fri, 22 Jan 2021 at 13:37, Alejandro Colomar (man-pages) <[email protected]> wrote:

[...]

Quoted 9 lines
Quoted 4 lines
Quoted 2 lines
Quoted 2 lines

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 <[email protected]>) as an example).

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

Quoted 22 lines
Quoted 12 lines
Quoted 12 lines
Quoted 2 lines

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 :-).

Quoted 6 lines
Quoted 1 line

[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 8 lines
Quoted 5 lines

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 11 lines
Quoted 3 lines

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 5 lines

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.

Quoted 4 lines
Quoted 1 line

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 6 lines
Quoted 4 lines
Quoted 1 line

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