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

[Junio C Hamano]

Todd Zullinger  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.

[PATCH] api-argv-array.txt: Update 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
into string-list.h.  Fix the link from the argv-array API documentation.

Signed-off-by: Todd Zullinger 
---

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

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