[PATCH v2] travis-ci: build documentation

classic Classic list List threaded Threaded
53 messages Options
123
Reply | Threaded
Open this post in threaded view
|

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

Jeff King
On Tue, May 03, 2016 at 08:41:37AM -0700, Junio C Hamano wrote:

> Even though you obviously were fooled by AsciiDoctor regarding
> literal double dash {litdd}, other parts of the changes did look
> good typofixes.  Thanks for starting this.

Yeah, I stopped reading after seeing the first hunk, but I agree the
rest look trivial.

-Peff
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH v3 2/2] travis-ci: build documentation

larsxschneider
In reply to this post by Junio C Hamano

On 03 May 2016, at 17:43, Junio C Hamano <[hidden email]> wrote:

> Lars Schneider <[hidden email]> writes:
>
>> On 02 May 2016, at 22:45, Junio C Hamano <[hidden email]> wrote:
>>
>>> [hidden email] writes:
>>>
>>>> +set -e
>>>> +
>>>> +LINKS=$(grep --recursive --only-matching --no-filename --perl-regexp \
>>>> +    '(?<=linkgit:).*?(?=\[\d+\])' Documentation/* \
>>>> +    | sort -u \
>>>> +)
>>>> +
>>>> +for LINK in $LINKS; do
>>>> +    echo "Checking linkgit:$LINK..."
>>>> +    test -s Documentation/$LINK.txt
>>>> +done
>>>
>>> Please separate the above link check out of this step and do so
>>> separately after the move of test body to a separate script
>>> settles.
>>
>> OK. I also wonder if the link check should rather go to the
>> "check-docs" Makefile target?
>
> That sounds like a good direction.
>
> Which in turn means that people on all platforms are welcome to run
> it, which in turn means that the script must be even more portable,
> with avoiding GNUism and bash-isms etc.

OK. I am not that experienced with shell scripting and therefore it
is hard for me to distinguish between the different shell features.
Do you know/can you recommend the most basic shell to test/work
with? A quick Google search told me that "dash" from Ubuntu seems
to be a good baseline as it aims to support pretty much only POSIX [1].

Thanks,
Lars

[1] http://www.cyberciti.biz/faq/debian-ubuntu-linux-binbash-vs-bindash-vs-binshshell/

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH v3 2/2] travis-ci: build documentation

Eric Wong-2
Lars Schneider <[hidden email]> wrote:
> OK. I am not that experienced with shell scripting and therefore it
> is hard for me to distinguish between the different shell features.
> Do you know/can you recommend the most basic shell to test/work
> with? A quick Google search told me that "dash" from Ubuntu seems
> to be a good baseline as it aims to support pretty much only POSIX [1].

Yes, I recommend dash as your /bin/sh if you're using a
Debian-based system ("Debian Almquist shell") such as Ubuntu.

Also, the Debian "devscripts" package has a tool called
"checkbashisms" which I have also found very useful.

Maybe ksh(93) or posh could be good, too, but it's been a
while...

I also rely on checking the manpages-posix and manpages-posix-dev
in the "non-free" section of Debian ("multiverse" in Ubuntu?)
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH v3 2/2] travis-ci: build documentation

Junio C Hamano
In reply to this post by larsxschneider
Lars Schneider <[hidden email]> writes:

> A quick Google search told me that "dash" from Ubuntu seems
> to be a good baseline as it aims to support pretty much only POSIX [1].

Yeah that is a good and safe starting point.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

[PATCH v4 0/2] travis-ci: build documentation

larsxschneider
In reply to this post by larsxschneider
From: Lars Schneider <[hidden email]>

diff to v3:
* Revert the change from "{litdd}" to "--" in the documentation.
  "{litdd}" is rendered wrong in some HTML output [1], but "--"
  breaks the roff output ... I will investigate this and try to fix
  it in a future patch.
* I removed the doc link checker for now. I will try to reintroduce
  an improved version of the link checker as part of `make check-docs`
  in a future patch.

Thanks Peff and Junio for the review,
Lars

[1] https://git-scm.com/docs/git-config

Lars Schneider (2):
  Documentation: fix linkgit references
  travis-ci: build documentation

 .travis.yml                         | 15 +++++++++++++++
 Documentation/config.txt            |  4 ++--
 Documentation/git-check-ignore.txt  |  2 +-
 Documentation/git-filter-branch.txt |  4 ++--
 Documentation/git-for-each-ref.txt  |  2 +-
 ci/test-documentation.sh            | 14 ++++++++++++++
 6 files changed, 35 insertions(+), 6 deletions(-)
 create mode 100755 ci/test-documentation.sh

--
2.5.1

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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

larsxschneider
From: Lars Schneider <[hidden email]>

Signed-off-by: Lars Schneider <[hidden email]>
---
 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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

[PATCH v4 2/2] travis-ci: build documentation

larsxschneider
In reply to this post by larsxschneider
From: Lars Schneider <[hidden email]>

Build documentation as separate Travis CI job to check for
documentation errors.

Signed-off-by: Lars Schneider <[hidden email]>
---
 .travis.yml              | 15 +++++++++++++++
 ci/test-documentation.sh | 14 ++++++++++++++
 2 files changed, 29 insertions(+)
 create mode 100755 ci/test-documentation.sh

diff --git a/.travis.yml b/.travis.yml
index 78e433b..55299bd 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -32,6 +32,21 @@ env:
     # t9816 occasionally fails with "TAP out of sequence errors" on Travis CI OS X
     - GIT_SKIP_TESTS="t9810 t9816"
 
+matrix:
+  include:
+    - env: Documentation
+      os: linux
+      compiler: clang
+      addons:
+        apt:
+          packages:
+          - asciidoc
+          - xmlto
+      before_install:
+      before_script:
+      script: ci/test-documentation.sh
+      after_failure:
+
 before_install:
   - >
     case "${TRAVIS_OS_NAME:-linux}" in
diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh
new file mode 100755
index 0000000..579d540
--- /dev/null
+++ b/ci/test-documentation.sh
@@ -0,0 +1,14 @@
+#!/bin/sh
+#
+# Perform sanity checks on documentation and build it.
+#
+
+set -e
+
+make check-builtins
+make check-docs
+make doc
+
+test -s Documentation/git.html
+test -s Documentation/git.xml
+test -s Documentation/git.1
--
2.5.1

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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

larsxschneider
In reply to this post by larsxschneider

On 04 May 2016, at 10:38, [hidden email] wrote:

> From: Lars Schneider <[hidden email]>
>
> Signed-off-by: Lars Schneider <[hidden email]>
> ---
> 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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH v3 2/2] travis-ci: build documentation

Christian Couder-2
In reply to this post by larsxschneider
On Wed, May 4, 2016 at 10:04 AM, Lars Schneider
<[hidden email]> wrote:

>
> On 03 May 2016, at 17:43, Junio C Hamano <[hidden email]> wrote:
>
>> Lars Schneider <[hidden email]> writes:
>>
>>> On 02 May 2016, at 22:45, Junio C Hamano <[hidden email]> wrote:
>>>
>>>> [hidden email] writes:
>>>>
>>>>> +set -e
>>>>> +
>>>>> +LINKS=$(grep --recursive --only-matching --no-filename --perl-regexp \
>>>>> +    '(?<=linkgit:).*?(?=\[\d+\])' Documentation/* \
>>>>> +    | sort -u \
>>>>> +)
>>>>> +
>>>>> +for LINK in $LINKS; do
>>>>> +    echo "Checking linkgit:$LINK..."
>>>>> +    test -s Documentation/$LINK.txt
>>>>> +done
>>>>
>>>> Please separate the above link check out of this step and do so
>>>> separately after the move of test body to a separate script
>>>> settles.
>>>
>>> OK. I also wonder if the link check should rather go to the
>>> "check-docs" Makefile target?
>>
>> That sounds like a good direction.
>>
>> Which in turn means that people on all platforms are welcome to run
>> it, which in turn means that the script must be even more portable,
>> with avoiding GNUism and bash-isms etc.
>
> OK. I am not that experienced with shell scripting and therefore it
> is hard for me to distinguish between the different shell features.
> Do you know/can you recommend the most basic shell to test/work
> with? A quick Google search told me that "dash" from Ubuntu seems
> to be a good baseline as it aims to support pretty much only POSIX [1].

You might also want to check:

http://www.shellcheck.net/
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH v3 2/2] travis-ci: build documentation

Matthieu Moy-2
Christian Couder <[hidden email]> writes:

> You might also want to check:
>
> http://www.shellcheck.net/

Indeed, it's also an excellent tool to check for common mistakes in
shell scripts (there are many, and shellcheck is good at pointing them
out and explaining them).

http://www.shellcheck.net/

(Available online and as a command-line tool)

--
Matthieu Moy
http://www-verimag.imag.fr/~moy/
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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

Ramsay Jones-2
In reply to this post by larsxschneider


On 04/05/16 09:43, Lars Schneider wrote:

>
> On 04 May 2016, at 10:38, [hidden email] wrote:
>
>> From: Lars Schneider <[hidden email]>
>>
>> Signed-off-by: Lars Schneider <[hidden email]>
>> ---
>> 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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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

Junio C Hamano
Ramsay Jones <[hidden email]> 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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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

Junio C Hamano
Junio C Hamano <[hidden email]> 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:<page>[<section>]"
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 <[hidden email]>
---
 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
-values the `--date` option to linkgit::git-rev-list[1] takes).
+values the `--date` option to linkgit:git-rev-list[1] takes).
 
 
 EXAMPLES
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 8de3499..9c4fd68 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -402,4 +402,4 @@ on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
 
 GIT
 ---
-Part of the linkgit:git[7] suite
+Part of the linkgit:git[1] suite
diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index e44426d..75368f2 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -243,7 +243,7 @@ appended to its command line, which is one of:
 The details of the credential will be provided on the helper's stdin
 stream. The exact format is the same as the input/output format of the
 `git credential` plumbing command (see the section `INPUT/OUTPUT
-FORMAT` in linkgit:git-credential[7] for a detailed specification).
+FORMAT` in linkgit:git-credential[1] for a detailed specification).
 
 For a `get` operation, the helper should produce a list of attributes
 on stdout in the same format. A helper is free to produce a subset, or
@@ -268,4 +268,4 @@ See also
 
 linkgit:gitcredentials[7]
 
-linkgit:git-config[5] (See configuration variables `credential.*`)
+linkgit:git-config[1] (See configuration variables `credential.*`)
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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

Junio C Hamano
In reply to this post by Junio C Hamano
Junio C Hamano <[hidden email]> 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:<page>[<section>]" references
to our documentation suite.  Catch these common classes of errors:

 * Referring to Documentation/<page>.txt that does not exist.

 * Referring to a <page> outside the Git suite.  In general, <page>
   must begin with "git".

 * Listing the manual <section> incorrectly.  The first line of the
   Documentation/<page>.txt must end with "(<section>)".

with a new script ci/lint-gitlink.sh.

Signed-off-by: Junio C Hamano <[hidden email]>
---
 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 0000000..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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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:<page>[<section>]" references
> to our documentation suite.  Catch these common classes of errors:
>
>  * Referring to Documentation/<page>.txt that does not exist.
>
>  * Referring to a <page> outside the Git suite.  In general, <page>
>    must begin with "git".
>
>  * Listing the manual <section> incorrectly.  The first line of the
>    Documentation/<page>.txt must end with "(<section>)".
>
> 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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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

Junio C Hamano
Jeff King <[hidden email]> 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 <[hidden email]>
Date: Wed, 4 May 2016 11:48:06 -0700
Subject: [PATCH v2] ci: validate "gitlink:" in documentation

It is easy to add incorrect "linkgit:<page>[<section>]" references
to our documentation suite.  Catch these common classes of errors:

 * Referring to Documentation/<page>.txt that does not exist.

 * Referring to a <page> outside the Git suite.  In general, <page>
   must begin with "git".

 * Listing the manual <section> incorrectly.  The first line of the
   Documentation/<page>.txt must end with "(<section>)".

with a new script "ci/lint-gitlink".

Signed-off-by: Junio C Hamano <[hidden email]>
---
 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 0000000..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 => \&lint_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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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 => \&lint_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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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

Junio C Hamano
Jeff King <[hidden email]> 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 => \&lint_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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

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 [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
123