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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



$ 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).

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)
-- 
2.30.0




[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux