Re: Correctly formatting URIs: slash - Alejandro Colomar (man-pages)

From: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
To: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>,
	Jakub Wilk <jwilk@jwilk.net>,
	linux-man <linux-man@vger.kernel.org>
Subject: Re: Correctly formatting URIs: slash
Date: Fri, 22 Jan 2021 18:32:30 +0100	[thread overview]
Message-ID: <ee39d6f4-4279-a8cc-63e7-f2f583d40659@gmail.com> (raw)
In-Reply-To: <20210122151204.tf7ygq324cf4zwjq@localhost.localdomain>

Hi Branden and Michael,

On 1/22/21 4:12 PM, G. Branden Robinson wrote:
> Hi Alex!
> 
> At 2021-01-22T14:00:33+0100, Alejandro Colomar (man-pages) wrote:
>> Why do some pages use \:/ for the slash in the path part of a URL, but
>> some others don't, and just use /?
> 
> Laziness or ignorance of how URLs get typeset and what the \: escape is
> for.
> 
> URLs are typeset with hyphenation disabled.  That means that the line
> preceding a URL can
> be broken early in a very ugly way, somewhat like this sentence.
> 
> Slashes in URLs turn out to be pretty good places to break a line if it
> must be.  If you wanted a hyphen to appear at the break point, you'd use
> the "hyphenation character", an escape that goes way back to 1970s AT&T
> troff: \%.  However, as with URLs,sometimes you want a hyphenless break
> point, and that's what groff's \: is.  Heirloom Doctools troff supports
> \: as well.  mandoc 1.14.1 does not (it refuses to break URLs at all, at
> least for man(7) documents; I didn't check its mdoc(7) support).
> 
>> Moreover, why do the former use \:/ only for the path, but not for the
>> protocol?
> 
> I think it is because people feel like postponing a break by 7 more
> characters to get the first part after the schema adjacent to it is not
> too high a price to pay.
> 
> There's no deep reason why you couldn't do:
> 
> .UR http\:://www\:.w3\:.org\:/CGI
> Common Gateway Interface
> .UE
> 
> for instance.
> 
> House style for the groff man pages is to place hyphenless break points
> _before_ periods and _after_ slashes in pathnames and URLs.  The former
> point is one I'd recommend firmly to others, because it helps keep the
> reader from confusing a line-broken pathname or URL as ending a
> sentence (prematurely).  The latter convention is more arbitrary; plenty
> of perfectly valid URLs (and pathnames) exist with or without trailing
> slashes, so one can't infer the end of such an object from the presence
> or absence of a slash at the end of a line of text.

Fair enough!  I'll patch URLs to follow those conventions.

Thanks,

Alex

> 
> Regards,
> Branden
> 

-- 
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/