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

Hi Alex,

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

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

quoted

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

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

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

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

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

Hello Michael,

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

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

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

quoted

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

Hey Michael,

Ping!

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

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

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

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

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

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

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

Standard usage would make this

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

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

The Jargon File follows hackish usage throughout.

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

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

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

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

Maybe others have opinions to offer.

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

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

Thanks,

Michael

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