posix.py: ffix: Correctly format URIs
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
@@ -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
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
Signed-off-by Alejandro Colomar <[email protected]>---
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@@ -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/
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.
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/
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
@@ -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
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.Signed-off-by Alejandro Colomar <[email protected]>--- posix.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-)posix.py +6
-4@@ -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)
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.Signed-off-by Alejandro Colomar <[email protected]>
Thanks. Patch applied.
Cheers,
Michael
Quoted 30 lines
--- posix.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-)posix.py +6
-4@@ -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/
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.Signed-off-by Alejandro Colomar <[email protected]>
Thanks. Patch applied.
Cheers,
Michael
Quoted 30 lines
--- posix.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-)posix.py +6
-4@@ -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/
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
[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.localand/etc/groff/mdoc.localas 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.
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.localand/etc/groff/mdoc.localas 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
* 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.localand/etc/groff/mdoc.localas 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
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
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.
* 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
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
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#FrenchThanks. 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/
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
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 atgroff_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 .UERegards,
Branden
Signature · 4 lines
-- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
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].
Signed-off-by Alejandro Colomar <[email protected]>
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@@ -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/
Ping: [PATCH] posix.py: ffix: Correctly format URIs
In reply to Alejandro ColomarQuoted 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].
Signed-off-by Alejandro Colomar <[email protected]>---
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@@ -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/
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].
Signed-off-by Alejandro Colomar <[email protected]>---
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' orlogical' quoting method[1]. Especially you being both a hacker and a writer :-).
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/
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].
Signed-off-by Alejandro Colomar <[email protected]>---
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' orlogical' quoting method[1]. Especially you being both a hacker and a writer :-).
Quoted 6 lines
Quoted 1 line
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/
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' orlogical' quoting method[1]. Especially you being both a hacker and a writer :-).Quoted 6 lines
Quoted 1 line
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