threads / patch / 46919

patchapi-argv-array.txt: Update link to string-list API

Subject: [PATCH] api-argv-array.txt: Update link to string-list API

## tl;dr

5 messages between Oct 5, 2017 and Oct 6, 2017. Diffs are folded; open one to read it.

replies: 4people: 3as markdown or json

Todd Zullinger· Oct 5, 2017, 21:12 UTC · lore

In 4f665f2cf3 (string-list.h: move documentation from Documentation/api/ into header, 2017-09-26) the string-list API documentation was moved into string-list.h. Fix the link from the argv-array API documentation.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---

Hi,

I noticed this broken link in the html documentation while building 2.15.0-rc0. I'm not sure whether it's better to point the link to the string-list.h file on Git Hub, remove the link, or drop the entire paragraph.

The change I made to remove the link was simply:

-The link:api-string-list.html[string-list API] is similar, but cannot be +The string-list API (documented in string-list.h) is similar, but cannot be

 Documentation/technical/api-argv-array.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Show changes to Documentation/technical/api-argv-array.txt +1 −1

diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt
index cfc063018c..1603f4a941 100644
--- a/Documentation/technical/api-argv-array.txt
+++ b/Documentation/technical/api-argv-array.txt
@@ -8,7 +8,7 @@ always NULL-terminated at the element pointed to by `argv[argc]`. This
 makes the result suitable for passing to functions expecting to receive
 argv from main(), or the link:api-run-command.html[run-command API].
 
-The link:api-string-list.html[string-list API] is similar, but cannot be
+The https://raw.githubusercontent.com/git/git/master/string-list.h[string-list API] is similar, but cannot be
 used for these purposes; instead of storing a straight string pointer,
 it contains an item structure with a `util` field that is not compatible
 with the traditional argv interface.

-- 
2.14.2

Junio C Hamano· Oct 6, 2017, 02:38 UTC · re: Todd Zullinger · lore

Re: [PATCH] api-argv-array.txt: Update link to string-list API

Todd Zullinger <tmz@pobox.com> writes:

> I noticed this broken link in the html documentation while building
> 2.15.0-rc0.  I'm not sure whether it's better to point the link to the
> string-list.h file on Git Hub, remove the link, or drop the entire
> paragraph.

Probably removing the link is the right thing to do. In the longer term, as we move more and more API documentation to the header file, we may want to have a mechanism in the documentation build procedure to extract them back to text. And at that point:

 - the API doc for argv-array is no longer in api-argv-array.txt in
   the source form;

 - however, it would be extacted from argv-array.h and made into
   manpage or html or whatever human readable format.

 - the API doc for string-list would also be extracted from
   string-list.h and made into manpage or html or whatever human
   readable format.

 - And these two can refer to each other as needed.

But we are not there yet.

> The change I made to remove the link was simply:
>
> -The link:api-string-list.html[string-list API] is similar, but cannot be
> +The string-list API (documented in string-list.h) is similar, but cannot be

This is preferrable for now, I would think.

Todd Zullinger· Oct 6, 2017, 03:14 UTC · re: Junio C Hamano · lore

[PATCH v2] api-argv-array.txt: Remove broken link to string-list API

In 4f665f2cf3 (string-list.h: move documentation from Documentation/api/ into header, 2017-09-26) the string-list API documentation was moved to string-list.h. The argv-array API documentation may follow a similar course in the future. Until then, prevent the broken link from making it to the end-user documentation.

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
Junio C Hamano wrote:

> Probably removing the link is the right thing to do.

Excellent. Thank you for detailing the likely progression as well as the preferred solution.

 Documentation/technical/api-argv-array.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Show changes to Documentation/technical/api-argv-array.txt +1 −1

diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt
index cfc063018c..870c8edbfb 100644
--- a/Documentation/technical/api-argv-array.txt
+++ b/Documentation/technical/api-argv-array.txt
@@ -8,7 +8,7 @@ always NULL-terminated at the element pointed to by `argv[argc]`. This
 makes the result suitable for passing to functions expecting to receive
 argv from main(), or the link:api-run-command.html[run-command API].
 
