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

[Jeff King <peff@peff.net>]

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

> 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