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).", > 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 > > Regards, > > Alex > > posix.py | 10 ++++++---- > 1 file changed, 6 insertions(+), 4 deletions(-) > > diff --git a/posix.py b/posix.py > index 55e401a..27f6207 100755 > --- a/posix.py > +++ b/posix.py > @@ -337,14 +337,16 @@ for file in sys.argv[2:]: > "Electrical and Electronics Engineers, Inc and The Open Group.\n" > "In the event of any discrepancy between this version and the original IEEE and\n" > "The Open Group Standard, the original IEEE and The Open Group Standard\n" > - "is the referee document. The original Standard can be obtained online at\n" > - "http://www.opengroup.org/unix/online.html .\n" > + "is the referee document. The original Standard can be obtained online at\n" > + ".UR <http://www.opengroup.org/unix/online.html>\n" > + ".UE .\n" > ".PP\n" > "Any typographical or formatting errors that appear\n" > "in this page are most likely\n" > "to have been introduced during the conversion of the source files to\n" > - "man page format. To report such errors, see\n" > - "https://www.kernel.org/doc/man-pages/reporting_bugs.html .\n" > + "man page format. To report such errors, see\n" > + ".UR <https://www.kernel.org/doc/man-pages/reporting_bugs.html>\n" > + ".UE .\n" > ) > > text = "".join(lines) > -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
