Re: [PATCH v4 1/2] Documentation: fix linkgit references

[Jeff King]

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 Hamano  writes:
> > 
> > > 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

[Jeff King]

On Wed, May 04, 2016 at 04:28:31PM -0700, Junio C Hamano wrote:

> Junio C Hamano  writes:
> 
> > 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 Hamano]

Junio C Hamano  writes:

> 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 Hamano]

Junio C Hamano  writes:

> 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

[Junio C Hamano]

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.
--
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 King]

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

[Jeff King]

On Wed, May 04, 2016 at 02:52:27PM -0700, Junio C Hamano wrote:

> Jeff King  writes:
> 
> > 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

[Ævar Arnfjörð Bjarmason]

On Wed, May 4, 2016 at 10:06 PM, Jeff King  wrote:
> 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

[Junio C Hamano]

Jeff King  writes:

> 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

[Jeff King]

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

[Junio C Hamano]

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

[Jeff King]

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

[Junio C Hamano]

Jeff King  writes:

> 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

[Jeff King]

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

[Junio C Hamano]

Jeff King  writes:

> 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

[Jeff King]

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 Hamano]

Junio C Hamano  writes:

> 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 Hamano]

Junio C Hamano  writes:

> 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

[Junio C Hamano]

Ramsay Jones  writes:

>>> 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

[Ramsay Jones]

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

[Jeff King]

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

[Lars Schneider]

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

[larsxschneider]

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
 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