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@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) > -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
