{"thread":{"id":"35882","subject":"[PATCH] Fix documentation AsciiDoc links for external urls","startedAt":"2014-02-15T14:39:37Z","lastAt":"2014-02-18T21:42:22Z","messageCount":3,"participants":["Roberto Tyley","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"234859","messageId":"1392475177-31358-1-git-send-email-roberto.tyley@gmail.com","threadId":"35882","inReplyTo":null,"subject":"[PATCH] Fix documentation AsciiDoc links for external urls","fromName":"Roberto Tyley","fromEmail":"roberto.tyley@gmail.com","sentAt":"2014-02-15T14:39:37Z","receivedAt":"2014-02-15T14:39:37Z","isPatch":true,"sender":{"key":"roberto.tyley@gmail.com","avatar":"https://avatars.githubusercontent.com/u/52038?v=4"},"body":"Turns out that putting 'link:' before the 'http' is actually superfluous\nin AsciiDoc, as there's already a predefined macro to handle it.\n\n\"http, https, [etc] URLs are rendered using predefined inline macros.\"\nhttp://www.methods.co.nz/asciidoc/userguide.html#_urls\n\n\"Hypertext links to files on the local file system are specified\nusing the link inline macro.\"\nhttp://www.methods.co.nz/asciidoc/userguide.html#_linking_to_local_documents\n\nDespite being superfluous, the reference implementation of AsciiDoc\ntolerates the extra 'link:' and silently removes it, giving a functioning\nlink in the generated HTML. However, AsciiDoctor (the Ruby implementation\nof AsciiDoc used to render the http://git-scm.com/ site) does /not/ have\nthis behaviour, and so generates broken links, as can be seen here:\n\nhttp://git-scm.com/docs/git-cvsimport (links to cvs2git & parsecvs)\nhttp://git-scm.com/docs/git-filter-branch (link to The BFG)\n\nIt's worth noting that after this change, the html generated by 'make html'\nin the git project is identical, and all links still work.\n---\n Documentation/git-cvsimport.txt           | 4 ++--\n Documentation/git-filter-branch.txt       | 4 ++--\n Documentation/gitcore-tutorial.txt        | 2 +-\n Documentation/gitcvs-migration.txt        | 2 +-\n Documentation/gitweb.txt                  | 2 +-\n Documentation/technical/http-protocol.txt | 4 ++--\n 6 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt\nindex 2df9953..260f39f 100644\n--- a/Documentation/git-cvsimport.txt\n+++ b/Documentation/git-cvsimport.txt\n@@ -21,8 +21,8 @@ DESCRIPTION\n *WARNING:* `git cvsimport` uses cvsps version 2, which is considered\n deprecated; it does not work with cvsps version 3 and later.  If you are\n performing a one-shot import of a CVS repository consider using\n-link:http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or\n-link:https://github.com/BartMassey/parsecvs[parsecvs].\n+http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or\n+https://github.com/BartMassey/parsecvs[parsecvs].\n \n Imports a CVS repository into Git. It will either create a new\n repository, or incrementally import into an existing one.\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex 2eba627..09535f2 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -436,7 +436,7 @@ git-filter-branch allows you to make complex shell-scripted rewrites\n of your Git history, but you probably don't need this flexibility if\n you're simply _removing unwanted data_ like large files or passwords.\n For those operations you may want to consider\n-link:http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],\n+http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],\n a JVM-based alternative to git-filter-branch, typically at least\n 10-50x faster for those use-cases, and with quite different\n characteristics:\n@@ -455,7 +455,7 @@ characteristics:\n   _is_ possible to write filters that include their own parallellism,\n   in the scripts executed against each commit.\n \n-* The link:http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]\n+* The http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]\n   are much more restrictive than git-filter branch, and dedicated just\n   to the tasks of removing unwanted data- e.g:\n   `--strip-blobs-bigger-than 1M`.\ndiff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\nindex 058a352..d2d7c21 100644\n--- a/Documentation/gitcore-tutorial.txt\n+++ b/Documentation/gitcore-tutorial.txt\n@@ -1443,7 +1443,7 @@ Although Git is a truly distributed system, it is often\n convenient to organize your project with an informal hierarchy\n of developers. Linux kernel development is run this way. There\n is a nice illustration (page 17, \"Merges to Mainline\") in\n-link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].\n+http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].\n \n It should be stressed that this hierarchy is purely *informal*.\n There is nothing fundamental in Git that enforces the \"chain of\ndiff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt\nindex 5ea94cb..5f4e890 100644\n--- a/Documentation/gitcvs-migration.txt\n+++ b/Documentation/gitcvs-migration.txt\n@@ -117,7 +117,7 @@ Importing a CVS archive\n -----------------------\n \n First, install version 2.1 or higher of cvsps from\n-link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make\n+http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make\n sure it is in your path.  Then cd to a checked out CVS working directory\n of the project you are interested in and run linkgit:git-cvsimport[1]:\n \ndiff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt\nindex cca14b8..cd9c895 100644\n--- a/Documentation/gitweb.txt\n+++ b/Documentation/gitweb.txt\n@@ -84,7 +84,7 @@ separator (rules for Perl's \"`split(\" \", $line)`\").\n \n * Fields use modified URI encoding, defined in RFC 3986, section 2.1\n (Percent-Encoding), or rather \"Query string encoding\" (see\n-link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference\n+http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference\n being that SP (\" \") can be encoded as \"{plus}\" (and therefore \"{plus}\" has to be\n also percent-encoded).\n +\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex 544373b..20525d9 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -500,7 +500,7 @@ TODO: Document this further.\n References\n ----------\n \n-link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n-link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n+http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n+http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n link:technical/pack-protocol.html\n link:technical/protocol-capabilities.html\n-- \n1.8.3.2\n"},{"id":"235014","messageId":"xmqqd2ikdvi4.fsf@gitster.dls.corp.google.com","threadId":"35882","inReplyTo":"1392475177-31358-1-git-send-email-roberto.tyley@gmail.com","subject":"Re: [PATCH] Fix documentation AsciiDoc links for external urls","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-02-18T20:19:15Z","receivedAt":"2014-02-18T20:19:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Roberto Tyley <roberto.tyley@gmail.com> writes:\n\n> Turns out that putting 'link:' before the 'http' is actually superfluous\n> in AsciiDoc, as there's already a predefined macro to handle it.\n>\n> \"http, https, [etc] URLs are rendered using predefined inline macros.\"\n> http://www.methods.co.nz/asciidoc/userguide.html#_urls\n>\n> \"Hypertext links to files on the local file system are specified\n> using the link inline macro.\"\n> http://www.methods.co.nz/asciidoc/userguide.html#_linking_to_local_documents\n>\n> Despite being superfluous, the reference implementation of AsciiDoc\n> tolerates the extra 'link:' and silently removes it, giving a functioning\n> link in the generated HTML. However, AsciiDoctor (the Ruby implementation\n> of AsciiDoc used to render the http://git-scm.com/ site) does /not/ have\n> this behaviour, and so generates broken links, as can be seen here:\n>\n> http://git-scm.com/docs/git-cvsimport (links to cvs2git & parsecvs)\n> http://git-scm.com/docs/git-filter-branch (link to The BFG)\n>\n> It's worth noting that after this change, the html generated by 'make html'\n> in the git project is identical, and all links still work.\n> ---\n\nSign-off?\n\nThe overall reasoning sounds good, and the patch also looks sensible.\n\nThanks.\n\n\n>  Documentation/git-cvsimport.txt           | 4 ++--\n>  Documentation/git-filter-branch.txt       | 4 ++--\n>  Documentation/gitcore-tutorial.txt        | 2 +-\n>  Documentation/gitcvs-migration.txt        | 2 +-\n>  Documentation/gitweb.txt                  | 2 +-\n>  Documentation/technical/http-protocol.txt | 4 ++--\n>  6 files changed, 9 insertions(+), 9 deletions(-)\n>\n> diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt\n> index 2df9953..260f39f 100644\n> --- a/Documentation/git-cvsimport.txt\n> +++ b/Documentation/git-cvsimport.txt\n> @@ -21,8 +21,8 @@ DESCRIPTION\n>  *WARNING:* `git cvsimport` uses cvsps version 2, which is considered\n>  deprecated; it does not work with cvsps version 3 and later.  If you are\n>  performing a one-shot import of a CVS repository consider using\n> -link:http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or\n> -link:https://github.com/BartMassey/parsecvs[parsecvs].\n> +http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or\n> +https://github.com/BartMassey/parsecvs[parsecvs].\n>  \n>  Imports a CVS repository into Git. It will either create a new\n>  repository, or incrementally import into an existing one.\n> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\n> index 2eba627..09535f2 100644\n> --- a/Documentation/git-filter-branch.txt\n> +++ b/Documentation/git-filter-branch.txt\n> @@ -436,7 +436,7 @@ git-filter-branch allows you to make complex shell-scripted rewrites\n>  of your Git history, but you probably don't need this flexibility if\n>  you're simply _removing unwanted data_ like large files or passwords.\n>  For those operations you may want to consider\n> -link:http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],\n> +http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],\n>  a JVM-based alternative to git-filter-branch, typically at least\n>  10-50x faster for those use-cases, and with quite different\n>  characteristics:\n> @@ -455,7 +455,7 @@ characteristics:\n>    _is_ possible to write filters that include their own parallellism,\n>    in the scripts executed against each commit.\n>  \n> -* The link:http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]\n> +* The http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]\n>    are much more restrictive than git-filter branch, and dedicated just\n>    to the tasks of removing unwanted data- e.g:\n>    `--strip-blobs-bigger-than 1M`.\n> diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\n> index 058a352..d2d7c21 100644\n> --- a/Documentation/gitcore-tutorial.txt\n> +++ b/Documentation/gitcore-tutorial.txt\n> @@ -1443,7 +1443,7 @@ Although Git is a truly distributed system, it is often\n>  convenient to organize your project with an informal hierarchy\n>  of developers. Linux kernel development is run this way. There\n>  is a nice illustration (page 17, \"Merges to Mainline\") in\n> -link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].\n> +http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].\n>  \n>  It should be stressed that this hierarchy is purely *informal*.\n>  There is nothing fundamental in Git that enforces the \"chain of\n> diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt\n> index 5ea94cb..5f4e890 100644\n> --- a/Documentation/gitcvs-migration.txt\n> +++ b/Documentation/gitcvs-migration.txt\n> @@ -117,7 +117,7 @@ Importing a CVS archive\n>  -----------------------\n>  \n>  First, install version 2.1 or higher of cvsps from\n> -link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make\n> +http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make\n>  sure it is in your path.  Then cd to a checked out CVS working directory\n>  of the project you are interested in and run linkgit:git-cvsimport[1]:\n>  \n> diff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt\n> index cca14b8..cd9c895 100644\n> --- a/Documentation/gitweb.txt\n> +++ b/Documentation/gitweb.txt\n> @@ -84,7 +84,7 @@ separator (rules for Perl's \"`split(\" \", $line)`\").\n>  \n>  * Fields use modified URI encoding, defined in RFC 3986, section 2.1\n>  (Percent-Encoding), or rather \"Query string encoding\" (see\n> -link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference\n> +http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference\n>  being that SP (\" \") can be encoded as \"{plus}\" (and therefore \"{plus}\" has to be\n>  also percent-encoded).\n>  +\n> diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\n> index 544373b..20525d9 100644\n> --- a/Documentation/technical/http-protocol.txt\n> +++ b/Documentation/technical/http-protocol.txt\n> @@ -500,7 +500,7 @@ TODO: Document this further.\n>  References\n>  ----------\n>  \n> -link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n> -link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n> +http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n> +http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n>  link:technical/pack-protocol.html\n>  link:technical/protocol-capabilities.html\n"},{"id":"235025","messageId":"1392759742-2772-1-git-send-email-roberto.tyley@gmail.com","threadId":"35882","inReplyTo":"xmqqd2ikdvi4.fsf@gitster.dls.corp.google.com","subject":"[PATCH] Fix documentation AsciiDoc links for external urls","fromName":"Roberto Tyley","fromEmail":"roberto.tyley@gmail.com","sentAt":"2014-02-18T21:42:22Z","receivedAt":"2014-02-18T21:42:22Z","isPatch":true,"sender":{"key":"roberto.tyley@gmail.com","avatar":"https://avatars.githubusercontent.com/u/52038?v=4"},"body":"Turns out that putting 'link:' before the 'http' is actually superfluous\nin AsciiDoc, as there's already a predefined macro to handle it.\n\n\"http, https, [etc] URLs are rendered using predefined inline macros.\"\nhttp://www.methods.co.nz/asciidoc/userguide.html#_urls\n\n\"Hypertext links to files on the local file system are specified\nusing the link inline macro.\"\nhttp://www.methods.co.nz/asciidoc/userguide.html#_linking_to_local_documents\n\nDespite being superfluous, the reference implementation of AsciiDoc\ntolerates the extra 'link:' and silently removes it, giving a functioning\nlink in the generated HTML. However, AsciiDoctor (the Ruby implementation\nof AsciiDoc used to render the http://git-scm.com/ site) does /not/ have\nthis behaviour, and so generates broken links, as can be seen here:\n\nhttp://git-scm.com/docs/git-cvsimport (links to cvs2git & parsecvs)\nhttp://git-scm.com/docs/git-filter-branch (link to The BFG)\n\nIt's worth noting that after this change, the html generated by 'make html'\nin the git project is identical, and all links still work.\n\nSigned-off-by: Roberto Tyley <roberto.tyley@gmail.com>\n---\n Documentation/git-cvsimport.txt           | 4 ++--\n Documentation/git-filter-branch.txt       | 4 ++--\n Documentation/gitcore-tutorial.txt        | 2 +-\n Documentation/gitcvs-migration.txt        | 2 +-\n Documentation/gitweb.txt                  | 2 +-\n Documentation/technical/http-protocol.txt | 4 ++--\n 6 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt\nindex 2df9953..260f39f 100644\n--- a/Documentation/git-cvsimport.txt\n+++ b/Documentation/git-cvsimport.txt\n@@ -21,8 +21,8 @@ DESCRIPTION\n *WARNING:* `git cvsimport` uses cvsps version 2, which is considered\n deprecated; it does not work with cvsps version 3 and later.  If you are\n performing a one-shot import of a CVS repository consider using\n-link:http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or\n-link:https://github.com/BartMassey/parsecvs[parsecvs].\n+http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or\n+https://github.com/BartMassey/parsecvs[parsecvs].\n \n Imports a CVS repository into Git. It will either create a new\n repository, or incrementally import into an existing one.\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex 2eba627..09535f2 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -436,7 +436,7 @@ git-filter-branch allows you to make complex shell-scripted rewrites\n of your Git history, but you probably don't need this flexibility if\n you're simply _removing unwanted data_ like large files or passwords.\n For those operations you may want to consider\n-link:http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],\n+http://rtyley.github.io/bfg-repo-cleaner/[The BFG Repo-Cleaner],\n a JVM-based alternative to git-filter-branch, typically at least\n 10-50x faster for those use-cases, and with quite different\n characteristics:\n@@ -455,7 +455,7 @@ characteristics:\n   _is_ possible to write filters that include their own parallellism,\n   in the scripts executed against each commit.\n \n-* The link:http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]\n+* The http://rtyley.github.io/bfg-repo-cleaner/#examples[command options]\n   are much more restrictive than git-filter branch, and dedicated just\n   to the tasks of removing unwanted data- e.g:\n   `--strip-blobs-bigger-than 1M`.\ndiff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\nindex 058a352..d2d7c21 100644\n--- a/Documentation/gitcore-tutorial.txt\n+++ b/Documentation/gitcore-tutorial.txt\n@@ -1443,7 +1443,7 @@ Although Git is a truly distributed system, it is often\n convenient to organize your project with an informal hierarchy\n of developers. Linux kernel development is run this way. There\n is a nice illustration (page 17, \"Merges to Mainline\") in\n-link:http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].\n+http://www.xenotime.net/linux/mentor/linux-mentoring-2006.pdf[Randy Dunlap's presentation].\n \n It should be stressed that this hierarchy is purely *informal*.\n There is nothing fundamental in Git that enforces the \"chain of\ndiff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt\nindex 5ea94cb..5f4e890 100644\n--- a/Documentation/gitcvs-migration.txt\n+++ b/Documentation/gitcvs-migration.txt\n@@ -117,7 +117,7 @@ Importing a CVS archive\n -----------------------\n \n First, install version 2.1 or higher of cvsps from\n-link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make\n+http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make\n sure it is in your path.  Then cd to a checked out CVS working directory\n of the project you are interested in and run linkgit:git-cvsimport[1]:\n \ndiff --git a/Documentation/gitweb.txt b/Documentation/gitweb.txt\nindex cca14b8..cd9c895 100644\n--- a/Documentation/gitweb.txt\n+++ b/Documentation/gitweb.txt\n@@ -84,7 +84,7 @@ separator (rules for Perl's \"`split(\" \", $line)`\").\n \n * Fields use modified URI encoding, defined in RFC 3986, section 2.1\n (Percent-Encoding), or rather \"Query string encoding\" (see\n-link:http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference\n+http://en.wikipedia.org/wiki/Query_string#URL_encoding[]), the difference\n being that SP (\" \") can be encoded as \"{plus}\" (and therefore \"{plus}\" has to be\n also percent-encoded).\n +\ndiff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt\nindex 544373b..20525d9 100644\n--- a/Documentation/technical/http-protocol.txt\n+++ b/Documentation/technical/http-protocol.txt\n@@ -500,7 +500,7 @@ TODO: Document this further.\n References\n ----------\n \n-link:http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n-link:http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n+http://www.ietf.org/rfc/rfc1738.txt[RFC 1738: Uniform Resource Locators (URL)]\n+http://www.ietf.org/rfc/rfc2616.txt[RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1]\n link:technical/pack-protocol.html\n link:technical/protocol-capabilities.html\n-- \n1.8.3.2\n"}]}