{"thread":{"id":"42176","subject":"[PATCH v2] travis-ci: build documentation","startedAt":"2016-04-29T09:35:34Z","lastAt":"2016-05-13T06:26:19Z","messageCount":53,"participants":["larsxschneider@gmail.com","Jeff King","Matthieu Moy","Lars Schneider","Stefan Beller","Junio C Hamano","Eric Wong","Christian Couder","Ramsay Jones","Ævar Arnfjörð Bjarmason"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"284905","messageId":"1461922534-49293-1-git-send-email-larsxschneider@gmail.com","threadId":"42176","inReplyTo":null,"subject":"[PATCH v2] travis-ci: build documentation","fromName":"","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-04-29T09:35:34Z","receivedAt":"2016-04-29T09:35:34Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"From: Lars Schneider \n\nRun \"make doc\" as separate Travis CI build job to check if all\ndocumentation can be built without errors.\n\nSigned-off-by: Lars Schneider \n---\n\ndiff to v1:\n* add quick sanity check to documentation results (thanks Matthieu)\n* fix typo in commits message (thanks Stefan)\n* move 'make doc' into seperate Travis CI build job (thanks Peff)\n* started to move CI helper scripts to /ci (thanks Matthieu & Junio)\n\nI really like the idea of the \"/ci\" directory. Over time I plan to\nmigrate all non Travis-CI related code from .travis.yml to this directory.\nThis would ease the transition to or parallel execution with another CI\nsystem (e.g. GitLab CI to test Git on Windows).\n\nThanks,\nLars\n\n\n .travis.yml | 15 +++++++++++++++\n ci/test-documentation.sh | 23 +++++++++++++++++++++++\n 2 files changed, 38 insertions(+)\n create mode 100755 ci/test-documentation.sh\n\ndiff --git a/.travis.yml b/.travis.yml\nindex 78e433b..9f71d23 100644\n--- a/.travis.yml\n+++ b/.travis.yml\n@@ -32,6 +32,21 @@ env:\n # t9816 occasionally fails with \"TAP out of sequence errors\" on Travis CI OS X\n - GIT_SKIP_TESTS=\"t9810 t9816\"\n\n+matrix:\n+ include:\n+ - env: Documentation\n+ os: linux\n+ compiler: clang\n+ addons:\n+ apt:\n+ packages:\n+ - asciidoc\n+ - xmlto\n+ before_install:\n+ before_script: make doc\n+ script: ci/test-documentation.sh\n+ after_failure:\n+\n before_install:\n - >\n case \"${TRAVIS_OS_NAME:-linux}\" in\ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nnew file mode 100755\nindex 0000000..329ff4b\n--- /dev/null\n+++ b/ci/test-documentation.sh\n@@ -0,0 +1,23 @@\n+#!/bin/sh\n+#\n+# Perform a quick sanity check on documentation generated with 'make doc'.\n+#\n+\n+set -e\n+\n+test_file_count () {\n+ SUFFIX=$1\n+ EXPECTED_COUNT=$2\n+ ACTUAL_COUNT=$(find Documentation -type f -name \"*.$SUFFIX\" | wc -l)\n+ echo \"$ACTUAL_COUNT *.$SUFFIX files found. $EXPECTED_COUNT expected.\"\n+ test $ACTUAL_COUNT -eq $EXPECTED_COUNT\n+}\n+\n+test -s Documentation/git.html\n+test -s Documentation/git.xml\n+test -s Documentation/git.1\n+\n+# The follow numbers need to be adjusted when new documentation is added.\n+test_file_count html 233\n+test_file_count xml 171\n+test_file_count 1 152\n--\n2.5.1\n"},{"id":"284909","messageId":"20160429121429.GB27952@sigill.intra.peff.net","threadId":"42176","inReplyTo":"1461922534-49293-1-git-send-email-larsxschneider@gmail.com","subject":"Re: [PATCH v2] travis-ci: build documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-04-29T12:14:29Z","receivedAt":"2016-04-29T12:14:29Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Apr 29, 2016 at 11:35:34AM +0200, larsxschneider@gmail.com wrote:\n\n> +# The follow numbers need to be adjusted when new documentation is added.\n> +test_file_count html 233\n> +test_file_count xml 171\n> +test_file_count 1 152\n\nThis seems like it will be really flaky and a pain in the future. I'm\nnot really sure what it's accomplishing, either. The earlier steps would\ncomplain if something failed to render, wouldn't they? At some point we\nhave to have some faith in \"make doc\".\n\n-Peff\n"},{"id":"284910","messageId":"vpqeg9o7gh4.fsf@anie.imag.fr","threadId":"42176","inReplyTo":"20160429121429.GB27952@sigill.intra.peff.net","subject":"Re: [PATCH v2] travis-ci: build documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-04-29T12:21:43Z","receivedAt":"2016-04-29T12:21:43Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Jeff King writes:\n\n> On Fri, Apr 29, 2016 at 11:35:34AM +0200, larsxschneider@gmail.com wrote:\n>\n>> +# The follow numbers need to be adjusted when new documentation is added.\n>> +test_file_count html 233\n>> +test_file_count xml 171\n>> +test_file_count 1 152\n>\n> This seems like it will be really flaky and a pain in the future. I'm\n> not really sure what it's accomplishing, either. The earlier steps would\n> complain if something failed to render, wouldn't they? At some point we\n> have to have some faith in \"make doc\".\n\nI agree. My proposal to check for a handful of generated files was just\nbecause this extra paranoia was almost free (just 3 lines of code that\nwon't need particular maintenance).\n\nIn this case, I'm afraid the maintenance cost is much bigger than the\nexpected benefits.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"284924","messageId":"B5E5068F-7D69-41F8-BC33-E287567FD3AD@gmail.com","threadId":"42176","inReplyTo":"vpqeg9o7gh4.fsf@anie.imag.fr","subject":"Re: [PATCH v2] travis-ci: build documentation","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-04-29T14:22:05Z","receivedAt":"2016-04-29T14:22:05Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\n> On 29 Apr 2016, at 14:21, Matthieu Moy wrote:\n> \n> Jeff King writes:\n> \n>> On Fri, Apr 29, 2016 at 11:35:34AM +0200, larsxschneider@gmail.com wrote:\n>> \n>>> +# The follow numbers need to be adjusted when new documentation is added.\n>>> +test_file_count html 233\n>>> +test_file_count xml 171\n>>> +test_file_count 1 152\n>> \n>> This seems like it will be really flaky and a pain in the future. I'm\n>> not really sure what it's accomplishing, either. The earlier steps would\n>> complain if something failed to render, wouldn't they? At some point we\n>> have to have some faith in \"make doc\".\n> \n> I agree. My proposal to check for a handful of generated files was just\n> because this extra paranoia was almost free (just 3 lines of code that\n> won't need particular maintenance).\n> \n> In this case, I'm afraid the maintenance cost is much bigger than the\n> expected benefits.\n\nI agree, too. I wasn't sure about this check. That's why I added\nthe little comment above to point out the problem.\n\nShould I reroll?\n\nThanks,\nLars"},{"id":"284928","messageId":"20160429143254.GA27249@sigill.intra.peff.net","threadId":"42176","inReplyTo":"B5E5068F-7D69-41F8-BC33-E287567FD3AD@gmail.com","subject":"Re: [PATCH v2] travis-ci: build documentation","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-04-29T14:32:54Z","receivedAt":"2016-04-29T14:32:54Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Apr 29, 2016 at 04:22:05PM +0200, Lars Schneider wrote:\n\n> >>> +# The follow numbers need to be adjusted when new documentation is added.\n> >>> +test_file_count html 233\n> >>> +test_file_count xml 171\n> >>> +test_file_count 1 152\n> [...]\n> I agree, too. I wasn't sure about this check. That's why I added\n> the little comment above to point out the problem.\n> \n> Should I reroll?\n\nIMHO, yes.\n\n-Peff\n"},{"id":"284929","messageId":"vpqd1p8xyut.fsf@anie.imag.fr","threadId":"42176","inReplyTo":"1461922534-49293-1-git-send-email-larsxschneider@gmail.com","subject":"Re: [PATCH v2] travis-ci: build documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-04-29T14:40:10Z","receivedAt":"2016-04-29T14:40:10Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"larsxschneider@gmail.com writes:\n\n> + before_install:\n> + before_script: make doc\n> + script: ci/test-documentation.sh\n\nIf you are to re-roll, I think before_script and script should be\nmerged, i.e. just write\n\nscript: ci/test-documentation.sh\n\nand have ci/test-documentation.sh be:\n\n#!/bin/sh\n\nset -e\n\nmake doc\ntest -s Documentation/git.html\ntest -s Documentation/git.xml\ntest -s Documentation/git.1\n\nIn the perspective of using another CI tool, everything within ci/ is\npotentially shared between systems so I'd tend to minimize the content\nof .travis.yml in favor of ci/*\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"284952","messageId":"CAGZ79kbBCM0CdBoeWTx9kWBBN1f-kuibpUNh9FacOb2xxCDPcw@mail.gmail.com","threadId":"42176","inReplyTo":"vpqeg9o7gh4.fsf@anie.imag.fr","subject":"Re: [PATCH v2] travis-ci: build documentation","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-04-29T17:27:19Z","receivedAt":"2016-04-29T17:27:19Z","isPatch":true,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Fri, Apr 29, 2016 at 5:21 AM, Matthieu Moy\n wrote:\n> Jeff King writes:\n>\n>> On Fri, Apr 29, 2016 at 11:35:34AM +0200, larsxschneider@gmail.com wrote:\n>>\n>>> +# The follow numbers need to be adjusted when new documentation is added.\n>>> +test_file_count html 233\n>>> +test_file_count xml 171\n>>> +test_file_count 1 152\n>>\n>> This seems like it will be really flaky and a pain in the future. I'm\n>> not really sure what it's accomplishing, either. The earlier steps would\n>> complain if something failed to render, wouldn't they? At some point we\n>> have to have some faith in \"make doc\".\n>\n> I agree. My proposal to check for a handful of generated files was just\n> because this extra paranoia was almost free (just 3 lines of code that\n> won't need particular maintenance).\n>\n> In this case, I'm afraid the maintenance cost is much bigger than the\n> expected benefits.\n\nSo you proposed to check a handful files for its exact content?\n\nThis could be less of maintenance if we'd check with a \"larger as\" operator\nsuch as\n\n test_file_count_more_than html 200\n\nusing an arbitrary slightly smaller number.\n\n\n>\n> --\n> Matthieu Moy\n> http://www-verimag.imag.fr/~moy/\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"284958","messageId":"vpqtwikti74.fsf@anie.imag.fr","threadId":"42176","inReplyTo":"CAGZ79kbBCM0CdBoeWTx9kWBBN1f-kuibpUNh9FacOb2xxCDPcw@mail.gmail.com","subject":"Re: [PATCH v2] travis-ci: build documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-04-29T17:53:35Z","receivedAt":"2016-04-29T17:53:35Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Stefan Beller writes:\n\n> On Fri, Apr 29, 2016 at 5:21 AM, Matthieu Moy\n> wrote:\n>> Jeff King writes:\n>>\n>>> On Fri, Apr 29, 2016 at 11:35:34AM +0200, larsxschneider@gmail.com wrote:\n>>>\n>>>> +# The follow numbers need to be adjusted when new documentation is added.\n>>>> +test_file_count html 233\n>>>> +test_file_count xml 171\n>>>> +test_file_count 1 152\n>>>\n>>> This seems like it will be really flaky and a pain in the future. I'm\n>>> not really sure what it's accomplishing, either. The earlier steps would\n>>> complain if something failed to render, wouldn't they? At some point we\n>>> have to have some faith in \"make doc\".\n>>\n>> I agree. My proposal to check for a handful of generated files was just\n>> because this extra paranoia was almost free (just 3 lines of code that\n>> won't need particular maintenance).\n>>\n>> In this case, I'm afraid the maintenance cost is much bigger than the\n>> expected benefits.\n>\n> So you proposed to check a handful files for its exact content?\n\nNo, just to check that the files exist and are non-empty, i.e. the \"test\n-s\" part of Lars' patch.\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"284974","messageId":"D3ACDA07-DBD4-44B5-8D0A-531F2EC3BD65@gmail.com","threadId":"42176","inReplyTo":"CAGZ79kbBCM0CdBoeWTx9kWBBN1f-kuibpUNh9FacOb2xxCDPcw@mail.gmail.com","subject":"Re: [PATCH v2] travis-ci: build documentation","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-04-29T20:44:38Z","receivedAt":"2016-04-29T20:44:38Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\nOn 29 Apr 2016, at 19:27, Stefan Beller wrote:\n\n> On Fri, Apr 29, 2016 at 5:21 AM, Matthieu Moy\n> wrote:\n>> Jeff King writes:\n>> \n>>> On Fri, Apr 29, 2016 at 11:35:34AM +0200, larsxschneider@gmail.com wrote:\n>>> \n>>>> +# The follow numbers need to be adjusted when new documentation is added.\n>>>> +test_file_count html 233\n>>>> +test_file_count xml 171\n>>>> +test_file_count 1 152\n>>> \n>>> This seems like it will be really flaky and a pain in the future. I'm\n>>> not really sure what it's accomplishing, either. The earlier steps would\n>>> complain if something failed to render, wouldn't they? At some point we\n>>> have to have some faith in \"make doc\".\n>> \n>> I agree. My proposal to check for a handful of generated files was just\n>> because this extra paranoia was almost free (just 3 lines of code that\n>> won't need particular maintenance).\n>> \n>> In this case, I'm afraid the maintenance cost is much bigger than the\n>> expected benefits.\n> \n> So you proposed to check a handful files for its exact content?\n> \n> This could be less of maintenance if we'd check with a \"larger as\" operator\n> such as\n> \n> test_file_count_more_than html 200\n> \n> using an arbitrary slightly smaller number.\n\nWell, I was thinking about testing against something like \n$(find . -type f -name \"git*.txt\" | wc -l) but it the end\nall of this is not really meaningful I think...\n\n- Lars\n\n\n> \n> \n>> \n>> --\n>> Matthieu Moy\n>> http://www-verimag.imag.fr/~moy/\n>> --\n>> To unsubscribe from this list: send the line \"unsubscribe git\" in\n>> the body of a message to majordomo@vger.kernel.org\n>> More majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"284978","messageId":"xmqqziscw2g7.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"D3ACDA07-DBD4-44B5-8D0A-531F2EC3BD65@gmail.com","subject":"Re: [PATCH v2] travis-ci: build documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-04-29T21:05:28Z","receivedAt":"2016-04-29T21:05:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Lars Schneider writes:\n\n>> This could be less of maintenance if we'd check with a \"larger as\" operator\n>> such as\n>> \n>> test_file_count_more_than html 200\n>> \n>> using an arbitrary slightly smaller number.\n>\n> Well, I was thinking about testing against something like \n> $(find . -type f -name \"git*.txt\" | wc -l) but it the end\n> all of this is not really meaningful I think...\n\nEither is too much, I would say--I have too much faith in the exit\nstatus from \"make doc\", I guess.\n\nWhat would _REALLY_ be nice is a check that lets us catch an error\nlike this deliberate breakage:\n\n diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n index 4b0318e..a684f2d 100644\n --- a/Documentation/diff-options.txt\n +++ b/Documentation/diff-options.txt\n @@ -560,4 +560,4 @@ endif::git-format-patch[]\n Do not show any source or destination prefix.\n\n For more detailed explanation on these common options, see also\n -linkgit:gitdiffcore[7].\n +linkgit:gitdiffnore[7].\n\nWe just get a dangling link in the result without an error exit from\n\"make doc\"; neither \"test -s\" nor \"size is about what we expect\"\nwould catch such a breakage, though.\n\nOther things that might be of interest are\n\n make check-builtins\n make check-docs\n\nbut I am not sure if the latter built target is up to date (it has a\nwhiltelist that needs to stay current). We rarely add new commands\nthese days, so it is easy to forget what these build targets try to\ncheck, which makes them good candidates to be thrown into the set of\nautomated tests.\n"},{"id":"285204","messageId":"1462220405-12408-1-git-send-email-larsxschneider@gmail.com","threadId":"42176","inReplyTo":"xmqqziscw2g7.fsf@gitster.mtv.corp.google.com","subject":"[PATCH v3 0/2] travis-ci: build documentation","fromName":"","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-02T20:20:03Z","receivedAt":"2016-05-02T20:20:03Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"From: Lars Schneider \n\ndiff to v2:\n* remove file count check for generated documentation as it is too flaky\n* run `make doc` in `test-documentation.sh` to reduce the code in\n .travis.yml and ease the execution in other CI systems\n* add linkgit check\n* fix existing linkgit errors\n* add `make check-builtins` and `make check-docs`\n\nThanks to Jeff, Matthieu, Stefan, and Junio for the review!\n\nCheers,\nLars\n\nLars Schneider (2):\n Documentation: fix linkgit references\n travis-ci: build documentation\n\n .travis.yml | 15 +++++++++++++++\n Documentation/config.txt | 6 +++---\n Documentation/git-check-ignore.txt | 2 +-\n Documentation/git-filter-branch.txt | 4 ++--\n Documentation/git-for-each-ref.txt | 2 +-\n Documentation/git-help.txt | 4 ++--\n Documentation/git-instaweb.txt | 4 ++--\n Documentation/git-sh-i18n.txt | 2 +-\n ci/test-documentation.sh | 24 ++++++++++++++++++++++++\n 9 files changed, 51 insertions(+), 12 deletions(-)\n create mode 100755 ci/test-documentation.sh\n\n--\n2.5.1\n"},{"id":"285205","messageId":"1462220405-12408-2-git-send-email-larsxschneider@gmail.com","threadId":"42176","inReplyTo":"1462220405-12408-1-git-send-email-larsxschneider@gmail.com","subject":"[PATCH v3 1/2] Documentation: fix linkgit references","fromName":"","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-02T20:20:04Z","receivedAt":"2016-05-02T20:20:04Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"From: Lars Schneider \n\nSigned-off-by: Lars Schneider \n---\n Documentation/config.txt | 6 +++---\n Documentation/git-check-ignore.txt | 2 +-\n Documentation/git-filter-branch.txt | 4 ++--\n Documentation/git-for-each-ref.txt | 2 +-\n Documentation/git-help.txt | 4 ++--\n Documentation/git-instaweb.txt | 4 ++--\n Documentation/git-sh-i18n.txt | 2 +-\n 7 files changed, 12 insertions(+), 12 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex c7bbe98..c5f1d6b 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -894,7 +894,7 @@ branch..description::\n browser..cmd::\n \tSpecify the command to invoke the specified browser. The\n \tspecified command is evaluated in shell with the URLs passed\n-\tas arguments. (See linkgit:git-web{litdd}browse[1].)\n+\tas arguments. (See linkgit:git-web--browse[1].)\n \n browser..path::\n \tOverride the path for the given tool that may be used to\n@@ -1494,7 +1494,7 @@ gui.diffContext::\n \tmade by the linkgit:git-gui[1]. The default is \"5\".\n \n gui.displayUntracked::\n-\tDetermines if linkgit::git-gui[1] shows untracked files\n+\tDetermines if linkgit:git-gui[1] shows untracked files\n \tin the file list. The default is \"true\".\n \n gui.encoding::\n@@ -1665,7 +1665,7 @@ http.cookieFile::\n \tFile containing previously stored cookie lines which should be used\n \tin the Git http session, if they match the server. The file format\n \tof the file to read cookies from should be plain HTTP headers or\n-\tthe Netscape/Mozilla cookie file format (see linkgit:curl[1]).\n+\tthe Netscape/Mozilla cookie file format (see `curl(1)`).\n \tNOTE that the file specified with http.cookieFile is only used as\n \tinput unless http.saveCookies is set.\n \ndiff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\nindex e94367a..9a85998 100644\n--- a/Documentation/git-check-ignore.txt\n+++ b/Documentation/git-check-ignore.txt\n@@ -112,7 +112,7 @@ EXIT STATUS\n SEE ALSO\n --------\n linkgit:gitignore[5]\n-linkgit:gitconfig[5]\n+linkgit:git-config[5]\n linkgit:git-ls-files[1]\n \n GIT\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex 73fd9e8..6538cb1 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -205,8 +205,8 @@ to other tags will be rewritten to point to the underlying commit.\n Remap to ancestor\n ~~~~~~~~~~~~~~~~~\n \n-By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the\n-set of revisions which get rewritten. However, positive refs on the command\n+By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can limit\n+the set of revisions which get rewritten. However, positive refs on the command\n line are distinguished: we don't let them be excluded by such limiters. For\n this purpose, they are instead rewritten to point at the nearest ancestor that\n was not excluded.\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex c52578b..d9d406d 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -179,7 +179,7 @@ returns an empty string instead.\n \n As a special case for the date-type fields, you may specify a format for\n the date by adding `:` followed by date format name (see the\n-values the `--date` option to linkgit::git-rev-list[1] takes).\n+values the `--date` option to linkgit:git-rev-list[1] takes).\n \n \n EXAMPLES\ndiff --git a/Documentation/git-help.txt b/Documentation/git-help.txt\nindex 3956525..7af18f9 100644\n--- a/Documentation/git-help.txt\n+++ b/Documentation/git-help.txt\n@@ -72,7 +72,7 @@ The web browser can be specified using the configuration variable\n 'help.browser', or 'web.browser' if the former is not set. If none of\n these config variables is set, the 'git web{litdd}browse' helper script\n (called by 'git help') will pick a suitable default. See\n-linkgit:git-web{litdd}browse[1] for more information about this.\n+linkgit:git-web--browse[1] for more information about this.\n \n CONFIGURATION VARIABLES\n -----------------------\n@@ -95,7 +95,7 @@ help.browser, web.browser and browser..path\n The 'help.browser', 'web.browser' and 'browser..path' will also\n be checked if the 'web' format is chosen (either by command-line\n option or configuration variable). See '-w|--web' in the OPTIONS\n-section above and linkgit:git-web{litdd}browse[1].\n+section above and linkgit:git-web--browse[1].\n \n man.viewer\n ~~~~~~~~~~\ndiff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt\nindex cc75b25..b95cc15 100644\n--- a/Documentation/git-instaweb.txt\n+++ b/Documentation/git-instaweb.txt\n@@ -46,7 +46,7 @@ OPTIONS\n \tThe web browser that should be used to view the gitweb\n \tpage. This will be passed to the 'git web{litdd}browse' helper\n \tscript along with the URL of the gitweb instance. See\n-\tlinkgit:git-web{litdd}browse[1] for more information about this. If\n+\tlinkgit:git-web--browse[1] for more information about this. If\n \tthe script fails, the URL will be printed to stdout.\n \n start::\n@@ -82,7 +82,7 @@ You may specify configuration in your .git/config\n \n If the configuration variable 'instaweb.browser' is not set,\n 'web.browser' will be used instead if it is defined. See\n-linkgit:git-web{litdd}browse[1] for more information about this.\n+linkgit:git-web--browse[1] for more information about this.\n \n SEE ALSO\n --------\ndiff --git a/Documentation/git-sh-i18n.txt b/Documentation/git-sh-i18n.txt\nindex 60cf49c..eafa55a 100644\n--- a/Documentation/git-sh-i18n.txt\n+++ b/Documentation/git-sh-i18n.txt\n@@ -35,7 +35,7 @@ gettext::\n eval_gettext::\n \tCurrently a dummy fall-through function implemented as a wrapper\n \taround `printf(1)` with variables expanded by the\n-\tlinkgit:git-sh-i18n{litdd}envsubst[1] helper. Will be replaced by a\n+\tlinkgit:git-sh-i18n--envsubst[1] helper. Will be replaced by a\n \treal gettext implementation in a later version.\n \n GIT\n-- \n2.5.1\n"},{"id":"285206","messageId":"1462220405-12408-3-git-send-email-larsxschneider@gmail.com","threadId":"42176","inReplyTo":"1462220405-12408-1-git-send-email-larsxschneider@gmail.com","subject":"[PATCH v3 2/2] travis-ci: build documentation","fromName":"","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-02T20:20:05Z","receivedAt":"2016-05-02T20:20:05Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"From: Lars Schneider \n\nBuild documentation as separate Travis CI job to check for\ndocumentation errors.\n\nSigned-off-by: Lars Schneider \n---\n .travis.yml | 15 +++++++++++++++\n ci/test-documentation.sh | 24 ++++++++++++++++++++++++\n 2 files changed, 39 insertions(+)\n create mode 100755 ci/test-documentation.sh\n\ndiff --git a/.travis.yml b/.travis.yml\nindex 78e433b..55299bd 100644\n--- a/.travis.yml\n+++ b/.travis.yml\n@@ -32,6 +32,21 @@ env:\n # t9816 occasionally fails with \"TAP out of sequence errors\" on Travis CI OS X\n - GIT_SKIP_TESTS=\"t9810 t9816\"\n \n+matrix:\n+ include:\n+ - env: Documentation\n+ os: linux\n+ compiler: clang\n+ addons:\n+ apt:\n+ packages:\n+ - asciidoc\n+ - xmlto\n+ before_install:\n+ before_script:\n+ script: ci/test-documentation.sh\n+ after_failure:\n+\n before_install:\n - >\n case \"${TRAVIS_OS_NAME:-linux}\" in\ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nnew file mode 100755\nindex 0000000..889e6fd\n--- /dev/null\n+++ b/ci/test-documentation.sh\n@@ -0,0 +1,24 @@\n+#!/bin/sh\n+#\n+# Perform sanity checks on documentation and build it.\n+#\n+\n+set -e\n+\n+LINKS=$(grep --recursive --only-matching --no-filename --perl-regexp \\\n+ '(?<=linkgit:).*?(?=\\[\\d+\\])' Documentation/* \\\n+ | sort -u \\\n+)\n+\n+for LINK in $LINKS; do\n+ echo \"Checking linkgit:$LINK...\"\n+ test -s Documentation/$LINK.txt\n+done\n+\n+make check-builtins\n+make check-docs\n+make doc\n+\n+test -s Documentation/git.html\n+test -s Documentation/git.xml\n+test -s Documentation/git.1\n-- \n2.5.1\n"},{"id":"285207","messageId":"20160502203445.GA19509@sigill.intra.peff.net","threadId":"42176","inReplyTo":"1462220405-12408-2-git-send-email-larsxschneider@gmail.com","subject":"Re: [PATCH v3 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-02T20:34:45Z","receivedAt":"2016-05-02T20:34:45Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, May 02, 2016 at 10:20:04PM +0200, larsxschneider@gmail.com wrote:\n\n> From: Lars Schneider \n> \n> Signed-off-by: Lars Schneider \n> ---\n\nFix how? Your commit message doesn't say why this is a good idea. Since\nthis is v3, I'm guessing that reasoning is on the list, but it needs to\nbe summarized here in the commit message.\n\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index c7bbe98..c5f1d6b 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -894,7 +894,7 @@ branch..description::\n> browser..cmd::\n> \tSpecify the command to invoke the specified browser. The\n> \tspecified command is evaluated in shell with the URLs passed\n> -\tas arguments. (See linkgit:git-web{litdd}browse[1].)\n> +\tas arguments. (See linkgit:git-web--browse[1].)\n\nThe existing code renders fine for me with \"make git-config.1\". But with\nyour patch, I get a unicode emdash, which is wrong:\n\n--- old\t2016-05-02 16:27:53.242050262 -0400\n+++ new\t2016-05-02 16:27:57.742050360 -0400\n@@ -978,7 +978,7 @@\n \n browser..cmd\n Specify the command to invoke the specified browser. The specified command is evaluated in shell with the\n- URLs passed as arguments. (See git-web--browse(1).)\n+ URLs passed as arguments. (See git-web—browse(1).)\n \n browser..path\n Override the path for the given tool that may be used to browse HTML help (see -w option in git-help(1))\n\nIn case it's hard to see with your font, the generated roff looks like\nthis:\n\n-\\fBgit-web--browse\\fR(1)\\&.)\n+\\fBgit-web\\(embrowse\\fR(1)\\&.)\n\nSo I think that's a step backwards. I did check the asciidoctor\nrendering on git-scm.com, though, and it gets the {litdd} case wrong. So\nI think it does need fixing, but we need a solution that looks correct\nin both cases. Maybe linkgit:`git-web--browse`[1] would work; it seems\nOK with my version of asciidoc, but I have a feeling it will run into\nthe same problem with asciidoctor (if it's not respecting {litdd} in\nthat context, it's probably also not respecting backticks).\n\n-Peff\n"},{"id":"285210","messageId":"xmqq60uwrxyi.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"1462220405-12408-3-git-send-email-larsxschneider@gmail.com","subject":"Re: [PATCH v3 2/2] travis-ci: build documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-02T20:45:09Z","receivedAt":"2016-05-02T20:45:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"larsxschneider@gmail.com writes:\n\n> +set -e\n> +\n> +LINKS=$(grep --recursive --only-matching --no-filename --perl-regexp \\\n> + '(?<=linkgit:).*?(?=\\[\\d+\\])' Documentation/* \\\n> + | sort -u \\\n> +)\n> +\n> +for LINK in $LINKS; do\n> + echo \"Checking linkgit:$LINK...\"\n> + test -s Documentation/$LINK.txt\n> +done\n\nPlease separate the above link check out of this step and do so\nseparately after the move of test body to a separate script\nsettles.\n\nWhen you reintroduce the tests, please make sure the shell script\nfollow the coding style of other scripts. E.g. I do not think the\nlast one in the $(...) needs a backslash continuation at all. I am\nassuming that you are doing this only on Linux, in which case use of\nGNUism with grep may be fine.\n\n> +make check-builtins\n> +make check-docs\n> +make doc\n> +\n> +test -s Documentation/git.html\n> +test -s Documentation/git.xml\n> +test -s Documentation/git.1\n"},{"id":"285254","messageId":"6483CF6A-5C14-42C9-BE1A-6D6AA33999BB@gmail.com","threadId":"42176","inReplyTo":"xmqq60uwrxyi.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3 2/2] travis-ci: build documentation","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-03T08:12:44Z","receivedAt":"2016-05-03T08:12:44Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\nOn 02 May 2016, at 22:45, Junio C Hamano wrote:\n\n> larsxschneider@gmail.com writes:\n> \n>> +set -e\n>> +\n>> +LINKS=$(grep --recursive --only-matching --no-filename --perl-regexp \\\n>> + '(?<=linkgit:).*?(?=\\[\\d+\\])' Documentation/* \\\n>> + | sort -u \\\n>> +)\n>> +\n>> +for LINK in $LINKS; do\n>> + echo \"Checking linkgit:$LINK...\"\n>> + test -s Documentation/$LINK.txt\n>> +done\n> \n> Please separate the above link check out of this step and do so\n> separately after the move of test body to a separate script\n> settles.\nOK. I also wonder if the link check should rather go to the \n\"check-docs\" Makefile target?\n\n\n> When you reintroduce the tests, please make sure the shell script\n> follow the coding style of other scripts. E.g. I do not think the\n> last one in the $(...) needs a backslash continuation at all. I am\n> assuming that you are doing this only on Linux, in which case use of\n> GNUism with grep may be fine.\nOK.\n\nThanks for the review,\nLars\n\n\n> \n>> +make check-builtins\n>> +make check-docs\n>> +make doc\n>> +\n>> +test -s Documentation/git.html\n>> +test -s Documentation/git.xml\n>> +test -s Documentation/git.1\n"},{"id":"285255","messageId":"E4A56B4E-6F2E-44E3-870B-D1D3A71B2869@gmail.com","threadId":"42176","inReplyTo":"20160502203445.GA19509@sigill.intra.peff.net","subject":"Re: [PATCH v3 1/2] Documentation: fix linkgit references","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-03T08:30:09Z","receivedAt":"2016-05-03T08:30:09Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\nOn 02 May 2016, at 22:34, Jeff King wrote:\n\n> On Mon, May 02, 2016 at 10:20:04PM +0200, larsxschneider@gmail.com wrote:\n> \n>> From: Lars Schneider \n>> \n>> Signed-off-by: Lars Schneider \n>> ---\n> \n> Fix how? Your commit message doesn't say why this is a good idea. Since\n> this is v3, I'm guessing that reasoning is on the list, but it needs to\n> be summarized here in the commit message.\nYou are right, I should have explained my thinking a bit more detailed. \nA few of the fixed linkgit references are just typos, e.g.:\n\n-linkgit:gitconfig[5]\n+linkgit:git-config[5]\n\n-values the `--date` option to linkgit::git-rev-list[1] takes).\n+values the `--date` option to linkgit:git-rev-list[1] takes).\n\n-\tthe Netscape/Mozilla cookie file format (see linkgit:curl[1]).\n+\tthe Netscape/Mozilla cookie file format (see `curl(1)`).\n\nI mistakenly assumed the \"{litdd}\" was a typo/bad search replace, too.\nI checked this website and thought my change would fix it, too:\n\nhttps://git-scm.com/docs/git-config\n\nThere it is rendered as \"(See git-web{litdd}browse[1].)\" and the link\nis broken.\n\n\n>> diff --git a/Documentation/config.txt b/Documentation/config.txt\n>> index c7bbe98..c5f1d6b 100644\n>> --- a/Documentation/config.txt\n>> +++ b/Documentation/config.txt\n>> @@ -894,7 +894,7 @@ branch..description::\n>> browser..cmd::\n>> \tSpecify the command to invoke the specified browser. The\n>> \tspecified command is evaluated in shell with the URLs passed\n>> -\tas arguments. (See linkgit:git-web{litdd}browse[1].)\n>> +\tas arguments. (See linkgit:git-web--browse[1].)\n> \n> The existing code renders fine for me with \"make git-config.1\". But with\n> your patch, I get a unicode emdash, which is wrong:\n> \n> --- old\t2016-05-02 16:27:53.242050262 -0400\n> +++ new\t2016-05-02 16:27:57.742050360 -0400\n> @@ -978,7 +978,7 @@\n> \n> browser..cmd\n> Specify the command to invoke the specified browser. The specified command is evaluated in shell with the\n> - URLs passed as arguments. (See git-web--browse(1).)\n> + URLs passed as arguments. (See git-web—browse(1).)\n> \n> browser..path\n> Override the path for the given tool that may be used to browse HTML help (see -w option in git-help(1))\n> \n> In case it's hard to see with your font, the generated roff looks like\n> this:\n> \n> -\\fBgit-web--browse\\fR(1)\\&.)\n> +\\fBgit-web\\(embrowse\\fR(1)\\&.)\n\nI can confirm. Sorry, I indeed missed that.\n\n\n> So I think that's a step backwards. I did check the asciidoctor\n> rendering on git-scm.com, though, and it gets the {litdd} case wrong. So\n> I think it does need fixing, but we need a solution that looks correct\n> in both cases. Maybe linkgit:`git-web--browse`[1] would work; it seems\n> OK with my version of asciidoc, but I have a feeling it will run into\n> the same problem with asciidoctor (if it's not respecting {litdd} in\n> that context, it's probably also not respecting backticks).\nI will play with this to find a solution. Would it be an option to\nreplace \"--\" with \"-\"? Why do we need two dashes if they cause trouble?\n\nThanks for the review,\nLars"},{"id":"285325","messageId":"xmqqd1p3p2ry.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"E4A56B4E-6F2E-44E3-870B-D1D3A71B2869@gmail.com","subject":"Re: [PATCH v3 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-03T15:41:37Z","receivedAt":"2016-05-03T15:41:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Lars Schneider writes:\n\n> On 02 May 2016, at 22:34, Jeff King wrote:\n>\n>> On Mon, May 02, 2016 at 10:20:04PM +0200, larsxschneider@gmail.com wrote:\n>> \n>>> From: Lars Schneider \n>>> \n>>> Signed-off-by: Lars Schneider \n>>> ---\n>> \n>> Fix how? Your commit message doesn't say why this is a good idea. Since\n>> this is v3, I'm guessing that reasoning is on the list, but it needs to\n>> be summarized here in the commit message.\n> You are right, I should have explained my thinking a bit more detailed. \n> A few of the fixed linkgit references are just typos, e.g.:\n>\n> -linkgit:gitconfig[5]\n> +linkgit:git-config[5]\n\nI didn't run \"git blame\" yet, so it might be that we used to have it\nin section 5, but \"git config --help\" puts the latter in section 1.\n\nEven though you obviously were fooled by AsciiDoctor regarding\nliteral double dash {litdd}, other parts of the changes did look\ngood typofixes. Thanks for starting this.\n"},{"id":"285326","messageId":"xmqq8tzrp2pd.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"6483CF6A-5C14-42C9-BE1A-6D6AA33999BB@gmail.com","subject":"Re: [PATCH v3 2/2] travis-ci: build documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-03T15:43:10Z","receivedAt":"2016-05-03T15:43:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Lars Schneider writes:\n\n> On 02 May 2016, at 22:45, Junio C Hamano wrote:\n>\n>> larsxschneider@gmail.com writes:\n>> \n>>> +set -e\n>>> +\n>>> +LINKS=$(grep --recursive --only-matching --no-filename --perl-regexp \\\n>>> + '(?<=linkgit:).*?(?=\\[\\d+\\])' Documentation/* \\\n>>> + | sort -u \\\n>>> +)\n>>> +\n>>> +for LINK in $LINKS; do\n>>> + echo \"Checking linkgit:$LINK...\"\n>>> + test -s Documentation/$LINK.txt\n>>> +done\n>> \n>> Please separate the above link check out of this step and do so\n>> separately after the move of test body to a separate script\n>> settles.\n>\n> OK. I also wonder if the link check should rather go to the \n> \"check-docs\" Makefile target?\n\nThat sounds like a good direction.\n\nWhich in turn means that people on all platforms are welcome to run\nit, which in turn means that the script must be even more portable,\nwith avoiding GNUism and bash-isms etc.\n"},{"id":"285346","messageId":"20160503175808.GA29877@sigill.intra.peff.net","threadId":"42176","inReplyTo":"E4A56B4E-6F2E-44E3-870B-D1D3A71B2869@gmail.com","subject":"Re: [PATCH v3 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-03T17:58:09Z","receivedAt":"2016-05-03T17:58:09Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 03, 2016 at 10:30:09AM +0200, Lars Schneider wrote:\n\n> > So I think that's a step backwards. I did check the asciidoctor\n> > rendering on git-scm.com, though, and it gets the {litdd} case wrong. So\n> > I think it does need fixing, but we need a solution that looks correct\n> > in both cases. Maybe linkgit:`git-web--browse`[1] would work; it seems\n> > OK with my version of asciidoc, but I have a feeling it will run into\n> > the same problem with asciidoctor (if it's not respecting {litdd} in\n> > that context, it's probably also not respecting backticks).\n> I will play with this to find a solution. Would it be an option to\n> replace \"--\" with \"-\"? Why do we need two dashes if they cause trouble?\n\nWe use two dashes to signify \"internal\" programs that users should not\nrely on. So \"git-web-browse\" would be something we'd expect to support\nforever, but \"git-web--browse\" is an implementation detail of one of our\nscripts (that just happens to require an extra program).\n\nSo I don't think we want to switch away from that convention just to\nmake the documentation work.\n\nAFAICT, the {litdd} is working fine with asciidoc; it's only asciidoctor\nthat is the problem. So the first step may be talking with asciidoctor\nfolks to see if it's a bug, or if they have a recommended workaround.\n\n-Peff\n"},{"id":"285347","messageId":"20160503175932.GB29877@sigill.intra.peff.net","threadId":"42176","inReplyTo":"xmqqd1p3p2ry.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-03T17:59:32Z","receivedAt":"2016-05-03T17:59:32Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 03, 2016 at 08:41:37AM -0700, Junio C Hamano wrote:\n\n> Even though you obviously were fooled by AsciiDoctor regarding\n> literal double dash {litdd}, other parts of the changes did look\n> good typofixes. Thanks for starting this.\n\nYeah, I stopped reading after seeing the first hunk, but I agree the\nrest look trivial.\n\n-Peff\n"},{"id":"285432","messageId":"32CC7549-3A50-42F3-A6CC-9B15EFA01A46@gmail.com","threadId":"42176","inReplyTo":"xmqq8tzrp2pd.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v3 2/2] travis-ci: build documentation","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-04T08:04:24Z","receivedAt":"2016-05-04T08:04:24Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\nOn 03 May 2016, at 17:43, Junio C Hamano wrote:\n\n> Lars Schneider writes:\n> \n>> On 02 May 2016, at 22:45, Junio C Hamano wrote:\n>> \n>>> larsxschneider@gmail.com writes:\n>>> \n>>>> +set -e\n>>>> +\n>>>> +LINKS=$(grep --recursive --only-matching --no-filename --perl-regexp \\\n>>>> + '(?<=linkgit:).*?(?=\\[\\d+\\])' Documentation/* \\\n>>>> + | sort -u \\\n>>>> +)\n>>>> +\n>>>> +for LINK in $LINKS; do\n>>>> + echo \"Checking linkgit:$LINK...\"\n>>>> + test -s Documentation/$LINK.txt\n>>>> +done\n>>> \n>>> Please separate the above link check out of this step and do so\n>>> separately after the move of test body to a separate script\n>>> settles.\n>> \n>> OK. I also wonder if the link check should rather go to the \n>> \"check-docs\" Makefile target?\n> \n> That sounds like a good direction.\n> \n> Which in turn means that people on all platforms are welcome to run\n> it, which in turn means that the script must be even more portable,\n> with avoiding GNUism and bash-isms etc.\n\nOK. I am not that experienced with shell scripting and therefore it\nis hard for me to distinguish between the different shell features.\nDo you know/can you recommend the most basic shell to test/work \nwith? A quick Google search told me that \"dash\" from Ubuntu seems\nto be a good baseline as it aims to support pretty much only POSIX [1].\n\nThanks,\nLars\n\n[1] http://www.cyberciti.biz/faq/debian-ubuntu-linux-binbash-vs-bindash-vs-binshshell/\n"},{"id":"285436","messageId":"20160504081852.GA24252@dcvr.yhbt.net","threadId":"42176","inReplyTo":"32CC7549-3A50-42F3-A6CC-9B15EFA01A46@gmail.com","subject":"Re: [PATCH v3 2/2] travis-ci: build documentation","fromName":"Eric Wong","fromEmail":"e@80x24.org","sentAt":"2016-05-04T08:18:52Z","receivedAt":"2016-05-04T08:18:52Z","isPatch":true,"sender":{"key":"e@80x24.org","avatar":null},"body":"Lars Schneider wrote:\n> OK. I am not that experienced with shell scripting and therefore it\n> is hard for me to distinguish between the different shell features.\n> Do you know/can you recommend the most basic shell to test/work \n> with? A quick Google search told me that \"dash\" from Ubuntu seems\n> to be a good baseline as it aims to support pretty much only POSIX [1].\n\nYes, I recommend dash as your /bin/sh if you're using a\nDebian-based system (\"Debian Almquist shell\") such as Ubuntu.\n\nAlso, the Debian \"devscripts\" package has a tool called\n\"checkbashisms\" which I have also found very useful.\n\nMaybe ksh(93) or posh could be good, too, but it's been a\nwhile...\n\nI also rely on checking the manpages-posix and manpages-posix-dev\nin the \"non-free\" section of Debian (\"multiverse\" in Ubuntu?)\n"},{"id":"285437","messageId":"xmqqshxyi6br.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"32CC7549-3A50-42F3-A6CC-9B15EFA01A46@gmail.com","subject":"Re: [PATCH v3 2/2] travis-ci: build documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T08:19:04Z","receivedAt":"2016-05-04T08:19:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Lars Schneider writes:\n\n> A quick Google search told me that \"dash\" from Ubuntu seems\n> to be a good baseline as it aims to support pretty much only POSIX [1].\n\nYeah that is a good and safe starting point.\n"},{"id":"285444","messageId":"1462351116-19308-1-git-send-email-larsxschneider@gmail.com","threadId":"42176","inReplyTo":"E4A56B4E-6F2E-44E3-870B-D1D3A71B2869@gmail.com","subject":"[PATCH v4 0/2] travis-ci: build documentation","fromName":"","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-04T08:38:34Z","receivedAt":"2016-05-04T08:38:34Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"From: Lars Schneider \n\ndiff to v3:\n* Revert the change from \"{litdd}\" to \"--\" in the documentation.\n \"{litdd}\" is rendered wrong in some HTML output [1], but \"--\"\n breaks the roff output ... I will investigate this and try to fix\n it in a future patch.\n* I removed the doc link checker for now. I will try to reintroduce\n an improved version of the link checker as part of `make check-docs`\n in a future patch.\n\nThanks Peff and Junio for the review,\nLars\n\n[1] https://git-scm.com/docs/git-config\n\nLars Schneider (2):\n Documentation: fix linkgit references\n travis-ci: build documentation\n\n .travis.yml | 15 +++++++++++++++\n Documentation/config.txt | 4 ++--\n Documentation/git-check-ignore.txt | 2 +-\n Documentation/git-filter-branch.txt | 4 ++--\n Documentation/git-for-each-ref.txt | 2 +-\n ci/test-documentation.sh | 14 ++++++++++++++\n 6 files changed, 35 insertions(+), 6 deletions(-)\n create mode 100755 ci/test-documentation.sh\n\n--\n2.5.1\n"},{"id":"285443","messageId":"1462351116-19308-2-git-send-email-larsxschneider@gmail.com","threadId":"42176","inReplyTo":"1462351116-19308-1-git-send-email-larsxschneider@gmail.com","subject":"[PATCH v4 1/2] Documentation: fix linkgit references","fromName":"","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-04T08:38:35Z","receivedAt":"2016-05-04T08:38:35Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"From: Lars Schneider \n\nSigned-off-by: Lars Schneider \n---\n Documentation/config.txt | 4 ++--\n Documentation/git-check-ignore.txt | 2 +-\n Documentation/git-filter-branch.txt | 4 ++--\n Documentation/git-for-each-ref.txt | 2 +-\n 4 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex c7bbe98..5683400 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -1494,7 +1494,7 @@ gui.diffContext::\n \tmade by the linkgit:git-gui[1]. The default is \"5\".\n \n gui.displayUntracked::\n-\tDetermines if linkgit::git-gui[1] shows untracked files\n+\tDetermines if linkgit:git-gui[1] shows untracked files\n \tin the file list. The default is \"true\".\n \n gui.encoding::\n@@ -1665,7 +1665,7 @@ http.cookieFile::\n \tFile containing previously stored cookie lines which should be used\n \tin the Git http session, if they match the server. The file format\n \tof the file to read cookies from should be plain HTTP headers or\n-\tthe Netscape/Mozilla cookie file format (see linkgit:curl[1]).\n+\tthe Netscape/Mozilla cookie file format (see `curl(1)`).\n \tNOTE that the file specified with http.cookieFile is only used as\n \tinput unless http.saveCookies is set.\n \ndiff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\nindex e94367a..9a85998 100644\n--- a/Documentation/git-check-ignore.txt\n+++ b/Documentation/git-check-ignore.txt\n@@ -112,7 +112,7 @@ EXIT STATUS\n SEE ALSO\n --------\n linkgit:gitignore[5]\n-linkgit:gitconfig[5]\n+linkgit:git-config[5]\n linkgit:git-ls-files[1]\n \n GIT\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex 73fd9e8..6538cb1 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -205,8 +205,8 @@ to other tags will be rewritten to point to the underlying commit.\n Remap to ancestor\n ~~~~~~~~~~~~~~~~~\n \n-By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the\n-set of revisions which get rewritten. However, positive refs on the command\n+By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can limit\n+the set of revisions which get rewritten. However, positive refs on the command\n line are distinguished: we don't let them be excluded by such limiters. For\n this purpose, they are instead rewritten to point at the nearest ancestor that\n was not excluded.\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex c52578b..d9d406d 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -179,7 +179,7 @@ returns an empty string instead.\n \n As a special case for the date-type fields, you may specify a format for\n the date by adding `:` followed by date format name (see the\n-values the `--date` option to linkgit::git-rev-list[1] takes).\n+values the `--date` option to linkgit:git-rev-list[1] takes).\n \n \n EXAMPLES\n-- \n2.5.1\n"},{"id":"285445","messageId":"1462351116-19308-3-git-send-email-larsxschneider@gmail.com","threadId":"42176","inReplyTo":"1462351116-19308-1-git-send-email-larsxschneider@gmail.com","subject":"[PATCH v4 2/2] travis-ci: build documentation","fromName":"","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-04T08:38:36Z","receivedAt":"2016-05-04T08:38:36Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"From: Lars Schneider \n\nBuild documentation as separate Travis CI job to check for\ndocumentation errors.\n\nSigned-off-by: Lars Schneider \n---\n .travis.yml | 15 +++++++++++++++\n ci/test-documentation.sh | 14 ++++++++++++++\n 2 files changed, 29 insertions(+)\n create mode 100755 ci/test-documentation.sh\n\ndiff --git a/.travis.yml b/.travis.yml\nindex 78e433b..55299bd 100644\n--- a/.travis.yml\n+++ b/.travis.yml\n@@ -32,6 +32,21 @@ env:\n # t9816 occasionally fails with \"TAP out of sequence errors\" on Travis CI OS X\n - GIT_SKIP_TESTS=\"t9810 t9816\"\n \n+matrix:\n+ include:\n+ - env: Documentation\n+ os: linux\n+ compiler: clang\n+ addons:\n+ apt:\n+ packages:\n+ - asciidoc\n+ - xmlto\n+ before_install:\n+ before_script:\n+ script: ci/test-documentation.sh\n+ after_failure:\n+\n before_install:\n - >\n case \"${TRAVIS_OS_NAME:-linux}\" in\ndiff --git a/ci/test-documentation.sh b/ci/test-documentation.sh\nnew file mode 100755\nindex 0000000..579d540\n--- /dev/null\n+++ b/ci/test-documentation.sh\n@@ -0,0 +1,14 @@\n+#!/bin/sh\n+#\n+# Perform sanity checks on documentation and build it.\n+#\n+\n+set -e\n+\n+make check-builtins\n+make check-docs\n+make doc\n+\n+test -s Documentation/git.html\n+test -s Documentation/git.xml\n+test -s Documentation/git.1\n-- \n2.5.1\n"},{"id":"285446","messageId":"F6210682-2FCA-423D-B6D3-06938C95D497@gmail.com","threadId":"42176","inReplyTo":"1462351116-19308-2-git-send-email-larsxschneider@gmail.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-04T08:43:04Z","receivedAt":"2016-05-04T08:43:04Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\nOn 04 May 2016, at 10:38, larsxschneider@gmail.com wrote:\n\n> From: Lars Schneider \n> \n> Signed-off-by: Lars Schneider \n> ---\n> Documentation/config.txt | 4 ++--\n> Documentation/git-check-ignore.txt | 2 +-\n> Documentation/git-filter-branch.txt | 4 ++--\n> Documentation/git-for-each-ref.txt | 2 +-\n> 4 files changed, 6 insertions(+), 6 deletions(-)\n> \n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index c7bbe98..5683400 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -1494,7 +1494,7 @@ gui.diffContext::\n> \tmade by the linkgit:git-gui[1]. The default is \"5\".\n> \n> gui.displayUntracked::\n> -\tDetermines if linkgit::git-gui[1] shows untracked files\n> +\tDetermines if linkgit:git-gui[1] shows untracked files\n> \tin the file list. The default is \"true\".\n> \n> gui.encoding::\n> @@ -1665,7 +1665,7 @@ http.cookieFile::\n> \tFile containing previously stored cookie lines which should be used\n> \tin the Git http session, if they match the server. The file format\n> \tof the file to read cookies from should be plain HTTP headers or\n> -\tthe Netscape/Mozilla cookie file format (see linkgit:curl[1]).\n> +\tthe Netscape/Mozilla cookie file format (see `curl(1)`).\n> \tNOTE that the file specified with http.cookieFile is only used as\n> \tinput unless http.saveCookies is set.\n> \n> diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\n> index e94367a..9a85998 100644\n> --- a/Documentation/git-check-ignore.txt\n> +++ b/Documentation/git-check-ignore.txt\n> @@ -112,7 +112,7 @@ EXIT STATUS\n> SEE ALSO\n> --------\n> linkgit:gitignore[5]\n> -linkgit:gitconfig[5]\n> +linkgit:git-config[5]\n> linkgit:git-ls-files[1]\n> \n> GIT\n> diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\n> index 73fd9e8..6538cb1 100644\n> --- a/Documentation/git-filter-branch.txt\n> +++ b/Documentation/git-filter-branch.txt\n> @@ -205,8 +205,8 @@ to other tags will be rewritten to point to the underlying commit.\n> Remap to ancestor\n> ~~~~~~~~~~~~~~~~~\n> \n> -By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the\n> -set of revisions which get rewritten. However, positive refs on the command\n> +By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can limit\n> +the set of revisions which get rewritten. However, positive refs on the command\n\nAll other linkgit fixes seem legimiate to me although I am not sure of this case\n\n-linkgit:rev-list[1] \n+linkgit:git-rev-list[1]\n \n\"rev-list\" works but I think \"git-rev-list\" would be the canonical form?\nSee: https://git-scm.com/docs/git-filter-branch\n\n\n> line are distinguished: we don't let them be excluded by such limiters. For\n> this purpose, they are instead rewritten to point at the nearest ancestor that\n> was not excluded.\n> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\n> index c52578b..d9d406d 100644\n> --- a/Documentation/git-for-each-ref.txt\n> +++ b/Documentation/git-for-each-ref.txt\n> @@ -179,7 +179,7 @@ returns an empty string instead.\n> \n> As a special case for the date-type fields, you may specify a format for\n> the date by adding `:` followed by date format name (see the\n> -values the `--date` option to linkgit::git-rev-list[1] takes).\n> +values the `--date` option to linkgit:git-rev-list[1] takes).\n> \n> \n> EXAMPLES\n> -- \n> 2.5.1\n> \n"},{"id":"285448","messageId":"20160504085708.GA17920@sigill.intra.peff.net","threadId":"42176","inReplyTo":"F6210682-2FCA-423D-B6D3-06938C95D497@gmail.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-04T08:57:08Z","receivedAt":"2016-05-04T08:57:08Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 04, 2016 at 10:43:04AM +0200, Lars Schneider wrote:\n\n> > diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\n> > index 73fd9e8..6538cb1 100644\n> > --- a/Documentation/git-filter-branch.txt\n> > +++ b/Documentation/git-filter-branch.txt\n> > @@ -205,8 +205,8 @@ to other tags will be rewritten to point to the underlying commit.\n> > Remap to ancestor\n> > ~~~~~~~~~~~~~~~~~\n> > \n> > -By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the\n> > -set of revisions which get rewritten. However, positive refs on the command\n> > +By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can limit\n> > +the set of revisions which get rewritten. However, positive refs on the command\n> \n> All other linkgit fixes seem legimiate to me although I am not sure of this case\n> \n> -linkgit:rev-list[1] \n> +linkgit:git-rev-list[1]\n> \n> \"rev-list\" works but I think \"git-rev-list\" would be the canonical form?\n> See: https://git-scm.com/docs/git-filter-branch\n\nIt should definitely be \"git-rev-list\". The \"linkgit\" macro will format\nwhatever text you feed it. For the manpages, that doesn't matter,\nbecause they don't actually hyperlink. But for other formats (like\nHTML), using just \"rev-list\" will generate a broken link.\n\n-Peff\n"},{"id":"285449","messageId":"CAP8UFD2XXE2Hh9NxMFS3dvaJk90LgwdbDcXmHvVir6MEKu2B3Q@mail.gmail.com","threadId":"42176","inReplyTo":"32CC7549-3A50-42F3-A6CC-9B15EFA01A46@gmail.com","subject":"Re: [PATCH v3 2/2] travis-ci: build documentation","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2016-05-04T09:11:44Z","receivedAt":"2016-05-04T09:11:44Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Wed, May 4, 2016 at 10:04 AM, Lars Schneider\n wrote:\n>\n> On 03 May 2016, at 17:43, Junio C Hamano wrote:\n>\n>> Lars Schneider writes:\n>>\n>>> On 02 May 2016, at 22:45, Junio C Hamano wrote:\n>>>\n>>>> larsxschneider@gmail.com writes:\n>>>>\n>>>>> +set -e\n>>>>> +\n>>>>> +LINKS=$(grep --recursive --only-matching --no-filename --perl-regexp \\\n>>>>> + '(?<=linkgit:).*?(?=\\[\\d+\\])' Documentation/* \\\n>>>>> + | sort -u \\\n>>>>> +)\n>>>>> +\n>>>>> +for LINK in $LINKS; do\n>>>>> + echo \"Checking linkgit:$LINK...\"\n>>>>> + test -s Documentation/$LINK.txt\n>>>>> +done\n>>>>\n>>>> Please separate the above link check out of this step and do so\n>>>> separately after the move of test body to a separate script\n>>>> settles.\n>>>\n>>> OK. I also wonder if the link check should rather go to the\n>>> \"check-docs\" Makefile target?\n>>\n>> That sounds like a good direction.\n>>\n>> Which in turn means that people on all platforms are welcome to run\n>> it, which in turn means that the script must be even more portable,\n>> with avoiding GNUism and bash-isms etc.\n>\n> OK. I am not that experienced with shell scripting and therefore it\n> is hard for me to distinguish between the different shell features.\n> Do you know/can you recommend the most basic shell to test/work\n> with? A quick Google search told me that \"dash\" from Ubuntu seems\n> to be a good baseline as it aims to support pretty much only POSIX [1].\n\nYou might also want to check:\n\nhttp://www.shellcheck.net/\n"},{"id":"285458","messageId":"vpq1t5it65h.fsf@anie.imag.fr","threadId":"42176","inReplyTo":"CAP8UFD2XXE2Hh9NxMFS3dvaJk90LgwdbDcXmHvVir6MEKu2B3Q@mail.gmail.com","subject":"Re: [PATCH v3 2/2] travis-ci: build documentation","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@grenoble-inp.fr","sentAt":"2016-05-04T11:27:22Z","receivedAt":"2016-05-04T11:27:22Z","isPatch":true,"sender":{"key":"matthieu.moy@grenoble-inp.fr","avatar":"https://gravatar.com/avatar/72c8a2705971a25dfaff23cece15130d405685845d911aedd5667ace277f3fc5?d=mp&s=160"},"body":"Christian Couder writes:\n\n> You might also want to check:\n>\n> http://www.shellcheck.net/\n\nIndeed, it's also an excellent tool to check for common mistakes in\nshell scripts (there are many, and shellcheck is good at pointing them\nout and explaining them).\n\nhttp://www.shellcheck.net/\n\n(Available online and as a command-line tool)\n\n-- \nMatthieu Moy\nhttp://www-verimag.imag.fr/~moy/\n"},{"id":"285460","messageId":"5729DF25.7030503@ramsayjones.plus.com","threadId":"42176","inReplyTo":"F6210682-2FCA-423D-B6D3-06938C95D497@gmail.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Ramsay Jones","fromEmail":"ramsay@ramsayjones.plus.com","sentAt":"2016-05-04T11:38:13Z","receivedAt":"2016-05-04T11:38:13Z","isPatch":true,"sender":{"key":"ramsay@ramsayjones.plus.com","avatar":"https://avatars.githubusercontent.com/u/33702710?v=4"},"body":"\n\nOn 04/05/16 09:43, Lars Schneider wrote:\n> \n> On 04 May 2016, at 10:38, larsxschneider@gmail.com wrote:\n> \n>> From: Lars Schneider \n>>\n>> Signed-off-by: Lars Schneider \n>> ---\n>> Documentation/config.txt | 4 ++--\n>> Documentation/git-check-ignore.txt | 2 +-\n>> Documentation/git-filter-branch.txt | 4 ++--\n>> Documentation/git-for-each-ref.txt | 2 +-\n>> 4 files changed, 6 insertions(+), 6 deletions(-)\n>>\n>> diff --git a/Documentation/config.txt b/Documentation/config.txt\n>> index c7bbe98..5683400 100644\n>> --- a/Documentation/config.txt\n>> +++ b/Documentation/config.txt\n>> @@ -1494,7 +1494,7 @@ gui.diffContext::\n>> \tmade by the linkgit:git-gui[1]. The default is \"5\".\n>>\n>> gui.displayUntracked::\n>> -\tDetermines if linkgit::git-gui[1] shows untracked files\n>> +\tDetermines if linkgit:git-gui[1] shows untracked files\n>> \tin the file list. The default is \"true\".\n>>\n>> gui.encoding::\n>> @@ -1665,7 +1665,7 @@ http.cookieFile::\n>> \tFile containing previously stored cookie lines which should be used\n>> \tin the Git http session, if they match the server. The file format\n>> \tof the file to read cookies from should be plain HTTP headers or\n>> -\tthe Netscape/Mozilla cookie file format (see linkgit:curl[1]).\n>> +\tthe Netscape/Mozilla cookie file format (see `curl(1)`).\n>> \tNOTE that the file specified with http.cookieFile is only used as\n>> \tinput unless http.saveCookies is set.\n>>\n>> diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\n>> index e94367a..9a85998 100644\n>> --- a/Documentation/git-check-ignore.txt\n>> +++ b/Documentation/git-check-ignore.txt\n>> @@ -112,7 +112,7 @@ EXIT STATUS\n>> SEE ALSO\n>> --------\n>> linkgit:gitignore[5]\n>> -linkgit:gitconfig[5]\n>> +linkgit:git-config[5]\n\nI think Junio already noted, git-config is in section 1 not 5.\n\nATB,\nRamsay Jones\n"},{"id":"285476","messageId":"xmqqd1p1ivfw.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"5729DF25.7030503@ramsayjones.plus.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T17:28:51Z","receivedAt":"2016-05-04T17:28:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ramsay Jones writes:\n\n>>> diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\n>>> index e94367a..9a85998 100644\n>>> --- a/Documentation/git-check-ignore.txt\n>>> +++ b/Documentation/git-check-ignore.txt\n>>> @@ -112,7 +112,7 @@ EXIT STATUS\n>>> SEE ALSO\n>>> --------\n>>> linkgit:gitignore[5]\n>>> -linkgit:gitconfig[5]\n>>> +linkgit:git-config[5]\n>\n> I think Junio already noted, git-config is in section 1 not 5.\n\nNot just that, I am afraid. This came from 368aa529 (add\ngit-check-ignore sub-command, 2013-01-06) and it added these:\n\n+linkgit:gitignore[5]\n+linkgit:gitconfig[5]\n+linkgit:git-ls-files[5]\n\nThe last one was later corrected, but who knows what other mistakes\nthere are?\n\nSo I used the script attached at the bottom to audit the whole\nthing, and the result is here.\n\n-- >8 --\nDocumentation/config.txt:1497: nongit link: :git-gui[1]\nDocumentation/config.txt:1662: nongit link: curl[1]\nDocumentation/diff-options.txt:274: wrong section (should be 5): gitattributes[1]\nDocumentation/git-check-ignore.txt:115: no such source: gitconfig[5]\nDocumentation/git-filter-branch.txt:208: nongit link: rev-list[1]\nDocumentation/git-for-each-ref.txt:182: nongit link: :git-rev-list[1]\nDocumentation/git-notes.txt:405: wrong section (should be 1): git[7]\nDocumentation/technical/api-credentials.txt:246: wrong section (should be 1): git-credential[7]\nDocumentation/technical/api-credentials.txt:271: wrong section (should be 1): git-config[5]\n-- 8< --\n\nI do not think there is any false positive above, so perhaps the\nchecker script below can be used as the link checker we discussed?\n\n-- >8 --\n#!/bin/sh\n\ngit grep -l linkgit: Documentation/ |\nwhile read path\ndo\n\tperl -e '\n\tsub report {\n\t\tmy ($where, $what, $error) = @_;\n\t\tprint \"$where: $error: $what\\n\";\n\t}\n\n\tsub grab_section {\n\t\tmy ($page) = @_;\n\t\topen my $fh, \"<\", \"Documentation/$page.txt\";\n\t\tmy $firstline = <$fh>;\n\t\tchomp $firstline;\n\t\tclose $fh;\n\t\tmy ($section) = ($firstline =~ /.*\\((\\d)\\)$/);\n\t\treturn $section;\n\t}\n\n\twhile (<>) {\n\t\tmy $where = \"$ARGV:$.\";\n\t\twhile (s/linkgit:((.*?)\\[(\\d)\\])//) {\n\t\t\tmy ($target, $page, $section) = ($1, $2, $3);\n\n\t\t\t# De-AsciiDoc\n\t\t\t$page =~ s/{litdd}/--/g;\n\n\t\t\tif ($page !~ /^git/) {\n\t\t\t\treport($where, $target, \"nongit link\");\n\t\t\t\tnext;\n\t\t\t}\n\t\t\tif (! -f \"Documentation/$page.txt\") {\n\t\t\t\treport($where, $target, \"no such source\");\n\t\t\t\tnext;\n\t\t\t}\n\t\t\t$real_section = grab_section($page); \n\t\t\tif ($real_section != $section) {\n\t\t\t\treport($where, $target,\n\t\t\t\t\t\"wrong section (should be $real_section)\");\n\t\t\t\tnext;\n\t\t\t}\n\t\t}\n\t}\n ' \"$path\"\ndone\n"},{"id":"285477","messageId":"xmqq8tzpiv3b.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"xmqqd1p1ivfw.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T17:36:24Z","receivedAt":"2016-05-04T17:36:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> So I used the script attached at the bottom to audit the whole\n> thing, and the result is here.\n> ...\n\nWhile I was at it, I just did this to make the documentation set\nlint clean.\n\n-- >8 --\n\nThere are a handful of incorrect \"linkgit:[
]\"\ninstances in our documentation set.\n\n * Some have an extra colon after \"linkgit:\"; fix them by removing\n the extra colon;\n\n * Some refer to a page outside the Git suite, namely curl(1); fix\n them by using the `curl(1)` that already appears on the same page\n for the same purpose of referring the readers to its manual page.\n\n * Some spell the name of the page incorrectly, e.g. \"rev-list\" when\n they mean \"git-rev-list\"; fix them.\n\n * Some list the manual section incorrectly; fix them to make sure\n they match what is at the top of the target of the link.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/config.txt | 4 ++--\n Documentation/diff-options.txt | 2 +-\n Documentation/everyday.txto | 2 +-\n Documentation/git-check-ignore.txt | 2 +-\n Documentation/git-filter-branch.txt | 2 +-\n Documentation/git-for-each-ref.txt | 2 +-\n Documentation/git-notes.txt | 2 +-\n Documentation/technical/api-credentials.txt | 4 ++--\n 8 files changed, 10 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 42d2b50..f37e16b 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -1494,7 +1494,7 @@ gui.diffContext::\n \tmade by the linkgit:git-gui[1]. The default is \"5\".\n \n gui.displayUntracked::\n-\tDetermines if linkgit::git-gui[1] shows untracked files\n+\tDetermines if linkgit:git-gui[1] shows untracked files\n \tin the file list. The default is \"true\".\n \n gui.encoding::\n@@ -1659,7 +1659,7 @@ http.cookieFile::\n \tFile containing previously stored cookie lines which should be used\n \tin the Git http session, if they match the server. The file format\n \tof the file to read cookies from should be plain HTTP headers or\n-\tthe Netscape/Mozilla cookie file format (see linkgit:curl[1]).\n+\tthe Netscape/Mozilla cookie file format (see `curl(1)`).\n \tNOTE that the file specified with http.cookieFile is only used as\n \tinput unless http.saveCookies is set.\n \ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 4b0318e..3cb3015 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -271,7 +271,7 @@ For example, `--word-diff-regex=.` will treat each character as a word\n and, correspondingly, show differences character by character.\n +\n The regex can also be set via a diff driver or configuration option, see\n-linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly\n+linkgit:gitattributes[5] or linkgit:git-config[1]. Giving it explicitly\n overrides any diff driver or configuration setting. Diff drivers\n override configuration settings.\n \ndiff --git a/Documentation/everyday.txto b/Documentation/everyday.txto\nindex c5047d8..ae555bd 100644\n--- a/Documentation/everyday.txto\n+++ b/Documentation/everyday.txto\n@@ -1,7 +1,7 @@\n Everyday Git With 20 Commands Or So\n ===================================\n \n-This document has been moved to linkgit:giteveryday[1].\n+This document has been moved to linkgit:giteveryday[7].\n \n Please let the owners of the referring site know so that they can update the\n link you clicked to get here.\ndiff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt\nindex e94367a..611754f 100644\n--- a/Documentation/git-check-ignore.txt\n+++ b/Documentation/git-check-ignore.txt\n@@ -112,7 +112,7 @@ EXIT STATUS\n SEE ALSO\n --------\n linkgit:gitignore[5]\n-linkgit:gitconfig[5]\n+linkgit:git-config[1]\n linkgit:git-ls-files[1]\n \n GIT\ndiff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt\nindex 73fd9e8..003731f 100644\n--- a/Documentation/git-filter-branch.txt\n+++ b/Documentation/git-filter-branch.txt\n@@ -205,7 +205,7 @@ to other tags will be rewritten to point to the underlying commit.\n Remap to ancestor\n ~~~~~~~~~~~~~~~~~\n \n-By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the\n+By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can limit the\n set of revisions which get rewritten. However, positive refs on the command\n line are distinguished: we don't let them be excluded by such limiters. For\n this purpose, they are instead rewritten to point at the nearest ancestor that\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex c52578b..d9d406d 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -179,7 +179,7 @@ returns an empty string instead.\n \n As a special case for the date-type fields, you may specify a format for\n the date by adding `:` followed by date format name (see the\n-values the `--date` option to linkgit::git-rev-list[1] takes).\n+values the `--date` option to linkgit:git-rev-list[1] takes).\n \n \n EXAMPLES\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 8de3499..9c4fd68 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -402,4 +402,4 @@ on the `notes.rewrite.` and `notes.rewriteRef` settings.\n \n GIT\n ---\n-Part of the linkgit:git[7] suite\n+Part of the linkgit:git[1] suite\ndiff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt\nindex e44426d..75368f2 100644\n--- a/Documentation/technical/api-credentials.txt\n+++ b/Documentation/technical/api-credentials.txt\n@@ -243,7 +243,7 @@ appended to its command line, which is one of:\n The details of the credential will be provided on the helper's stdin\n stream. The exact format is the same as the input/output format of the\n `git credential` plumbing command (see the section `INPUT/OUTPUT\n-FORMAT` in linkgit:git-credential[7] for a detailed specification).\n+FORMAT` in linkgit:git-credential[1] for a detailed specification).\n \n For a `get` operation, the helper should produce a list of attributes\n on stdout in the same format. A helper is free to produce a subset, or\n@@ -268,4 +268,4 @@ See also\n \n linkgit:gitcredentials[7]\n \n-linkgit:git-config[5] (See configuration variables `credential.*`)\n+linkgit:git-config[1] (See configuration variables `credential.*`)\n"},{"id":"285488","messageId":"xmqqvb2thczf.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"xmqqd1p1ivfw.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T18:52:52Z","receivedAt":"2016-05-04T18:52:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> I do not think there is any false positive above, so perhaps the\n> checker script below can be used as the link checker we discussed?\n\n-- >8 --\nSubject: [PATCH] ci: validate \"gitlink:\" in documentation\n\nIt is easy to add incorrect \"linkgit:[
]\" references\nto our documentation suite. Catch these common classes of errors:\n\n * Referring to Documentation/.txt that does not exist.\n\n * Referring to a outside the Git suite. In general, \n must begin with \"git\".\n\n * Listing the manual
incorrectly. The first line of the\n Documentation/.txt must end with \"(
)\".\n\nwith a new script ci/lint-gitlink.sh.\n\nSigned-off-by: Junio C Hamano \n---\n ci/lint-gitlink.sh | 47 +++++++++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 47 insertions(+)\n create mode 100755 ci/lint-gitlink.sh\n\ndiff --git a/ci/lint-gitlink.sh b/ci/lint-gitlink.sh\nnew file mode 100755\nindex 0000000..2379626\n--- /dev/null\n+++ b/ci/lint-gitlink.sh\n@@ -0,0 +1,47 @@\n+#!/bin/sh\n+\n+git grep -l linkgit: Documentation/ |\n+while read path\n+do\n+\tperl -e '\n+\tsub report {\n+\t\tmy ($where, $what, $error) = @_;\n+\t\tprint \"$where: $error: $what\\n\";\n+\t}\n+\n+\tsub grab_section {\n+\t\tmy ($page) = @_;\n+\t\topen my $fh, \"<\", \"Documentation/$page.txt\";\n+\t\tmy $firstline = <$fh>;\n+\t\tchomp $firstline;\n+\t\tclose $fh;\n+\t\tmy ($section) = ($firstline =~ /.*\\((\\d)\\)$/);\n+\t\treturn $section;\n+\t}\n+\n+\twhile (<>) {\n+\t\tmy $where = \"$ARGV:$.\";\n+\t\twhile (s/linkgit:((.*?)\\[(\\d)\\])//) {\n+\t\t\tmy ($target, $page, $section) = ($1, $2, $3);\n+\n+\t\t\t# De-AsciiDoc\n+\t\t\t$page =~ s/{litdd}/--/g;\n+\n+\t\t\tif ($page !~ /^git/) {\n+\t\t\t\treport($where, $target, \"nongit link\");\n+\t\t\t\tnext;\n+\t\t\t}\n+\t\t\tif (! -f \"Documentation/$page.txt\") {\n+\t\t\t\treport($where, $target, \"no such source\");\n+\t\t\t\tnext;\n+\t\t\t}\n+\t\t\t$real_section = grab_section($page);\n+\t\t\tif ($real_section != $section) {\n+\t\t\t\treport($where, $target,\n+\t\t\t\t\t\"wrong section (should be $real_section)\");\n+\t\t\t\tnext;\n+\t\t\t}\n+\t\t}\n+\t}\n+\t' \"$path\"\n+done\n-- \n2.8.2-498-g6350fe8\n"},{"id":"285496","messageId":"20160504192516.GD21259@sigill.intra.peff.net","threadId":"42176","inReplyTo":"xmqqvb2thczf.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-04T19:25:16Z","receivedAt":"2016-05-04T19:25:16Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 04, 2016 at 11:52:52AM -0700, Junio C Hamano wrote:\n\n> > I do not think there is any false positive above, so perhaps the\n> > checker script below can be used as the link checker we discussed?\n> \n> -- >8 --\n> Subject: [PATCH] ci: validate \"gitlink:\" in documentation\n> \n> It is easy to add incorrect \"linkgit:[
]\" references\n> to our documentation suite. Catch these common classes of errors:\n> \n> * Referring to Documentation/.txt that does not exist.\n> \n> * Referring to a outside the Git suite. In general, \n> must begin with \"git\".\n> \n> * Listing the manual
incorrectly. The first line of the\n> Documentation/.txt must end with \"(
)\".\n> \n> with a new script ci/lint-gitlink.sh.\n\nIt seems like this is something we _should_ be able to do while asciidoc\nis actually expanding the macro, rather than as a separate step. But:\n\n 1. I don't think stock asciidoc has this much flexibility in its\n macros.\n\n 2. There are some ordering questions (e.g., while building \"foo.1\",\n \"bar.1\" may not be built yet, so we still have to massage requests\n for \"bar.1\" into \"bar.txt\".\n\nLikewise, I think we could build the whole HTML source and then actually\njust look for broken links in it. But that script would probably end up\nlooking similar to this one, with s/linkgit/href/. But it does more\ndirectly measure what we want, which is that the rendered doc is usable;\nit would catch something like using \"--\" instead of \"{litdd}\".\n\n> +#!/bin/sh\n> +\n> +git grep -l linkgit: Documentation/ |\n> +while read path\n> +do\n> +\tperl -e '\n\nIs it worth just making this a perl script, rather than a shell script\nwith a giant inline perl script? Perl is actually really good at doing\nthat \"grep\" as it reads the file. :)\n\nBesides being slightly more efficient (reading the files only once\nrather than filtering once via grep and then re-reading via perl). But\nmore importantly, it avoids a layer of quoting, which makes it less\nlikely to make a mistake by using single-quote in the perl script (I do\nnot see any errors in what you wrote, though).\n\n-Peff\n"},{"id":"285500","messageId":"xmqq7ff9h9zo.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"20160504192516.GD21259@sigill.intra.peff.net","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T19:57:31Z","receivedAt":"2016-05-04T19:57:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> Likewise, I think we could build the whole HTML source and then actually\n> just look for broken links in it. But that script would probably end up\n> looking similar to this one, with s/linkgit/href/. But it does more\n> directly measure what we want, which is that the rendered doc is usable;\n\nI debated about this myself, but chose to inspect the source\nmaterial, as that approach is easier to give actionable lint output\nto the user that points out the file:lineno to be corrected.\n\n> it would catch something like using \"--\" instead of \"{litdd}\".\n\nThat is true indeed. With the \"source\" approach, that would indeed\nbe harder.\n\n>> +#!/bin/sh\n>> +\n>> +git grep -l linkgit: Documentation/ |\n>> +while read path\n>> +do\n>> +\tperl -e '\n>\n> Is it worth just making this a perl script, rather than a shell script\n> with a giant inline perl script? Perl is actually really good at doing\n> that \"grep\" as it reads the file. :)\n\nOK.\n\n-- >8 --\nFrom: Junio C Hamano \nDate: Wed, 4 May 2016 11:48:06 -0700\nSubject: [PATCH v2] ci: validate \"gitlink:\" in documentation\n\nIt is easy to add incorrect \"linkgit:[
]\" references\nto our documentation suite. Catch these common classes of errors:\n\n * Referring to Documentation/.txt that does not exist.\n\n * Referring to a outside the Git suite. In general, \n must begin with \"git\".\n\n * Listing the manual
incorrectly. The first line of the\n Documentation/.txt must end with \"(
)\".\n\nwith a new script \"ci/lint-gitlink\".\n\nSigned-off-by: Junio C Hamano \n---\n ci/lint-gitlink | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 60 insertions(+)\n create mode 100755 ci/lint-gitlink\n\ndiff --git a/ci/lint-gitlink b/ci/lint-gitlink\nnew file mode 100755\nindex 0000000..bb73e89\n--- /dev/null\n+++ b/ci/lint-gitlink\n@@ -0,0 +1,60 @@\n+#!/usr/bin/perl\n+\n+use File::Find;\n+\n+my $found_errors = 0;\n+\n+sub report {\n+\tmy ($where, $what, $error) = @_;\n+\tprint \"$where: $error: $what\\n\";\n+\t$found_errors = 1;\n+}\n+\n+sub grab_section {\n+\tmy ($page) = @_;\n+\topen my $fh, \"<\", \"Documentation/$page.txt\";\n+\tmy $firstline = <$fh>;\n+\tchomp $firstline;\n+\tclose $fh;\n+\tmy ($section) = ($firstline =~ /.*\\((\\d)\\)$/);\n+\treturn $section;\n+}\n+\n+sub lint {\n+\tmy ($file) = @_;\n+\topen my $fh, \"<\", $file\n+\t\tor return;\n+\twhile (<$fh>) {\n+\t\tmy $where = \"$file:$.\";\n+\t\twhile (s/linkgit:((.*?)\\[(\\d)\\])//) {\n+\t\t\tmy ($target, $page, $section) = ($1, $2, $3);\n+\n+\t\t\t# De-AsciiDoc\n+\t\t\t$page =~ s/{litdd}/--/g;\n+\n+\t\t\tif ($page !~ /^git/) {\n+\t\t\t\treport($where, $target, \"nongit link\");\n+\t\t\t\tnext;\n+\t\t\t}\n+\t\t\tif (! -f \"Documentation/$page.txt\") {\n+\t\t\t\treport($where, $target, \"no such source\");\n+\t\t\t\tnext;\n+\t\t\t}\n+\t\t\t$real_section = grab_section($page);\n+\t\t\tif ($real_section != $section) {\n+\t\t\t\treport($where, $target,\n+\t\t\t\t\t\"wrong section (should be $real_section)\");\n+\t\t\t\tnext;\n+\t\t\t}\n+\t\t}\n+\t}\n+\tclose $fh;\n+}\n+\n+sub lint_it {\n+\tlint($File::Find::name) if -f;\n+}\n+\n+find({ wanted => \\&lint_it, no_chdir => 1 }, \"Documentation\");\n+\n+exit $found_errors;\n-- \n2.8.2-498-g6350fe8\n"},{"id":"285502","messageId":"20160504200635.GA22787@sigill.intra.peff.net","threadId":"42176","inReplyTo":"xmqq7ff9h9zo.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-04T20:06:36Z","receivedAt":"2016-05-04T20:06:36Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 04, 2016 at 12:57:31PM -0700, Junio C Hamano wrote:\n\n> > Is it worth just making this a perl script, rather than a shell script\n> > with a giant inline perl script? Perl is actually really good at doing\n> > that \"grep\" as it reads the file. :)\n> \n> OK.\n\nHmm. This new version uses File::Find:\n\n> +sub lint_it {\n> +\tlint($File::Find::name) if -f;\n> +}\n> +\n> +find({ wanted => \\&lint_it, no_chdir => 1 }, \"Documentation\");\n\nThat will inspect non-source files, too.\n\nWould:\n\n open(my $files, '-|', qw(git ls-files));\n while (<$files>) {\n chomp;\n ...\n }\n\nmake sense? Or a simpler but non-streaming spelling:\n\n my @files = map { chomp; $_ } `git ls-files`;\n\nOr just taking the list of files on the command line as your original\ndid, and feeding `ls-files` from the caller. That also lets you do\n\"link-gitlink git-foo.txt\", etc.\n\n-Peff\n"},{"id":"285515","messageId":"xmqq8tzpfrt0.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"20160504200635.GA22787@sigill.intra.peff.net","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T21:15:39Z","receivedAt":"2016-05-04T21:15:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Wed, May 04, 2016 at 12:57:31PM -0700, Junio C Hamano wrote:\n>\n>> > Is it worth just making this a perl script, rather than a shell script\n>> > with a giant inline perl script? Perl is actually really good at doing\n>> > that \"grep\" as it reads the file. :)\n>> \n>> OK.\n>\n> Hmm. This new version uses File::Find:\n>\n>> +sub lint_it {\n>> +\tlint($File::Find::name) if -f;\n>> +}\n>> +\n>> +find({ wanted => \\&lint_it, no_chdir => 1 }, \"Documentation\");\n>\n> That will inspect non-source files, too.\n>\n> Would:\n>\n> open(my $files, '-|', qw(git ls-files));\n> while (<$files>) {\n> chomp;\n> ...\n> }\n>\n> make sense? Or a simpler but non-streaming spelling:\n>\n> my @files = map { chomp; $_ } `git ls-files`;\n\nI forgot to say that I wanted not to rely on \"git\" (i.e. OK to use\nthis on tarball extract).\n\n> Or just taking the list of files on the command line as your original\n> did, and feeding `ls-files` from the caller. That also lets you do\n> \"link-gitlink git-foo.txt\", etc.\n\nYes, I think that is the most sensible.\n"},{"id":"285517","messageId":"20160504213149.GA22828@sigill.intra.peff.net","threadId":"42176","inReplyTo":"xmqq8tzpfrt0.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-04T21:31:50Z","receivedAt":"2016-05-04T21:31:50Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 04, 2016 at 02:15:39PM -0700, Junio C Hamano wrote:\n\n> > make sense? Or a simpler but non-streaming spelling:\n> >\n> > my @files = map { chomp; $_ } `git ls-files`;\n> \n> I forgot to say that I wanted not to rely on \"git\" (i.e. OK to use\n> this on tarball extract).\n\nOh, that's a good idea.\n\n> > Or just taking the list of files on the command line as your original\n> > did, and feeding `ls-files` from the caller. That also lets you do\n> > \"link-gitlink git-foo.txt\", etc.\n> \n> Yes, I think that is the most sensible.\n\nYeah, and then the Makefile can drive it from $(MAN_TXT), etc, without\nrequiring git (which I think is what you were getting at, but just\nspelling it out for myself and the list).\n\n-Peff\n"},{"id":"285519","messageId":"xmqq4madfqxs.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"20160504213149.GA22828@sigill.intra.peff.net","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T21:34:23Z","receivedAt":"2016-05-04T21:34:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Third time's a charm, perhaps?\n \n-- >8 --\nSubject: [PATCH] ci: validate \"gitlink:\" in documentation\n\nIt is easy to add incorrect \"linkgit:[
]\" references\nto our documentation suite. Catch these common classes of errors:\n\n * Referring to Documentation/.txt that does not exist.\n\n * Referring to a outside the Git suite. In general, \n must begin with \"git\".\n\n * Listing the manual
incorrectly. The first line of the\n Documentation/.txt must end with \"(
)\".\n\nwith a new script \"ci/lint-gitlink\", and drive it from \"make check-docs\".\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/Makefile | 5 +++++\n Makefile | 1 +\n ci/lint-gitlink | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++\n 3 files changed, 62 insertions(+)\n create mode 100755 ci/lint-gitlink\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3e39e28..e9cd43d 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -204,6 +204,7 @@ ifndef V\n \tQUIET_DBLATEX\t= @echo ' ' DBLATEX $@;\n \tQUIET_XSLTPROC\t= @echo ' ' XSLTPROC $@;\n \tQUIET_GEN\t= @echo ' ' GEN $@;\n+\tQUIET_LINT\t= @echo ' ' LINT $@;\n \tQUIET_STDERR\t= 2> /dev/null\n \tQUIET_SUBDIR0\t= +@subdir=\n \tQUIET_SUBDIR1\t= ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \\\n@@ -427,4 +428,8 @@ quick-install-html: require-htmlrepo\n print-man1:\n \t@for i in $(MAN1_TXT); do echo $$i; done\n \n+lint-docs::\n+\t$(QUIET_LINT)$(foreach txt,$(patsubst %.html,%.txt,$(DOC_HTML)), \\\n+\t../ci/lint-gitlink $(txt))\n+\n .PHONY: FORCE\ndiff --git a/Makefile b/Makefile\nindex 2742a69..61bd0ab 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -2496,6 +2496,7 @@ ALL_COMMANDS += git-gui git-citool\n \n .PHONY: check-docs\n check-docs::\n+\t$(MAKE) -C Documentation lint-docs\n \t@(for v in $(ALL_COMMANDS); \\\n \tdo \\\n \t\tcase \"$$v\" in \\\ndiff --git a/ci/lint-gitlink b/ci/lint-gitlink\nnew file mode 100755\nindex 0000000..6b6bf91\n--- /dev/null\n+++ b/ci/lint-gitlink\n@@ -0,0 +1,56 @@\n+#!/usr/bin/perl\n+\n+my $found_errors = 0;\n+\n+sub report {\n+\tmy ($where, $what, $error) = @_;\n+\tprint \"$where: $error: $what\\n\";\n+\t$found_errors = 1;\n+}\n+\n+sub grab_section {\n+\tmy ($page) = @_;\n+\topen my $fh, \"<\", \"$page.txt\";\n+\tmy $firstline = <$fh>;\n+\tchomp $firstline;\n+\tclose $fh;\n+\tmy ($section) = ($firstline =~ /.*\\((\\d)\\)$/);\n+\treturn $section;\n+}\n+\n+sub lint {\n+\tmy ($file) = @_;\n+\topen my $fh, \"<\", $file\n+\t\tor return;\n+\twhile (<$fh>) {\n+\t\tmy $where = \"$file:$.\";\n+\t\twhile (s/linkgit:((.*?)\\[(\\d)\\])//) {\n+\t\t\tmy ($target, $page, $section) = ($1, $2, $3);\n+\n+\t\t\t# De-AsciiDoc\n+\t\t\t$page =~ s/{litdd}/--/g;\n+\n+\t\t\tif ($page !~ /^git/) {\n+\t\t\t\treport($where, $target, \"nongit link\");\n+\t\t\t\tnext;\n+\t\t\t}\n+\t\t\tif (! -f \"$page.txt\") {\n+\t\t\t\treport($where, $target, \"no such source\");\n+\t\t\t\tnext;\n+\t\t\t}\n+\t\t\t$real_section = grab_section($page);\n+\t\t\tif ($real_section != $section) {\n+\t\t\t\treport($where, $target,\n+\t\t\t\t\t\"wrong section (should be $real_section)\");\n+\t\t\t\tnext;\n+\t\t\t}\n+\t\t}\n+\t}\n+\tclose $fh;\n+}\n+\n+for (@ARGV) {\n+\tlint($_);\n+}\n+\n+exit $found_errors;\n-- \n2.8.2-498-g6350fe8\n"},{"id":"285521","messageId":"20160504214412.GA25237@sigill.intra.peff.net","threadId":"42176","inReplyTo":"xmqq4madfqxs.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-04T21:44:12Z","receivedAt":"2016-05-04T21:44:12Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 04, 2016 at 02:34:23PM -0700, Junio C Hamano wrote:\n\n> Third time's a charm, perhaps?\n> \n> -- >8 --\n> Subject: [PATCH] ci: validate \"gitlink:\" in documentation\n> \n> It is easy to add incorrect \"linkgit:[
]\" references\n> to our documentation suite. Catch these common classes of errors:\n> \n> * Referring to Documentation/.txt that does not exist.\n> \n> * Referring to a outside the Git suite. In general, \n> must begin with \"git\".\n> \n> * Listing the manual
incorrectly. The first line of the\n> Documentation/.txt must end with \"(
)\".\n> \n> with a new script \"ci/lint-gitlink\", and drive it from \"make check-docs\".\n> \n> Signed-off-by: Junio C Hamano \n> ---\n\nThis looks good to me. Two minor nits that may not be worth addressing:\n\n> +lint-docs::\n> +\t$(QUIET_LINT)$(foreach txt,$(patsubst %.html,%.txt,$(DOC_HTML)), \\\n> +\t../ci/lint-gitlink $(txt))\n> +\n\nThis dependency feels funny. Wouldn't CI want to invoke this as:\n\n make -C Documentation lint-docs\n\nIOW, Documentation owns the script (just like t/ owns its own lint\nscripts like check-non-portable-shell.pl), and CI always just triggers\nthe make-driven checks, just as a normal developer would?\n\n> +sub lint {\n> +\tmy ($file) = @_;\n> +\topen my $fh, \"<\", $file\n> +\t\tor return;\n> +\twhile (<$fh>) {\n> +\t\tmy $where = \"$file:$.\";\n> [... actual linting of line ...]\n> +}\n> +\n> +for (@ARGV) {\n> +\tlint($_);\n> +}\n\nThe usual perl way here would be:\n\n while(<>) {\n\tmy $where = \"$ARGV:$.\";\n\t... actual linting of line ...\n }\n\nwhere \"<>\" automagically reads from files on the command-line or stdin\nif none were specified (and sets $ARGV as appropriate). But maybe you\nprefer not to handle the stdin case (it is a benefit sometimes, but an\nannoyance if you accidentally end up with an empty file list).\n\n-Peff\n"},{"id":"285525","messageId":"xmqqk2j9ebj8.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"20160504214412.GA25237@sigill.intra.peff.net","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T21:52:27Z","receivedAt":"2016-05-04T21:52:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> This dependency feels funny. Wouldn't CI want to invoke this as:\n>\n> make -C Documentation lint-docs\n\nI expected CI to do this instead\n\n\tmake check-docs\n"},{"id":"285526","messageId":"CACBZZX4dYjHETCyMFQngBKoS80gkmcAZKKYc0VkE0ufaAg-gZg@mail.gmail.com","threadId":"42176","inReplyTo":"20160504200635.GA22787@sigill.intra.peff.net","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2016-05-04T21:54:52Z","receivedAt":"2016-05-04T21:54:52Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Wed, May 4, 2016 at 10:06 PM, Jeff King wrote:\n> Would:\n>\n> open(my $files, '-|', qw(git ls-files));\n> while (<$files>) {\n> chomp;\n> ...\n> }\n>\n> make sense? Or a simpler but non-streaming spelling:\n>\n> my @files = map { chomp; $_ } `git ls-files`;\n\nAs a minor sidenote you can equivalently write that as:\n\n chomp(my @files = `git ls-files`);\n\nI.e. chomp itself when given a list will chomp each item of the list.\nSo no need for a map.\n"},{"id":"285529","messageId":"20160504220935.GA26339@sigill.intra.peff.net","threadId":"42176","inReplyTo":"xmqqk2j9ebj8.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-04T22:09:35Z","receivedAt":"2016-05-04T22:09:35Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 04, 2016 at 02:52:27PM -0700, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > This dependency feels funny. Wouldn't CI want to invoke this as:\n> >\n> > make -C Documentation lint-docs\n> \n> I expected CI to do this instead\n> \n> \tmake check-docs\n\nAh, sure, that makes even more sense. But I think the point remains,\nwhich is that your perl script is an implementation detail of the\nMakefile process. I thought the \"ci\" directory was supposed to be for\nci-specific scripts that would be driven directly by Travis, etc.\n\n-Peff\n"},{"id":"285530","messageId":"20160504221127.GB26339@sigill.intra.peff.net","threadId":"42176","inReplyTo":"CACBZZX4dYjHETCyMFQngBKoS80gkmcAZKKYc0VkE0ufaAg-gZg@mail.gmail.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-04T22:11:27Z","receivedAt":"2016-05-04T22:11:27Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 04, 2016 at 11:54:52PM +0200, Ævar Arnfjörð Bjarmason wrote:\n\n> > my @files = map { chomp; $_ } `git ls-files`;\n> \n> As a minor sidenote you can equivalently write that as:\n> \n> chomp(my @files = `git ls-files`);\n> \n> I.e. chomp itself when given a list will chomp each item of the list.\n> So no need for a map.\n\nRight, thanks, that is more readable. I use the map form reflexively\nbecause I am often doing stuff like:\n\n my @list = do {\n open(my $fh, '<', $fn);\n map { chomp; $_ }\n };\n\n(or replacing \"do\" with an actual function which is returning a\ngrotesque pipeline of grep/map, etc).\n\n-Peff\n"},{"id":"285532","messageId":"xmqq60uteacx.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"20160504220935.GA26339@sigill.intra.peff.net","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T22:17:50Z","receivedAt":"2016-05-04T22:17:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> But I think the point remains,\n> which is that your perl script is an implementation detail of the\n> Makefile process. I thought the \"ci\" directory was supposed to be for\n> ci-specific scripts that would be driven directly by Travis, etc.\n\nTrue. Documentation/ has tools like built-docdep.perl,\nhowto-index.sh, etc., so it can live next to it.\n\nThanks.\n"},{"id":"285533","messageId":"xmqq1t5he9we.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"xmqq60uteacx.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T22:27:45Z","receivedAt":"2016-05-04T22:27:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Jeff King writes:\n>\n>> But I think the point remains,\n>> which is that your perl script is an implementation detail of the\n>> Makefile process. I thought the \"ci\" directory was supposed to be for\n>> ci-specific scripts that would be driven directly by Travis, etc.\n>\n> True. Documentation/ has tools like built-docdep.perl,\n> howto-index.sh, etc., so it can live next to it.\n>\n> Thanks.\n\nGaah, the Makefile part of the final patch is wrong; we do not check\nthe included sources at all if we only passed the top-level targets'\nsources.\n"},{"id":"285547","messageId":"xmqqfutxcsio.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"xmqq1t5he9we.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-04T23:28:31Z","receivedAt":"2016-05-04T23:28:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Gaah, the Makefile part of the final patch is wrong; we do not check\n> the included sources at all if we only passed the top-level targets'\n> sources.\n\nI ended up queuing an enhanced version of File::Find based one on\n'pu', but I won't be posting it here today.\n"},{"id":"285549","messageId":"20160504234153.GA12837@sigill.intra.peff.net","threadId":"42176","inReplyTo":"xmqqfutxcsio.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-04T23:41:53Z","receivedAt":"2016-05-04T23:41:53Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 04, 2016 at 04:28:31PM -0700, Junio C Hamano wrote:\n\n> Junio C Hamano writes:\n> \n> > Gaah, the Makefile part of the final patch is wrong; we do not check\n> > the included sources at all if we only passed the top-level targets'\n> > sources.\n> \n> I ended up queuing an enhanced version of File::Find based one on\n> 'pu', but I won't be posting it here today.\n\nHmm. It seems like we should still be able to drive it from the Makefile\nusing the dependencies generated by build-docdep.\n\n-Peff\n"},{"id":"285550","messageId":"20160504235332.GA13102@sigill.intra.peff.net","threadId":"42176","inReplyTo":"20160504234153.GA12837@sigill.intra.peff.net","subject":"Re: [PATCH v4 1/2] Documentation: fix linkgit references","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2016-05-04T23:53:32Z","receivedAt":"2016-05-04T23:53:32Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 04, 2016 at 07:41:53PM -0400, Jeff King wrote:\n\n> On Wed, May 04, 2016 at 04:28:31PM -0700, Junio C Hamano wrote:\n> \n> > Junio C Hamano writes:\n> > \n> > > Gaah, the Makefile part of the final patch is wrong; we do not check\n> > > the included sources at all if we only passed the top-level targets'\n> > > sources.\n> > \n> > I ended up queuing an enhanced version of File::Find based one on\n> > 'pu', but I won't be posting it here today.\n> \n> Hmm. It seems like we should still be able to drive it from the Makefile\n> using the dependencies generated by build-docdep.\n\nHaving just read that script, it is blindly looking at \"*.txt\", so...as\nlong as that is what your script is doing (and it looks like the version\nin pu is), I don't think there's any reason to get more complicated. The\nonly difference is that build-docdep does not even bother looking in\nsubdirectories (maybe it should, since we now build stuff in technical,\nI think).\n\n-Peff\n"},{"id":"286077","messageId":"xmqqpostrg67.fsf@gitster.mtv.corp.google.com","threadId":"42176","inReplyTo":"1462351116-19308-3-git-send-email-larsxschneider@gmail.com","subject":"Re: [PATCH v4 2/2] travis-ci: build documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-05-10T17:12:00Z","receivedAt":"2016-05-10T17:12:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"larsxschneider@gmail.com writes:\n\n> From: Lars Schneider \n>\n> Build documentation as separate Travis CI job to check for\n> documentation errors.\n>\n> Signed-off-by: Lars Schneider \n> ---\n> .travis.yml | 15 +++++++++++++++\n> ci/test-documentation.sh | 14 ++++++++++++++\n> 2 files changed, 29 insertions(+)\n> create mode 100755 ci/test-documentation.sh\n>\n> diff --git a/.travis.yml b/.travis.yml\n> index 78e433b..55299bd 100644\n> --- a/.travis.yml\n> +++ b/.travis.yml\n> @@ -32,6 +32,21 @@ env:\n> # t9816 occasionally fails with \"TAP out of sequence errors\" on Travis CI OS X\n> - GIT_SKIP_TESTS=\"t9810 t9816\"\n\nCompletely offtopic, but this looks like this is made to apply to\nall archs, not limited to OSX? It of course would be ideal to see\nwhy they fail only on OSX and fix them, but shouldn't the blacklist\nat least limited to the platform with the problem?\n"},{"id":"286428","messageId":"87079FFA-996D-4F8D-A2A8-7C8917CEF545@gmail.com","threadId":"42176","inReplyTo":"xmqqpostrg67.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH v4 2/2] travis-ci: build documentation","fromName":"Lars Schneider","fromEmail":"larsxschneider@gmail.com","sentAt":"2016-05-13T06:26:19Z","receivedAt":"2016-05-13T06:26:19Z","isPatch":true,"sender":{"key":"larsxschneider@gmail.com","avatar":"https://avatars.githubusercontent.com/u/477434?v=4"},"body":"\n> On 10 May 2016, at 19:12, Junio C Hamano wrote:\n> \n> larsxschneider@gmail.com writes:\n> \n>> From: Lars Schneider \n>> \n>> Build documentation as separate Travis CI job to check for\n>> documentation errors.\n>> \n>> Signed-off-by: Lars Schneider \n>> ---\n>> .travis.yml | 15 +++++++++++++++\n>> ci/test-documentation.sh | 14 ++++++++++++++\n>> 2 files changed, 29 insertions(+)\n>> create mode 100755 ci/test-documentation.sh\n>> \n>> diff --git a/.travis.yml b/.travis.yml\n>> index 78e433b..55299bd 100644\n>> --- a/.travis.yml\n>> +++ b/.travis.yml\n>> @@ -32,6 +32,21 @@ env:\n>> # t9816 occasionally fails with \"TAP out of sequence errors\" on Travis CI OS X\n>> - GIT_SKIP_TESTS=\"t9810 t9816\"\n> \n> Completely offtopic, but this looks like this is made to apply to\n> all archs, not limited to OSX? It of course would be ideal to see\n> why they fail only on OSX and fix them, but shouldn't the blacklist\n> at least limited to the platform with the problem?\n\nAs far as I remember the test was flaky on Linux and OSX. The problem\nwas not Git. The problem was the Perforce Server \"p4d\" p4 daemon which\nwould refuse to die sometimes.\n\nI run a bigger number of Travis tests and it looks like the problem is\ngone. Out of 60 runs only just one failed and t9810 / t9816 passed:\nhttps://travis-ci.org/larsxschneider/git/jobs/129383851\n(BTW: does anyone know how I can make prove show me the running tests?\nI would like to know which test died there..)\n\nIt looks like as Perforce solved the t9810/t9816 problem with the update \nfrom 15.2 to 16.1 that we made in 31f3c86 \"travis-ci: update Git-LFS \nand P4 to the latest version\". I will post a patch to enable these tests,\nagain.\n\nThanks,\nLars\n"}]}