Re: [PATCH v3 1/5] doc: add documentation for OPT_STRING_LIST

From: Jacob Keller <jacob.keller@gmail.com>
Date: Jan 18, 2017, 21:10 UTC
Message-ID: <CA+P7+xrv35w0RYNEZ88K_EWC57A4utBQTibtw6+TJBCtzA9Ybw@mail.gmail.com>
In-Reply-To: <xmqq37gg9moc.fsf@gitster.mtv.corp.google.com>

On Wed, Jan 18, 2017 at 11:45 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 5 quoted lines

>
> I do not know if it is clear enough that 'option' in the last
> sentence is a placeholder.  I then wondered if spelling it as
> `--no-<long>` would make it a bit clearer, but that is ugly.
>

To be fair, this is exactly how the rest of the doc spells these things, so I would rather be consistent with the doc as is, and a future patch could clean this up. See OPT_SET_INT, for an example of `--no-option`.

Show 8 quoted lines

> The "Reset the list" is an instruction to the end-users who interact
> with a program written by readers of this document using
> OPT_STRING_LIST(), and it feels a bit out of place.  Perhaps
>
>         End users can reset the list by negating the option,
>         i.e. passing "--no-<long>", on the command line.
>
> I dunno.

Maybe we can rephrase this "The list is reset via `--no-option`"?

Thanks, Jake