From: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
To: mtk.manpages@gmail.com
Cc: Alejandro Colomar <colomar.6.4.3@gmail.com>,
linux-man <linux-man@vger.kernel.org>,
"G . Branden Robinson" <g.branden.robinson@gmail.com>,
Jakub Wilk <jwilk@jwilk.net>
Subject: Re: Ping: [PATCH] posix.py: ffix: Correctly format URIs
Date: Fri, 22 Jan 2021 19:19:14 +0100 [thread overview]
Message-ID: <bdc24ecd-bb92-5d9a-4461-f3d3640f6457@gmail.com> (raw)
In-Reply-To: <CAKgNAkhHLw2gwrnquOq8nbFSoydkSyoWivgeHrh2CH4QY3PdDg@mail.gmail.com>
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@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.
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@gmail.com>) 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/
next prev parent reply other threads:[~2021-01-22 19:17 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-01-09 19:58 [PATCH] posix.py: ffix: Correctly format URIs Alejandro Colomar
2021-01-09 21:07 ` Alejandro Colomar (man-pages)
2021-01-10 6:50 ` G. Branden Robinson
2021-01-10 14:35 ` Alejandro Colomar (man-pages)
2021-01-10 14:57 ` [PATCH v2] " Alejandro Colomar
2021-01-19 19:59 ` Ping: " Alejandro Colomar (man-pages)
2021-01-20 8:50 ` Michael Kerrisk (man-pages)
2021-01-20 8:55 ` Michael Kerrisk (man-pages)
2021-01-12 20:51 ` [PATCH] " Jakub Wilk
2021-01-14 7:11 ` G. Branden Robinson
2021-01-21 19:54 ` Alejandro Colomar (man-pages)
2021-01-21 20:14 ` Jakub Wilk
2021-01-21 20:19 ` Alejandro Colomar
2021-01-22 3:23 ` G. Branden Robinson
2021-01-22 9:35 ` Jakub Wilk
2021-01-22 10:07 ` G. Branden Robinson
2021-01-22 10:50 ` Alejandro Colomar (man-pages)
2021-01-22 14:51 ` G. Branden Robinson
2021-01-22 17:27 ` Alejandro Colomar (man-pages)
2021-01-09 22:09 ` Alejandro Colomar (man-pages)
2021-01-22 12:37 ` Ping: " Alejandro Colomar (man-pages)
2021-01-22 15:13 ` Michael Kerrisk (man-pages)
2021-01-22 18:19 ` Alejandro Colomar (man-pages) [this message]
2021-01-23 9:15 ` Michael Kerrisk (man-pages)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=bdc24ecd-bb92-5d9a-4461-f3d3640f6457@gmail.com \
--to=alx.manpages@gmail.com \
--cc=colomar.6.4.3@gmail.com \
--cc=g.branden.robinson@gmail.com \
--cc=jwilk@jwilk.net \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.