On 1/22/21 4:13 PM, Michael Kerrisk (man-pages) wrote:
Hi Alex,
On Fri, 22 Jan 2021 at 13:37, Alejandro Colomar (man-pages)
<alx.manpages@xxxxxxxxx> wrote:
On 1/9/21 8:58 PM, Alejandro Colomar wrote:
$ man 7 uri 2>/dev/null \
|sed -n '/Writing a URI/,/^$/p';
Writing a URI
When written, URIs should be placed inside double quotes
(e.g., "http://www.kernel.org";), enclosed in angle brack‐
ets (e.g., <http://lwn.net>), or placed on a line by
themselves. A warning for those who use double-quotes:
never move extraneous punctuation (such as the period
ending a sentence or the comma in a list) inside a URI,
since this will change the value of the URI. Instead,
use angle brackets instead, or switch to a quoting system
that never includes extraneous characters inside quota‐
tion marks. This latter system, called the 'new' or
'logical' quoting system by "Hart's Rules" and the "Ox‐
ford Dictionary for Writers and Editors", is preferred
practice in Great Britain and hackers worldwide (see the
Jargon File's section on Hacker Writing Style,
⟨http://www.fwi.uva.nl/~mes/jargon/h/HackerWritingStyle.html⟩;,
for more information). Older
documents suggested inserting the prefix "URL:" just be‐
fore the URI, but this form has never caught on.
Enclose URIs in <>. It is especially important in this case, as
the URIs are followed by '.'.
From "" or <>, I prefer <>, as they are less used in other
contexts, so they are more easily read as URIs.
This also fixes the extraneous space that was used to separate
the URIs from the final period.
In some cases, the period ended in a line of its own.
Also enclose them in [.UR/.UE].
Signed-off-by: Alejandro Colomar <colomar.6.4.3@xxxxxxxxx>
---
Hello Michael,
This patch is for man-pages-posix.git.
I found that the link in uri(7) is broken,
but I found that same document here:
http://www.catb.org/jargon/html/writing-style.html
I'll patch uri.7 to fix that link.
That was a very interesting read.
I got why you tend to use "xxxx (xxxx.)" and not "xxxx (xxxx).",
Sorry... I don't understand what you are referring to in the previous line.
It has happened already a few times that you corrected a patch of mine
(or you corrected the corrections I sent to others' patches), because of
using "... foo)." and you changed it to be "... foo.)" (see
<c73ca93d-b723-adc1-0603-4c7f9ecc458e@xxxxxxxxx>) as an example).
the latter being _much_ more common in Spanish (and other languages)
(actually, I've never read the former in Spanish).
Hey Michael,
Ping!
I'm still very interested in knowing your thoughts about the Hacker
Writing Style from the Jargon File, and more specifically about the
so-called `new' or `logical' quoting method[1]. Especially you being
both a hacker and a writer :-).
[1]: http://www.catb.org/jargon/html/writing-style.html
So, I regard the Jargon File and HWS as no real authority on anything,
and I'm not even sure we should refer to them in a manual page. Much
of the writing there is rather polemical. But, that said...
I don't regard it as an authority either, and yes, it's unnecessarily
polemical, but there are still some entries that have some useful
information, like this one about the different quoting methods, IMHO.
I'll quote the most important part here so you don't need to follow the
link (but I recommend it, though):
[[
Hackers tend to use quotes as balanced delimiters like parentheses, much
to the dismay of American editors. Thus, if “Jim is going” is a phrase,
and so are “Bill runs” and “Spock groks”, then hackers generally prefer
to write: “Jim is going”, “Bill runs”, and “Spock groks”. This is
incorrect according to standard American usage (which would put the
continuation commas and the final period inside the string quotes);
however, it is counter-intuitive to hackers to mutilate literal strings
with characters that don't belong in them. Given the sorts of examples
that can come up in discussions of programming, American-style quoting
can even be grossly misleading. When communicating command lines or
small pieces of code, extra characters can be a real pain in the neck.
Consider, for example, a sentence in a vi tutorial that looks like this:
Then delete a line from the file by typing “dd”.
Standard usage would make this
Then delete a line from the file by typing “dd.”
but that would be very bad — because the reader would be prone to type
the string d-d-dot, and it happens that in vi(1), dot repeats the last
command accepted. The net result would be to delete two lines!
The Jargon File follows hackish usage throughout.
Interestingly, a similar style is now preferred practice in Great
Britain, though the older style (which became established for
typographical reasons having to do with the aesthetics of comma and
quotes in typeset text) is still accepted there. Hart's Rules and the
Oxford Dictionary for Writers and Editors call the hacker-like style
‘new’ or ‘logical’ quoting. This returns British English to the style
many other languages (including Spanish, French, Italian, Catalan, and
German) have been using all along.
]]
Like many programmers, I find the Logical Style, ahhh, logical. And in
a fixed-width font, the visual argument for putting periods and commas
inside the quotes (the American style) doesn't apply. The
counterargument is that in most every other aspect, man-pages follows
American conventions.
For that counterpart I'd argue an easy one: we already made some
rational exceptions, such as s/dgment/dgement/ ;-).
I imagine that in man-pages there's a mix of both styles, since I'm
not sure if I've ever taken care about this.
Yes, there is.
So, what to do... Given that man-pages are primarily rendered to
fix-width displays, and the confusion that can sometimes occur in a
technical context if following the American style, I would not oppose
switching everything British/Logical style.
Maybe others have opinions to offer.
I strongly vote for the European quoting method, for logical reasons.
Pun intended :-).
BTW, I should remind myself to fix the link in uri.7.
I'd be inclined to remove the URL. Mention of the Logical Style in
Hart's rules and the British style is good enough, I think.
I'm not against keeping the link, but I wouldn't oppose a removal either.
Thanks,
Michael
Thanks,
Alex
--
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