-The link:api-string-list.html[string-list API] is similar, but cannot be
+The string-list API (documented in string-list.h) is similar, but cannot be
 used for these purposes; instead of storing a straight string pointer,
 it contains an item structure with a `util` field that is not compatible
 with the traditional argv interface.

-- 
2.15.0.rc0

Jonathan Nieder· Oct 6, 2017, 03:45 UTC · re: Todd Zullinger · lore

Re: [PATCH v2] api-argv-array.txt: Remove broken link to string-list API

Todd Zullinger wrote:

Show 10 quoted lines

> In 4f665f2cf3 (string-list.h: move documentation from Documentation/api/
> into header, 2017-09-26) the string-list API documentation was moved to
> string-list.h.  The argv-array API documentation may follow a similar
> course in the future.  Until then, prevent the broken link from making
> it to the end-user documentation.
>
> Signed-off-by: Todd Zullinger <tmz@pobox.com>
> ---
>  Documentation/technical/api-argv-array.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Thanks for catching it. Do you use a broken link detection tool to detect this kind of issue automatically?

[...]

Show 11 quoted lines

> --- a/Documentation/technical/api-argv-array.txt
> +++ b/Documentation/technical/api-argv-array.txt
> @@ -8,7 +8,7 @@ always NULL-terminated at the element pointed to by `argv[argc]`. This
>  makes the result suitable for passing to functions expecting to receive
>  argv from main(), or the link:api-run-command.html[run-command API].
>  
> -The link:api-string-list.html[string-list API] is similar, but cannot be
> +The string-list API (documented in string-list.h) is similar, but cannot be
>  used for these purposes; instead of storing a straight string pointer,
>  it contains an item structure with a `util` field that is not compatible
>  with the traditional argv interface.

Todd Zullinger· Oct 6, 2017, 04:08 UTC · re: Jonathan Nieder · lore

Re: [PATCH v2] api-argv-array.txt: Remove broken link to string-list API

Jonathan Nieder wrote:

> Thanks for catching it.  Do you use a broken link detection tool to 
> detect this kind of issue automatically?

Yeah, in the Fedora git builds we pass all the generated html files through the linkchecker tool (http://wummel.github.io/linkchecker/).

We started using that a few months ago to help us catch broken links in case we somehow failed to include some documentation in our packaging. (After catching this minor issue I wondered if it might be useful to add something similar to the travis builds, but I haven't done any more than wonder about it. ;)

Here's the (somehwat verbose) output from the failed link check:

$ find /builddir/build/BUILDROOT/git-2.15.0-0.0.rc0.fc25.x86_64/usr/share/doc/git -name '*.html' | xargs linkchecker [...] Start checking at 2017-10-05 12:37:01-004 10 threads active, 325 links queued, 194 links in 47 URLs checked, runtime 1 seconds 10 threads active, 643 links queued, 1242 links in 197 URLs checked, runtime 6 seconds

URL `api-string-list.html' Name `string-list API' Parent URL file:///builddir/build/BUILDROOT/git-2.15.0-0.0.rc0.fc25.x86_64/usr/share/doc/git/technical/api-argv-array.html, line 745, col 31 Real URL file:///builddir/build/BUILDROOT/git-2.15.0-0.0.rc0.fc25.x86_64/usr/share/doc/git/technical/api-string-list.html Check time 0.002 seconds Result Error: URLError: <urlopen error [Errno 2] No such file or directory: '/builddir/build/BUILDROOT/git-2.15.0-0.0.rc0.fc25.x86_64/usr/share/doc/git/technical/api-string-list.html'>

Statistics:
Downloaded: 7.17MB.
Content types: 0 image, 2764 text, 0 video, 0 audio, 0 application, 29 mail and 49 other.
URL lengths: min=17, max=125, avg=96.

That's it. 2842 links in 232 URLs checked. 0 warnings found. 1 error found. Stopped checking at 2017-10-05 12:37:09-004 (8 seconds)

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
I always wanted to be a procrastinator, never got around to it.