Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 04, 2016 at 07:41:53PM -0400, Jeff King wrote: > On Wed, May 04, 2016 at 04:28:31PM -0700, Junio C Hamano wrote: > > > Junio C Hamanowrites: > > > > > Gaah, the Makefile part of the final patch is wrong; we do not check > > > the included sources at all if we only passed the top-level targets' > > > sources. > > > > I ended up queuing an enhanced version of File::Find based one on > > 'pu', but I won't be posting it here today. > > Hmm. It seems like we should still be able to drive it from the Makefile > using the dependencies generated by build-docdep. Having just read that script, it is blindly looking at "*.txt", so...as long as that is what your script is doing (and it looks like the version in pu is), I don't think there's any reason to get more complicated. The only difference is that build-docdep does not even bother looking in subdirectories (maybe it should, since we now build stuff in technical, I think). -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 04, 2016 at 04:28:31PM -0700, Junio C Hamano wrote: > Junio C Hamanowrites: > > > Gaah, the Makefile part of the final patch is wrong; we do not check > > the included sources at all if we only passed the top-level targets' > > sources. > > I ended up queuing an enhanced version of File::Find based one on > 'pu', but I won't be posting it here today. Hmm. It seems like we should still be able to drive it from the Makefile using the dependencies generated by build-docdep. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Junio C Hamanowrites: > Gaah, the Makefile part of the final patch is wrong; we do not check > the included sources at all if we only passed the top-level targets' > sources. I ended up queuing an enhanced version of File::Find based one on 'pu', but I won't be posting it here today. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Junio C Hamanowrites: > Jeff King writes: > >> But I think the point remains, >> which is that your perl script is an implementation detail of the >> Makefile process. I thought the "ci" directory was supposed to be for >> ci-specific scripts that would be driven directly by Travis, etc. > > True. Documentation/ has tools like built-docdep.perl, > howto-index.sh, etc., so it can live next to it. > > Thanks. Gaah, the Makefile part of the final patch is wrong; we do not check the included sources at all if we only passed the top-level targets' sources. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Jeff Kingwrites: > But I think the point remains, > which is that your perl script is an implementation detail of the > Makefile process. I thought the "ci" directory was supposed to be for > ci-specific scripts that would be driven directly by Travis, etc. True. Documentation/ has tools like built-docdep.perl, howto-index.sh, etc., so it can live next to it. Thanks. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 04, 2016 at 11:54:52PM +0200, Ævar Arnfjörð Bjarmason wrote: > > my @files = map { chomp; $_ } `git ls-files`; > > As a minor sidenote you can equivalently write that as: > > chomp(my @files = `git ls-files`); > > I.e. chomp itself when given a list will chomp each item of the list. > So no need for a map. Right, thanks, that is more readable. I use the map form reflexively because I am often doing stuff like: my @list = do { open(my $fh, '<', $fn); map { chomp; $_ } }; (or replacing "do" with an actual function which is returning a grotesque pipeline of grep/map, etc). -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 04, 2016 at 02:52:27PM -0700, Junio C Hamano wrote: > Jeff Kingwrites: > > > This dependency feels funny. Wouldn't CI want to invoke this as: > > > > make -C Documentation lint-docs > > I expected CI to do this instead > > make check-docs Ah, sure, that makes even more sense. But I think the point remains, which is that your perl script is an implementation detail of the Makefile process. I thought the "ci" directory was supposed to be for ci-specific scripts that would be driven directly by Travis, etc. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 4, 2016 at 10:06 PM, Jeff Kingwrote: > Would: > > open(my $files, '-|', qw(git ls-files)); > while (<$files>) { > chomp; > ... > } > > make sense? Or a simpler but non-streaming spelling: > > my @files = map { chomp; $_ } `git ls-files`; As a minor sidenote you can equivalently write that as: chomp(my @files = `git ls-files`); I.e. chomp itself when given a list will chomp each item of the list. So no need for a map. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Jeff Kingwrites: > This dependency feels funny. Wouldn't CI want to invoke this as: > > make -C Documentation lint-docs I expected CI to do this instead make check-docs -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 04, 2016 at 02:34:23PM -0700, Junio C Hamano wrote: > Third time's a charm, perhaps? > > -- >8 -- > Subject: [PATCH] ci: validate "gitlink:" in documentation > > It is easy to add incorrect "linkgit:[]" references > to our documentation suite. Catch these common classes of errors: > > * Referring to Documentation/.txt that does not exist. > > * Referring to a outside the Git suite. In general, >must begin with "git". > > * Listing the manual incorrectly. The first line of the >Documentation/.txt must end with "()". > > with a new script "ci/lint-gitlink", and drive it from "make check-docs". > > Signed-off-by: Junio C Hamano> --- This looks good to me. Two minor nits that may not be worth addressing: > +lint-docs:: > + $(QUIET_LINT)$(foreach txt,$(patsubst %.html,%.txt,$(DOC_HTML)), \ > + ../ci/lint-gitlink $(txt)) > + This dependency feels funny. Wouldn't CI want to invoke this as: make -C Documentation lint-docs IOW, Documentation owns the script (just like t/ owns its own lint scripts like check-non-portable-shell.pl), and CI always just triggers the make-driven checks, just as a normal developer would? > +sub lint { > + my ($file) = @_; > + open my $fh, "<", $file > + or return; > + while (<$fh>) { > + my $where = "$file:$."; > [... actual linting of line ...] > +} > + > +for (@ARGV) { > + lint($_); > +} The usual perl way here would be: while(<>) { my $where = "$ARGV:$."; ... actual linting of line ... } where "<>" automagically reads from files on the command-line or stdin if none were specified (and sets $ARGV as appropriate). But maybe you prefer not to handle the stdin case (it is a benefit sometimes, but an annoyance if you accidentally end up with an empty file list). -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Third time's a charm, perhaps? -- >8 -- Subject: [PATCH] ci: validate "gitlink:" in documentation It is easy to add incorrect "linkgit:[]" references to our documentation suite. Catch these common classes of errors: * Referring to Documentation/.txt that does not exist. * Referring to a outside the Git suite. In general, must begin with "git". * Listing the manual incorrectly. The first line of the Documentation/.txt must end with "()". with a new script "ci/lint-gitlink", and drive it from "make check-docs". Signed-off-by: Junio C Hamano--- Documentation/Makefile | 5 + Makefile | 1 + ci/lint-gitlink| 56 ++ 3 files changed, 62 insertions(+) create mode 100755 ci/lint-gitlink diff --git a/Documentation/Makefile b/Documentation/Makefile index 3e39e28..e9cd43d 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -204,6 +204,7 @@ ifndef V QUIET_DBLATEX = @echo ' ' DBLATEX $@; QUIET_XSLTPROC = @echo ' ' XSLTPROC $@; QUIET_GEN = @echo ' ' GEN $@; + QUIET_LINT = @echo ' ' LINT $@; QUIET_STDERR= 2> /dev/null QUIET_SUBDIR0 = +@subdir= QUIET_SUBDIR1 = ;$(NO_SUBDIR) echo ' ' SUBDIR $$subdir; \ @@ -427,4 +428,8 @@ quick-install-html: require-htmlrepo print-man1: @for i in $(MAN1_TXT); do echo $$i; done +lint-docs:: + $(QUIET_LINT)$(foreach txt,$(patsubst %.html,%.txt,$(DOC_HTML)), \ + ../ci/lint-gitlink $(txt)) + .PHONY: FORCE diff --git a/Makefile b/Makefile index 2742a69..61bd0ab 100644 --- a/Makefile +++ b/Makefile @@ -2496,6 +2496,7 @@ ALL_COMMANDS += git-gui git-citool .PHONY: check-docs check-docs:: + $(MAKE) -C Documentation lint-docs @(for v in $(ALL_COMMANDS); \ do \ case "$$v" in \ diff --git a/ci/lint-gitlink b/ci/lint-gitlink new file mode 100755 index 000..6b6bf91 --- /dev/null +++ b/ci/lint-gitlink @@ -0,0 +1,56 @@ +#!/usr/bin/perl + +my $found_errors = 0; + +sub report { + my ($where, $what, $error) = @_; + print "$where: $error: $what\n"; + $found_errors = 1; +} + +sub grab_section { + my ($page) = @_; + open my $fh, "<", "$page.txt"; + my $firstline = <$fh>; + chomp $firstline; + close $fh; + my ($section) = ($firstline =~ /.*\((\d)\)$/); + return $section; +} + +sub lint { + my ($file) = @_; + open my $fh, "<", $file + or return; + while (<$fh>) { + my $where = "$file:$."; + while (s/linkgit:((.*?)\[(\d)\])//) { + my ($target, $page, $section) = ($1, $2, $3); + + # De-AsciiDoc + $page =~ s/{litdd}/--/g; + + if ($page !~ /^git/) { + report($where, $target, "nongit link"); + next; + } + if (! -f "$page.txt") { + report($where, $target, "no such source"); + next; + } + $real_section = grab_section($page); + if ($real_section != $section) { + report($where, $target, + "wrong section (should be $real_section)"); + next; + } + } + } + close $fh; +} + +for (@ARGV) { + lint($_); +} + +exit $found_errors; -- 2.8.2-498-g6350fe8 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 04, 2016 at 02:15:39PM -0700, Junio C Hamano wrote: > > make sense? Or a simpler but non-streaming spelling: > > > > my @files = map { chomp; $_ } `git ls-files`; > > I forgot to say that I wanted not to rely on "git" (i.e. OK to use > this on tarball extract). Oh, that's a good idea. > > Or just taking the list of files on the command line as your original > > did, and feeding `ls-files` from the caller. That also lets you do > > "link-gitlink git-foo.txt", etc. > > Yes, I think that is the most sensible. Yeah, and then the Makefile can drive it from $(MAN_TXT), etc, without requiring git (which I think is what you were getting at, but just spelling it out for myself and the list). -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Jeff Kingwrites: > On Wed, May 04, 2016 at 12:57:31PM -0700, Junio C Hamano wrote: > >> > Is it worth just making this a perl script, rather than a shell script >> > with a giant inline perl script? Perl is actually really good at doing >> > that "grep" as it reads the file. :) >> >> OK. > > Hmm. This new version uses File::Find: > >> +sub lint_it { >> +lint($File::Find::name) if -f; >> +} >> + >> +find({ wanted => \_it, no_chdir => 1 }, "Documentation"); > > That will inspect non-source files, too. > > Would: > > open(my $files, '-|', qw(git ls-files)); > while (<$files>) { > chomp; > ... > } > > make sense? Or a simpler but non-streaming spelling: > > my @files = map { chomp; $_ } `git ls-files`; I forgot to say that I wanted not to rely on "git" (i.e. OK to use this on tarball extract). > Or just taking the list of files on the command line as your original > did, and feeding `ls-files` from the caller. That also lets you do > "link-gitlink git-foo.txt", etc. Yes, I think that is the most sensible. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 04, 2016 at 12:57:31PM -0700, Junio C Hamano wrote: > > Is it worth just making this a perl script, rather than a shell script > > with a giant inline perl script? Perl is actually really good at doing > > that "grep" as it reads the file. :) > > OK. Hmm. This new version uses File::Find: > +sub lint_it { > + lint($File::Find::name) if -f; > +} > + > +find({ wanted => \_it, no_chdir => 1 }, "Documentation"); That will inspect non-source files, too. Would: open(my $files, '-|', qw(git ls-files)); while (<$files>) { chomp; ... } make sense? Or a simpler but non-streaming spelling: my @files = map { chomp; $_ } `git ls-files`; Or just taking the list of files on the command line as your original did, and feeding `ls-files` from the caller. That also lets you do "link-gitlink git-foo.txt", etc. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Jeff Kingwrites: > Likewise, I think we could build the whole HTML source and then actually > just look for broken links in it. But that script would probably end up > looking similar to this one, with s/linkgit/href/. But it does more > directly measure what we want, which is that the rendered doc is usable; I debated about this myself, but chose to inspect the source material, as that approach is easier to give actionable lint output to the user that points out the file:lineno to be corrected. > it would catch something like using "--" instead of "{litdd}". That is true indeed. With the "source" approach, that would indeed be harder. >> +#!/bin/sh >> + >> +git grep -l linkgit: Documentation/ | >> +while read path >> +do >> +perl -e ' > > Is it worth just making this a perl script, rather than a shell script > with a giant inline perl script? Perl is actually really good at doing > that "grep" as it reads the file. :) OK. -- >8 -- From: Junio C Hamano Date: Wed, 4 May 2016 11:48:06 -0700 Subject: [PATCH v2] ci: validate "gitlink:" in documentation It is easy to add incorrect "linkgit:[]" references to our documentation suite. Catch these common classes of errors: * Referring to Documentation/.txt that does not exist. * Referring to a outside the Git suite. In general, must begin with "git". * Listing the manual incorrectly. The first line of the Documentation/.txt must end with "()". with a new script "ci/lint-gitlink". Signed-off-by: Junio C Hamano --- ci/lint-gitlink | 60 + 1 file changed, 60 insertions(+) create mode 100755 ci/lint-gitlink diff --git a/ci/lint-gitlink b/ci/lint-gitlink new file mode 100755 index 000..bb73e89 --- /dev/null +++ b/ci/lint-gitlink @@ -0,0 +1,60 @@ +#!/usr/bin/perl + +use File::Find; + +my $found_errors = 0; + +sub report { + my ($where, $what, $error) = @_; + print "$where: $error: $what\n"; + $found_errors = 1; +} + +sub grab_section { + my ($page) = @_; + open my $fh, "<", "Documentation/$page.txt"; + my $firstline = <$fh>; + chomp $firstline; + close $fh; + my ($section) = ($firstline =~ /.*\((\d)\)$/); + return $section; +} + +sub lint { + my ($file) = @_; + open my $fh, "<", $file + or return; + while (<$fh>) { + my $where = "$file:$."; + while (s/linkgit:((.*?)\[(\d)\])//) { + my ($target, $page, $section) = ($1, $2, $3); + + # De-AsciiDoc + $page =~ s/{litdd}/--/g; + + if ($page !~ /^git/) { + report($where, $target, "nongit link"); + next; + } + if (! -f "Documentation/$page.txt") { + report($where, $target, "no such source"); + next; + } + $real_section = grab_section($page); + if ($real_section != $section) { + report($where, $target, + "wrong section (should be $real_section)"); + next; + } + } + } + close $fh; +} + +sub lint_it { + lint($File::Find::name) if -f; +} + +find({ wanted => \_it, no_chdir => 1 }, "Documentation"); + +exit $found_errors; -- 2.8.2-498-g6350fe8 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 04, 2016 at 11:52:52AM -0700, Junio C Hamano wrote: > > I do not think there is any false positive above, so perhaps the > > checker script below can be used as the link checker we discussed? > > -- >8 -- > Subject: [PATCH] ci: validate "gitlink:" in documentation > > It is easy to add incorrect "linkgit:[]" references > to our documentation suite. Catch these common classes of errors: > > * Referring to Documentation/.txt that does not exist. > > * Referring to a outside the Git suite. In general, >must begin with "git". > > * Listing the manual incorrectly. The first line of the >Documentation/.txt must end with "()". > > with a new script ci/lint-gitlink.sh. It seems like this is something we _should_ be able to do while asciidoc is actually expanding the macro, rather than as a separate step. But: 1. I don't think stock asciidoc has this much flexibility in its macros. 2. There are some ordering questions (e.g., while building "foo.1", "bar.1" may not be built yet, so we still have to massage requests for "bar.1" into "bar.txt". Likewise, I think we could build the whole HTML source and then actually just look for broken links in it. But that script would probably end up looking similar to this one, with s/linkgit/href/. But it does more directly measure what we want, which is that the rendered doc is usable; it would catch something like using "--" instead of "{litdd}". > +#!/bin/sh > + > +git grep -l linkgit: Documentation/ | > +while read path > +do > + perl -e ' Is it worth just making this a perl script, rather than a shell script with a giant inline perl script? Perl is actually really good at doing that "grep" as it reads the file. :) Besides being slightly more efficient (reading the files only once rather than filtering once via grep and then re-reading via perl). But more importantly, it avoids a layer of quoting, which makes it less likely to make a mistake by using single-quote in the perl script (I do not see any errors in what you wrote, though). -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Junio C Hamanowrites: > I do not think there is any false positive above, so perhaps the > checker script below can be used as the link checker we discussed? -- >8 -- Subject: [PATCH] ci: validate "gitlink:" in documentation It is easy to add incorrect "linkgit:[]" references to our documentation suite. Catch these common classes of errors: * Referring to Documentation/.txt that does not exist. * Referring to a outside the Git suite. In general, must begin with "git". * Listing the manual incorrectly. The first line of the Documentation/.txt must end with "()". with a new script ci/lint-gitlink.sh. Signed-off-by: Junio C Hamano --- ci/lint-gitlink.sh | 47 +++ 1 file changed, 47 insertions(+) create mode 100755 ci/lint-gitlink.sh diff --git a/ci/lint-gitlink.sh b/ci/lint-gitlink.sh new file mode 100755 index 000..2379626 --- /dev/null +++ b/ci/lint-gitlink.sh @@ -0,0 +1,47 @@ +#!/bin/sh + +git grep -l linkgit: Documentation/ | +while read path +do + perl -e ' + sub report { + my ($where, $what, $error) = @_; + print "$where: $error: $what\n"; + } + + sub grab_section { + my ($page) = @_; + open my $fh, "<", "Documentation/$page.txt"; + my $firstline = <$fh>; + chomp $firstline; + close $fh; + my ($section) = ($firstline =~ /.*\((\d)\)$/); + return $section; + } + + while (<>) { + my $where = "$ARGV:$."; + while (s/linkgit:((.*?)\[(\d)\])//) { + my ($target, $page, $section) = ($1, $2, $3); + + # De-AsciiDoc + $page =~ s/{litdd}/--/g; + + if ($page !~ /^git/) { + report($where, $target, "nongit link"); + next; + } + if (! -f "Documentation/$page.txt") { + report($where, $target, "no such source"); + next; + } + $real_section = grab_section($page); + if ($real_section != $section) { + report($where, $target, + "wrong section (should be $real_section)"); + next; + } + } + } + ' "$path" +done -- 2.8.2-498-g6350fe8 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Junio C Hamanowrites: > So I used the script attached at the bottom to audit the whole > thing, and the result is here. > ... While I was at it, I just did this to make the documentation set lint clean. -- >8 -- There are a handful of incorrect "linkgit:[]" instances in our documentation set. * Some have an extra colon after "linkgit:"; fix them by removing the extra colon; * Some refer to a page outside the Git suite, namely curl(1); fix them by using the `curl(1)` that already appears on the same page for the same purpose of referring the readers to its manual page. * Some spell the name of the page incorrectly, e.g. "rev-list" when they mean "git-rev-list"; fix them. * Some list the manual section incorrectly; fix them to make sure they match what is at the top of the target of the link. Signed-off-by: Junio C Hamano --- Documentation/config.txt| 4 ++-- Documentation/diff-options.txt | 2 +- Documentation/everyday.txto | 2 +- Documentation/git-check-ignore.txt | 2 +- Documentation/git-filter-branch.txt | 2 +- Documentation/git-for-each-ref.txt | 2 +- Documentation/git-notes.txt | 2 +- Documentation/technical/api-credentials.txt | 4 ++-- 8 files changed, 10 insertions(+), 10 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 42d2b50..f37e16b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1494,7 +1494,7 @@ gui.diffContext:: made by the linkgit:git-gui[1]. The default is "5". gui.displayUntracked:: - Determines if linkgit::git-gui[1] shows untracked files + Determines if linkgit:git-gui[1] shows untracked files in the file list. The default is "true". gui.encoding:: @@ -1659,7 +1659,7 @@ http.cookieFile:: File containing previously stored cookie lines which should be used in the Git http session, if they match the server. The file format of the file to read cookies from should be plain HTTP headers or - the Netscape/Mozilla cookie file format (see linkgit:curl[1]). + the Netscape/Mozilla cookie file format (see `curl(1)`). NOTE that the file specified with http.cookieFile is only used as input unless http.saveCookies is set. diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 4b0318e..3cb3015 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -271,7 +271,7 @@ For example, `--word-diff-regex=.` will treat each character as a word and, correspondingly, show differences character by character. + The regex can also be set via a diff driver or configuration option, see -linkgit:gitattributes[1] or linkgit:git-config[1]. Giving it explicitly +linkgit:gitattributes[5] or linkgit:git-config[1]. Giving it explicitly overrides any diff driver or configuration setting. Diff drivers override configuration settings. diff --git a/Documentation/everyday.txto b/Documentation/everyday.txto index c5047d8..ae555bd 100644 --- a/Documentation/everyday.txto +++ b/Documentation/everyday.txto @@ -1,7 +1,7 @@ Everyday Git With 20 Commands Or So === -This document has been moved to linkgit:giteveryday[1]. +This document has been moved to linkgit:giteveryday[7]. Please let the owners of the referring site know so that they can update the link you clicked to get here. diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index e94367a..611754f 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -112,7 +112,7 @@ EXIT STATUS SEE ALSO linkgit:gitignore[5] -linkgit:gitconfig[5] +linkgit:git-config[1] linkgit:git-ls-files[1] GIT diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 73fd9e8..003731f 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -205,7 +205,7 @@ to other tags will be rewritten to point to the underlying commit. Remap to ancestor ~ -By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the +By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can limit the set of revisions which get rewritten. However, positive refs on the command line are distinguished: we don't let them be excluded by such limiters. For this purpose, they are instead rewritten to point at the nearest ancestor that diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index c52578b..d9d406d 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -179,7 +179,7 @@ returns an empty string instead. As a special case for the date-type fields, you may specify a format for the date by adding `:` followed by date format name (see the
Re: [PATCH v4 1/2] Documentation: fix linkgit references
Ramsay Joneswrites: >>> diff --git a/Documentation/git-check-ignore.txt >>> b/Documentation/git-check-ignore.txt >>> index e94367a..9a85998 100644 >>> --- a/Documentation/git-check-ignore.txt >>> +++ b/Documentation/git-check-ignore.txt >>> @@ -112,7 +112,7 @@ EXIT STATUS >>> SEE ALSO >>> >>> linkgit:gitignore[5] >>> -linkgit:gitconfig[5] >>> +linkgit:git-config[5] > > I think Junio already noted, git-config is in section 1 not 5. Not just that, I am afraid. This came from 368aa529 (add git-check-ignore sub-command, 2013-01-06) and it added these: +linkgit:gitignore[5] +linkgit:gitconfig[5] +linkgit:git-ls-files[5] The last one was later corrected, but who knows what other mistakes there are? So I used the script attached at the bottom to audit the whole thing, and the result is here. -- >8 -- Documentation/config.txt:1497: nongit link: :git-gui[1] Documentation/config.txt:1662: nongit link: curl[1] Documentation/diff-options.txt:274: wrong section (should be 5): gitattributes[1] Documentation/git-check-ignore.txt:115: no such source: gitconfig[5] Documentation/git-filter-branch.txt:208: nongit link: rev-list[1] Documentation/git-for-each-ref.txt:182: nongit link: :git-rev-list[1] Documentation/git-notes.txt:405: wrong section (should be 1): git[7] Documentation/technical/api-credentials.txt:246: wrong section (should be 1): git-credential[7] Documentation/technical/api-credentials.txt:271: wrong section (should be 1): git-config[5] -- 8< -- I do not think there is any false positive above, so perhaps the checker script below can be used as the link checker we discussed? -- >8 -- #!/bin/sh git grep -l linkgit: Documentation/ | while read path do perl -e ' sub report { my ($where, $what, $error) = @_; print "$where: $error: $what\n"; } sub grab_section { my ($page) = @_; open my $fh, "<", "Documentation/$page.txt"; my $firstline = <$fh>; chomp $firstline; close $fh; my ($section) = ($firstline =~ /.*\((\d)\)$/); return $section; } while (<>) { my $where = "$ARGV:$."; while (s/linkgit:((.*?)\[(\d)\])//) { my ($target, $page, $section) = ($1, $2, $3); # De-AsciiDoc $page =~ s/{litdd}/--/g; if ($page !~ /^git/) { report($where, $target, "nongit link"); next; } if (! -f "Documentation/$page.txt") { report($where, $target, "no such source"); next; } $real_section = grab_section($page); if ($real_section != $section) { report($where, $target, "wrong section (should be $real_section)"); next; } } } ' "$path" done -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On 04/05/16 09:43, Lars Schneider wrote: > > On 04 May 2016, at 10:38, larsxschnei...@gmail.com wrote: > >> From: Lars Schneider>> >> Signed-off-by: Lars Schneider >> --- >> Documentation/config.txt| 4 ++-- >> Documentation/git-check-ignore.txt | 2 +- >> Documentation/git-filter-branch.txt | 4 ++-- >> Documentation/git-for-each-ref.txt | 2 +- >> 4 files changed, 6 insertions(+), 6 deletions(-) >> >> diff --git a/Documentation/config.txt b/Documentation/config.txt >> index c7bbe98..5683400 100644 >> --- a/Documentation/config.txt >> +++ b/Documentation/config.txt >> @@ -1494,7 +1494,7 @@ gui.diffContext:: >> made by the linkgit:git-gui[1]. The default is "5". >> >> gui.displayUntracked:: >> -Determines if linkgit::git-gui[1] shows untracked files >> +Determines if linkgit:git-gui[1] shows untracked files >> in the file list. The default is "true". >> >> gui.encoding:: >> @@ -1665,7 +1665,7 @@ http.cookieFile:: >> File containing previously stored cookie lines which should be used >> in the Git http session, if they match the server. The file format >> of the file to read cookies from should be plain HTTP headers or >> -the Netscape/Mozilla cookie file format (see linkgit:curl[1]). >> +the Netscape/Mozilla cookie file format (see `curl(1)`). >> NOTE that the file specified with http.cookieFile is only used as >> input unless http.saveCookies is set. >> >> diff --git a/Documentation/git-check-ignore.txt >> b/Documentation/git-check-ignore.txt >> index e94367a..9a85998 100644 >> --- a/Documentation/git-check-ignore.txt >> +++ b/Documentation/git-check-ignore.txt >> @@ -112,7 +112,7 @@ EXIT STATUS >> SEE ALSO >> >> linkgit:gitignore[5] >> -linkgit:gitconfig[5] >> +linkgit:git-config[5] I think Junio already noted, git-config is in section 1 not 5. ATB, Ramsay Jones -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On Wed, May 04, 2016 at 10:43:04AM +0200, Lars Schneider wrote: > > diff --git a/Documentation/git-filter-branch.txt > > b/Documentation/git-filter-branch.txt > > index 73fd9e8..6538cb1 100644 > > --- a/Documentation/git-filter-branch.txt > > +++ b/Documentation/git-filter-branch.txt > > @@ -205,8 +205,8 @@ to other tags will be rewritten to point to the > > underlying commit. > > Remap to ancestor > > ~ > > > > -By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit > > the > > -set of revisions which get rewritten. However, positive refs on the command > > +By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can > > limit > > +the set of revisions which get rewritten. However, positive refs on the > > command > > All other linkgit fixes seem legimiate to me although I am not sure of this > case > > -linkgit:rev-list[1] > +linkgit:git-rev-list[1] > > "rev-list" works but I think "git-rev-list" would be the canonical form? > See: https://git-scm.com/docs/git-filter-branch It should definitely be "git-rev-list". The "linkgit" macro will format whatever text you feed it. For the manpages, that doesn't matter, because they don't actually hyperlink. But for other formats (like HTML), using just "rev-list" will generate a broken link. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v4 1/2] Documentation: fix linkgit references
On 04 May 2016, at 10:38, larsxschnei...@gmail.com wrote: > From: Lars Schneider> > Signed-off-by: Lars Schneider > --- > Documentation/config.txt| 4 ++-- > Documentation/git-check-ignore.txt | 2 +- > Documentation/git-filter-branch.txt | 4 ++-- > Documentation/git-for-each-ref.txt | 2 +- > 4 files changed, 6 insertions(+), 6 deletions(-) > > diff --git a/Documentation/config.txt b/Documentation/config.txt > index c7bbe98..5683400 100644 > --- a/Documentation/config.txt > +++ b/Documentation/config.txt > @@ -1494,7 +1494,7 @@ gui.diffContext:: > made by the linkgit:git-gui[1]. The default is "5". > > gui.displayUntracked:: > - Determines if linkgit::git-gui[1] shows untracked files > + Determines if linkgit:git-gui[1] shows untracked files > in the file list. The default is "true". > > gui.encoding:: > @@ -1665,7 +1665,7 @@ http.cookieFile:: > File containing previously stored cookie lines which should be used > in the Git http session, if they match the server. The file format > of the file to read cookies from should be plain HTTP headers or > - the Netscape/Mozilla cookie file format (see linkgit:curl[1]). > + the Netscape/Mozilla cookie file format (see `curl(1)`). > NOTE that the file specified with http.cookieFile is only used as > input unless http.saveCookies is set. > > diff --git a/Documentation/git-check-ignore.txt > b/Documentation/git-check-ignore.txt > index e94367a..9a85998 100644 > --- a/Documentation/git-check-ignore.txt > +++ b/Documentation/git-check-ignore.txt > @@ -112,7 +112,7 @@ EXIT STATUS > SEE ALSO > > linkgit:gitignore[5] > -linkgit:gitconfig[5] > +linkgit:git-config[5] > linkgit:git-ls-files[1] > > GIT > diff --git a/Documentation/git-filter-branch.txt > b/Documentation/git-filter-branch.txt > index 73fd9e8..6538cb1 100644 > --- a/Documentation/git-filter-branch.txt > +++ b/Documentation/git-filter-branch.txt > @@ -205,8 +205,8 @@ to other tags will be rewritten to point to the > underlying commit. > Remap to ancestor > ~ > > -By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit > the > -set of revisions which get rewritten. However, positive refs on the command > +By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can > limit > +the set of revisions which get rewritten. However, positive refs on the > command All other linkgit fixes seem legimiate to me although I am not sure of this case -linkgit:rev-list[1] +linkgit:git-rev-list[1] "rev-list" works but I think "git-rev-list" would be the canonical form? See: https://git-scm.com/docs/git-filter-branch > line are distinguished: we don't let them be excluded by such limiters. For > this purpose, they are instead rewritten to point at the nearest ancestor that > was not excluded. > diff --git a/Documentation/git-for-each-ref.txt > b/Documentation/git-for-each-ref.txt > index c52578b..d9d406d 100644 > --- a/Documentation/git-for-each-ref.txt > +++ b/Documentation/git-for-each-ref.txt > @@ -179,7 +179,7 @@ returns an empty string instead. > > As a special case for the date-type fields, you may specify a format for > the date by adding `:` followed by date format name (see the > -values the `--date` option to linkgit::git-rev-list[1] takes). > +values the `--date` option to linkgit:git-rev-list[1] takes). > > > EXAMPLES > -- > 2.5.1 > -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v4 1/2] Documentation: fix linkgit references
From: Lars SchneiderSigned-off-by: Lars Schneider --- Documentation/config.txt| 4 ++-- Documentation/git-check-ignore.txt | 2 +- Documentation/git-filter-branch.txt | 4 ++-- Documentation/git-for-each-ref.txt | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index c7bbe98..5683400 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1494,7 +1494,7 @@ gui.diffContext:: made by the linkgit:git-gui[1]. The default is "5". gui.displayUntracked:: - Determines if linkgit::git-gui[1] shows untracked files + Determines if linkgit:git-gui[1] shows untracked files in the file list. The default is "true". gui.encoding:: @@ -1665,7 +1665,7 @@ http.cookieFile:: File containing previously stored cookie lines which should be used in the Git http session, if they match the server. The file format of the file to read cookies from should be plain HTTP headers or - the Netscape/Mozilla cookie file format (see linkgit:curl[1]). + the Netscape/Mozilla cookie file format (see `curl(1)`). NOTE that the file specified with http.cookieFile is only used as input unless http.saveCookies is set. diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index e94367a..9a85998 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -112,7 +112,7 @@ EXIT STATUS SEE ALSO linkgit:gitignore[5] -linkgit:gitconfig[5] +linkgit:git-config[5] linkgit:git-ls-files[1] GIT diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 73fd9e8..6538cb1 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -205,8 +205,8 @@ to other tags will be rewritten to point to the underlying commit. Remap to ancestor ~ -By using linkgit:rev-list[1] arguments, e.g., path limiters, you can limit the -set of revisions which get rewritten. However, positive refs on the command +By using linkgit:git-rev-list[1] arguments, e.g., path limiters, you can limit +the set of revisions which get rewritten. However, positive refs on the command line are distinguished: we don't let them be excluded by such limiters. For this purpose, they are instead rewritten to point at the nearest ancestor that was not excluded. diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index c52578b..d9d406d 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -179,7 +179,7 @@ returns an empty string instead. As a special case for the date-type fields, you may specify a format for the date by adding `:` followed by date format name (see the -values the `--date` option to linkgit::git-rev-list[1] takes). +values the `--date` option to linkgit:git-rev-list[1] takes). EXAMPLES -- 2.5.1 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html