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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Alex,

On Fri, 22 Jan 2021 at 13:37, Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> 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@gmail.com>
> > ---
> >
> > 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.

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