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

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hi Michael, Branden,

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].

I was wondering if, instead of hardcoding <>,
it would be possible to make .UR/.UE embed those characters.
It would make the code more generic, but I don't know if it is feasible
or desirable.

Thanks,

Alex

> 
> 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).",
> the latter being _much_ more common in Spanish (and other languages)
> (actually, I've never read the former in Spanish).>
> 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/