From: Junio C Hamano <gitster@pobox.com>
To: Todd Zullinger <tmz@pobox.com>
Cc: git@vger.kernel.org, Han-Wen Nienhuys <hanwen@google.com>
Subject: Re: [PATCH] api-argv-array.txt: Update link to string-list API
Date: Fri, 06 Oct 2017 11:38:40 +0900 [thread overview]
Message-ID: <xmqq4lrdyp8v.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: <20171005211203.11913-1-tmz@pobox.com> (Todd Zullinger's message of "Thu, 5 Oct 2017 17:12:03 -0400")
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.
next prev parent reply other threads:[~2017-10-06 2:38 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-10-05 21:12 [PATCH] api-argv-array.txt: Update link to string-list API Todd Zullinger
2017-10-06 2:38 ` Junio C Hamano [this message]
2017-10-06 3:14 ` [PATCH v2] api-argv-array.txt: Remove broken " Todd Zullinger
2017-10-06 3:45 ` Jonathan Nieder
2017-10-06 4:08 ` Todd Zullinger
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqq4lrdyp8v.fsf@gitster.mtv.corp.google.com \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=hanwen@google.com \
--cc=tmz@pobox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).