Re: [PATCH 1/2] git-fast-import.txt: improve documentation for quoted paths

From: Jeff King <peff@peff.net>
Date: Nov 29, 2012, 18:54 UTC
Message-ID: <20121129185404.GC17309@sigill.intra.peff.net>
In-Reply-To: <vpqhao8gsaj.fsf@grenoble-inp.fr>

On Thu, Nov 29, 2012 at 07:47:32PM +0100, Matthieu Moy wrote:

Show 8 quoted lines

> Jeff King <peff@peff.net> writes:
> 
> > So technically, your modification to the beginning of the sentence is
> > not correct.
> 
> I'd say the resulting sentence is somehow incorrect, but not more than
> the previous one (both say "if ..." without really telling what the
> condition was).

That's fair. There is a lot left unsaid in the original. :)

Show 6 quoted lines

> >> If an `LF`, backslash or double quote must be encoded
> >                        ^
> >                        missing comma as list delimiter
> 
> Google tells me that my version was UK-correct but not US-correct. As
> french, I have no opinion on the subject, I take yours ;-).

Thanks, I had a vague recollection that it might be regional. I probably should have looked it up myself.

Show 11 quoted lines

> How about this:
> 
> A path can use the C-style string quoting (this is accepted in all
> cases and mandatory if the filename starts with double quote or
> contains `LF`). In C-style quoting, `LF`, backslash, and double quote
> characters must be escaped by preceding them with a backslash. Also,
> the complete name should be surrounded with double quotes (e.g.
> `"path/with\n, \\ and \" in it"`).
> 
> This should be technically correct, and "this is accepted in all cases"
> should encourrage people to use it.

I think that is much better, but it reads a little more easily to me if we rearrange the second sentence. To complete my English bikeshedding, here is how I would have written the whole paragraph:

  A path can use C-style string quoting; this is accepted in all cases
  and mandatory if the filename starts with double quote or contains
  `LF`. In C-style quoting, the complete name should be surrounded with
  double quotes, and any `LF`, backslash, or double quote characters
  must be escaped by preceding them with a backslash (e.g.,
  `"path/with\n, \\ and \" in it"`).

Feel free to incorporate or ignore any of my tweaks from that version.

-Peff