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

From: Jeff King <peff@peff.net>
Date: May 14, 2015, 04:32 UTC
Message-ID: <20150514043259.GC9351@peff.net>
In-Reply-To: <20150513094841.GA10518@serenity.lan>

On Wed, May 13, 2015 at 10:48:42AM +0100, John Keeping wrote:

Show 22 quoted lines

> On Wed, May 13, 2015 at 01:01:38AM -0400, Jeff King wrote:
> > Older versions of AsciiDoc would convert the "--" in
> > "--option" into an emdash. According to 565e135
> > (Documentation: quote double-dash for AsciiDoc, 2011-06-29),
> > this is fixed in AsciiDoc 8.3.0. According to bf17126, we
> > don't support anything older than 8.4.1 anyway, so we no
> > longer need to worry about quoting.
> > 
> > Even though this does not change the output at all, there
> > are a few good reasons to drop the quoting:
> > 
> >   1. It makes the source prettier to read.
> > 
> >   2. We don't quote consistently, which may be confusing when
> >      reading the source.
> > 
> >   3. Asciidoctor does not like the quoting, and renders a
> >      literal backslash.
> 
> 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.

-Peff