[PATCH] README: create HTTP/HTTPS links from URLs in Markdown

[PATCH] README: create HTTP/HTTPS links from URLs in Markdown

[Eric Wong]

Markdown supports automatic links by surrounding URLs with
angle brackets, as documented in
<https://daringfireball.net/projects/markdown/syntax#autolink>

While we're at it, update URLs to avoid redirecting clients for
git-scm.com (by using HTTPS) and public-inbox.org (by adding a
trailing slash).

Signed-off-by: Eric Wong <e@80x24.org>
---
 I was going to cite some style manuals (MLA, APA, etc),
 but it seems current versions do not favor angle brackets.
 However, this remains consistent with the recommendations in
 RFC 2369 <https://ietf.org/rfc/rfc2369.txt> for mail headers.

 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index c0cd5580e..f17af66a9 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ Torvalds with help of a group of hackers around the net.
 
 Please read the file [INSTALL][] for installation instructions.
 
-Many Git online resources are accessible from http://git-scm.com/
+Many Git online resources are accessible from <https://git-scm.com/>
 including full documentation and Git related tools.
 
 See [Documentation/gittutorial.txt][] to get started, then see
@@ -33,8 +33,8 @@ requests, comments and patches to git@vger.kernel.org (read
 [Documentation/SubmittingPatches][] for instructions on patch submission).
 To subscribe to the list, send an email with just "subscribe git" in
 the body to majordomo@vger.kernel.org. The mailing list archives are
-available at https://public-inbox.org/git,
-http://marc.info/?l=git and other archival sites.
+available at <https://public-inbox.org/git/>,
+<http://marc.info/?l=git> and other archival sites.
 
 The maintainer frequently sends the "What's cooking" reports that
 list the current status of various development topics to the mailing
-- 
EW

Re: [PATCH] README: create HTTP/HTTPS links from URLs in Markdown

[Jeff King]

On Wed, Mar 01, 2017 at 10:22:04PM +0000, Eric Wong wrote:

> Markdown supports automatic links by surrounding URLs with
> angle brackets, as documented in
> <https://daringfireball.net/projects/markdown/syntax#autolink>

One of the joys of markdown is that there are so many variants. A lot of
them (including GitHub-flavored markdown) will linkify URLs even when
they're not inside angle brackets.

So I don't mind this patch, but I'm curious what's rendering the
markdown you're seeing. I'd think online that one would either come
across the raw text, or the GFM from https://github.com/git/git.

-Peff

Re: [PATCH] README: create HTTP/HTTPS links from URLs in Markdown

[Eric Wong]

Jeff King <peff@peff.net> wrote:
> On Wed, Mar 01, 2017 at 10:22:04PM +0000, Eric Wong wrote:
> 
> > Markdown supports automatic links by surrounding URLs with
> > angle brackets, as documented in
> > <https://daringfireball.net/projects/markdown/syntax#autolink>
> 
> One of the joys of markdown is that there are so many variants. A lot of
> them (including GitHub-flavored markdown) will linkify URLs even when
> they're not inside angle brackets.
> 
> So I don't mind this patch, but I'm curious what's rendering the
> markdown you're seeing. I'd think online that one would either come
> across the raw text, or the GFM from https://github.com/git/git.

I was using Gruber's reference implementation from Debian stable
(1.0.1-7).

Also, pandoc (also Debian stable 1.12.4.2~dfsg-1+b14) seems to
require angle brackets by default.  pandoc also supports the
"-f markdown_github" option where it seems to behave like GFM.

But yeah, I much prefer the unambiguity of angle brackets,
especially when URLs are followed immediately but punctuation
such as ',' or '.'.

Re: [PATCH] README: create HTTP/HTTPS links from URLs in Markdown

[Jeff King]

On Thu, Mar 02, 2017 at 07:34:21AM +0000, Eric Wong wrote:

> Jeff King <peff@peff.net> wrote:
> > On Wed, Mar 01, 2017 at 10:22:04PM +0000, Eric Wong wrote:
> > 
> > > Markdown supports automatic links by surrounding URLs with
> > > angle brackets, as documented in
> > > <https://daringfireball.net/projects/markdown/syntax#autolink>
> > 
> > One of the joys of markdown is that there are so many variants. A lot of
> > them (including GitHub-flavored markdown) will linkify URLs even when
> > they're not inside angle brackets.
> > 
> > So I don't mind this patch, but I'm curious what's rendering the
> > markdown you're seeing. I'd think online that one would either come
> > across the raw text, or the GFM from https://github.com/git/git.
> 
> I was using Gruber's reference implementation from Debian stable
> (1.0.1-7).

OK. I guess my question more was "why are you doing that?". I'd expect
people to find the GFM rendering on GitHub, or just look at the text via
"less".

But it's not really my business why you would want to do it. :) It's
reasonable for us to cater to the common subset of renderers.

-Peff

Re: [PATCH] README: create HTTP/HTTPS links from URLs in Markdown

[Eric Wong]

Jeff King <peff@peff.net> wrote:
> On Thu, Mar 02, 2017 at 07:34:21AM +0000, Eric Wong wrote:
> > Jeff King <peff@peff.net> wrote:
> > > On Wed, Mar 01, 2017 at 10:22:04PM +0000, Eric Wong wrote:
> > > 
> > > > Markdown supports automatic links by surrounding URLs with
> > > > angle brackets, as documented in
> > > > <https://daringfireball.net/projects/markdown/syntax#autolink>
> > > 
> > > One of the joys of markdown is that there are so many variants. A lot of
> > > them (including GitHub-flavored markdown) will linkify URLs even when
> > > they're not inside angle brackets.
> > > 
> > > So I don't mind this patch, but I'm curious what's rendering the
> > > markdown you're seeing. I'd think online that one would either come
> > > across the raw text, or the GFM from https://github.com/git/git.
> > 
> > I was using Gruber's reference implementation from Debian stable
> > (1.0.1-7).
> 
> OK. I guess my question more was "why are you doing that?". I'd expect
> people to find the GFM rendering on GitHub, or just look at the text via
> "less".

Actually, I was initially seeing the lack of trailing slash
causing unnecessary 301 redirects on public-inbox.org.

So, I added the trailing slash and ran "markdown <README.md"
to check my work.

Then, I realized links weren't generated at all without angle
brackets.  So down the rabbit hole I went to read Gruber's syntax
document and linkifying the rest for compatibility with Gruber's
implementation.

> But it's not really my business why you would want to do it. :) It's
> reasonable for us to cater to the common subset of renderers.

:)

I figure somebody unfamiliar with Markdown editing README.md is
likely to run the original implementation locally to check their
work, as I did.


(hmm... and vger is unusually slow this week)