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

[Todd Zullinger]

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: 

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.

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

[Jonathan Nieder]

Todd Zullinger wrote:

> 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 
> ---
>  Documentation/technical/api-argv-array.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Jonathan Nieder 

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

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

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

[Todd Zullinger]

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

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