From: Ramkumar Ramachandra <artagnon@gmail.com>
Date: Thu, 25 Apr 2013 05:17:25 GMT
Subject: Re: Re* [PATCH 5/7] git-log.txt: rewrite note on why "--" may be required
Message-ID: <CALkWK0m2__SZmpyQqLjkJuMWtPuD4=Oo7QrYovq_Fw6fpHEXXQ@mail.gmail.com>
In-Reply-To: <7vmwsn8ok4.fsf_-_@alter.siamese.dyndns.org>

Junio C Hamano wrote:
> It should be more like this [*1*]:
>
>         'git log' [<options>] [<revision range>] [--] [<path>...]

Agreed.  The backslash is unnecessary (I suspect it's something
carried over from earlier versions of asciidoc requiring this
escaping).

> It may be better to split the item into two, keep the current
> description of <path> under "<path>...::" heading, and have another
> heading for "--::" that talks about the disambiguation.  The "--"
> disambiguator is not solely for "your path might be mistaken as a
> revision without it", but also for "your revision might be mistaken
> as a path", but both the old and the new text are fuzzy about the
> reason what "confusion" it is cautioning the reader.

I agree that the "confusion" paragraph after [--] [<path>] can be
improved, but putting [--] in a paragraph of its own sounds like an
overkill.  Apart from other things, it means that every single git
command would need an identical [--] paragraph for consistency.  We
can just keep the footnote following [--] [<path>] in some commands,
using discretion.