Re: [PATCH 3/6] doc: typeset -- as litteral

From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: Jun 28, 2016, 08:26 UTC
Message-ID: <vpqa8i5zpkd.fsf@anie.imag.fr>
In-Reply-To: <20160627191005.GD9594@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 8 quoted lines

> On Mon, Jun 27, 2016 at 07:46:20PM +0200, Matthieu Moy wrote:
>
>> Subject: Re: [PATCH 3/6] doc: typeset -- as litteral
>
> s/litteral/literal/
>
> I can hardly blame you, though. I think English stole the word from
> French and then switched its spelling. :)

I never remember about double consonent, and indeed the fact that French and English have different spelling for the same words doesn't help (addition Vs adition, traffic Vs trafic, ...) ;-).

Fixed in v2.

> You may also want put quotes around "--" to make it clear that you are
> talking about it as punctuation, not using it as such in your
> sentence.

Done.

> I read all the way through patch 6, and they all look good to me (though
> the "litteral" typo appears again later). I won't bother responding to
> each separately.

Should all be fixed now.

> I do notice that your patterns are finding existing items marked with
> single-quotes. We may have other cases lurking that are not quoted at
> all (but should be).

Yes, this series (and tr/doc-tt) clearly catch just the low-hanging fruits. Having forward quotes in the existing text makes it clear that the author wanted some kind of formatting, and hence make regex-based replacement rather reliable (very few false positive).

Unquoted stuff are more problematic since you can have for example

  You should run `git foo --bar boz`

or multi-lines formatted code blocks, and a naive regex would match --bar.

> I think those could be a separate series, but if anybody wants to look
> for them, I think searching for "\--" will help (a literal double-dash
> needs that to avoid becoming an emdash).

The rule seems to be more complex than this, for example "Implies --porcelain" in https://git-scm.com/docs/git-blame is properly typeset, although the source code has no escaping or quoting.

I'll keep these out of the series for now, I've added more ideas to

  https://git.wiki.kernel.org/index.php/SmallProjectsIdeas#Fix_asciidoc_formatting_in_documentation

I may come back to this later.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/