Re: [PATCH] Fix documentation AsciiDoc links for external urls

[Junio C Hamano <gitster@pobox.com>]

Roberto Tyley <roberto.tyley@gmail.com> writes:

> Turns out that putting 'link:' before the 'http' is actually superfluous
> in AsciiDoc, as there's already a predefined macro to handle it.
>
> "http, https, [etc] URLs are rendered using predefined inline macros."
> http://www.methods.co.nz/asciidoc/userguide.html#_urls
>
> "Hypertext links to files on the local file system are specified
> using the link inline macro."
> http://www.methods.co.nz/asciidoc/userguide.html#_linking_to_local_documents
>
> Despite being superfluous, the reference implementation of AsciiDoc
> tolerates the extra 'link:' and silently removes it, giving a functioning
> link in the generated HTML. However, AsciiDoctor (the Ruby implementation
> of AsciiDoc used to render the http://git-scm.com/ site) does /not/ have
> this behaviour, and so generates broken links, as can be seen here:
>
> http://git-scm.com/docs/git-cvsimport (links to cvs2git & parsecvs)
> http://git-scm.com/docs/git-filter-branch (link to The BFG)
>
> It's worth noting that after this change, the html generated by 'make html'
> in the git project is identical, and all links still work.
> ---

Sign-off?

The overall reasoning sounds good, and the patch also looks sensible.

Thanks.


>  Documentation/git-cvsimport.txt           | 4 ++--
>  Documentation/git-filter-branch.txt       | 4 ++--
>  Documentation/gitcore-tutorial.txt        | 2 +-
>  Documentation/gitcvs-migration.txt        | 2 +-
>  Documentation/gitweb.txt                  | 2 +-
>  Documentation/technical/http-protocol.txt | 4 ++--
>  6 files changed, 9 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt
> index 2df9953..260f39f 100644
> --- a/Documentation/git-cvsimport.txt
> +++ b/Documentation/git-cvsimport.txt
> @@ -21,8 +21,8 @@ DESCRIPTION
>  *WARNING:* `git cvsimport` uses cvsps version 2, which is considered
>  deprecated; it does not work with cvsps version 3 and later.  If you are
>  performing a one-shot import of a CVS repository consider using
> -link:http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or
> -link:https://github.com/BartMassey/parsecvs[parsecvs].
> +http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or
> +https://github.com/BartMassey/parsecvs[parsecvs].
>  
>  Imports a CVS repository into Git. It will either create a new
>  repository, or incrementally import into an existing one.
> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
> index 2eba627..09535f2 100644
> --- a/Documentation/git-filter-branch.txt
> +++ b/Documentation/git-filter-branch.txt
> @@ -436,7 +436,7 @@ git-filter-branch allows you to make complex shell-scripted rewrites
>  of your Git history, but you probably don't need this flexibility if
>  you're simply _removing unwanted data_ like large files or passwords.
>  For those operations you may want to consider
> -link:http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],
> +http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],
>  a JVM-based alternative to git-filter-branch, typically at least
>  10-50x faster for those use-cases, and with quite different
>  characteristics:
> @@ -455,7 +455,7 @@ characteristics:
>    _is_ possible to write filters that include their own parallellism,
>    in the scripts executed against each commit.
>  
> -* The link:http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]
> +* The http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]
>    are much more restrictive than git-filter branch, and dedicated just
>    to the tasks of removing unwanted data- e.g:
>    `--strip-blobs-bigger-than 1M`.
> diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
> index 058a352..d2d7c21 100644
> --- a/Documentation/gitcore-tutorial.txt
> +++ b/Documentation/gitcore-tutorial.txt
> @@ -1443,7 +1443,7 @@ Although Git is a truly distributed system, it is often
>  convenient to organize your project with an informal hierarchy
>  of developers. Linux kernel development is run this way. There
>  is a nice illustration (page 17, "Merges to Mainline") in
> -link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].
> +http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].
>  
>  It should be stressed that this hierarchy is purely *informal*.
>  There is nothing fundamental in Git that enforces the "chain of
> diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt
> index 5ea94cb..5f4e890 100644
> --- a/Documentation/gitcvs-migration.txt
> +++ b/Documentation/gitcvs-migration.txt
> @@ -117,7 +117,7 @@ Importing a CVS archive
>  -----------------------
>  
>  First, install version 2.1 or higher of cvsps from
> -link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make
> +http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make
>  sure it is in your path.  Then cd to a checked out CVS working directory
>  of the project you are interested in and run linkgit:git-cvsimport[1]:
>  
> diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt
> index cca14b8..cd9c895 100644
> --- a/Documentation/gitweb.txt
> +++ b/Documentation/gitweb.txt
> @@ -84,7 +84,7 @@ separator (rules for Perl's "`split(" ", $line)`").
>  
>  * Fields use modified URI encoding, defined in RFC 3986, section 2.1
>  (Percent-Encoding), or rather "Query string encoding" (see
> -link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference
> +http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference
>  being that SP (" ") can be encoded as "{plus}" (and therefore "{plus}" has to be
>  also percent-encoded).
>  +
> diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt
> index 544373b..20525d9 100644
> --- a/Documentation/technical/http-protocol.txt
> +++ b/Documentation/technical/http-protocol.txt
> @@ -500,7 +500,7 @@ TODO: Document this further.
>  References
>  ----------
>  
> -link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
> -link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
> +http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]
> +http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]
>  link:technical/pack-protocol.html
>  link:technical/protocol-capabilities.html