Subject: Re: [PATCH 6/8] doc: convert \--option to --option

From: Junio C Hamano <[email-masked]>
Date: Sun, 17 May 2015 11:34:19 -0700

Jeff King <[email-masked]> writes:

> On Wed, May 13, 2015 at 10:48:42AM +0100, John Keeping wrote:
>
>> If we're changing all of these files anyway, it would be nice to wrap
>> literal options in backticks as suggested in
>> Documentation/CodingGuidelines.
>
> I considered it, and I do prefer backticks. But I stopped short because
> my goal here was to make source changes that didn't have any actual
> output changes. So I'm not opposed to the output change, but it doesn't
> belong in this patch.
>
> I'm also a little hesitant just because it semes there are quite a lot
> of outliers. I'm not sure if I'm helping anything to produce a patch
> that changes a small subset of them (i.e., if we do it, we should really
> do it thoroughly).
>
> I dunno. If you want to do a patch on top, I'd be happy to look at it.

FWIW I agree 100% with what Peff said. `--options` is a good thing
to do, it does not belong to this patch, and we should aim to do so
for the entirety of the documentation, not just a small part.

The last one makes the execution of such a clean-up somewhat a
tricky affair.  We'd need to avoid conflicting with other topics in
flight (i.e. clean up quiet part of the documentation only), make
sure topics in flight do not add new breakages, and come back to
documentation other topics have changed once they stabilized.