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

From: Junio C Hamano <gitster@pobox.com>
Date: May 17, 2015, 18:34 UTC
Message-ID: <xmqqzj53catw.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20150514043259.GC9351@peff.net>

Jeff King <peff@peff.net> writes:

Show 17 quoted lines

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