Re* [PATCH 5/7] git-log.txt: rewrite note on why "--" may be required

[Junio C Hamano <gitster@pobox.com>]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> In its current form, the note talks about separating options from
> "branch names" and "refnames" in the same sentence.  This is entirely
> inaccurate, as <revision range> need not be a set of branch names or
> ref names.  Rewrite it to use the word "revision range", to be
> consistent with the SYNOPSIS.
>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/git-log.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index 9576695..a976534 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -77,8 +77,8 @@ produced by --stat etc.
>  	Simplification" below for details and other simplification
>  	modes.
>  +
> -To prevent confusion with options and branch names, paths may need to
> -be prefixed with "\-- " to separate them from options or refnames.
> +Paths may need to be prefixed with "\-- " to separate them from
> +options or the revision range, when confusion arises.
>  
>  include::rev-list-options.txt[]

This is an explanation about an enumeration item:

	[\--] <path>...::

which corresponds to this in the synopsis:

        'git log' [<options>] [<revision range>] [[\--] <path>...]

But the synopsis looks incorrect to me.  It insists that if you were
to write "--", you have to give at least one <path>.

It should be more like this [*1*]:

	'git log' [<options>] [<revision range>] [--] [<path>...]

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.

Formatting doubts aside, one thing I am not so happy about the
suggested patch below (would apply on top of the patches from this
series) is that the explanation of a double-dash requires
understanding of _both_ what <revision range> and <path>... means to
the command, but for a reader who has read this page from top, the
latter has not been explained yet.  We could of course swap the
order and describe <path>... first and then "--", but that does not
sound quite right, either.  It has to be between these two.


[Footnote]

*1* We have many instances like "[--quiet]" in Documentation; do we
    need the backslash before these double-dash like "[\--]"?


 Documentation/git-log.txt | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index a976534..f5746e4 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -9,7 +9,7 @@ git-log - Show commit logs
 SYNOPSIS
 --------
 [verse]
-'git log' [<options>] [<revision range>] [[\--] <path>...]
+'git log' [<options>] [<revision range>] [--] [<path>...]
 
 DESCRIPTION
 -----------
@@ -71,14 +71,26 @@ produced by --stat etc.
 	ways to spell <revision range>, see the "Specifying Ranges"
 	section of linkgit:gitrevisions[7].
 
-[\--] <path>...::
+--::
+	On the command line, arguments that specify revision range
+	come first and then paths (see the next item).  A
+	double-dash can be used to mark the end of revision range
+	arguments when an argument can be otherwise ambiguous.
++
+For example, when there are a file called `master` and a branch with
+the same name, what `git log master` means is unclear.  It may be
+asking for the whole history leading to the current commit (i.e. no
+<revision range> is specified, defaulting to `HEAD`), limited to
+commits that touch a single path `master`.  Or it may be asking for
+the whole history leading to the tip of `master`, without any path
+limiting.  The former can be spelled `git log -- master`, while the
+latter can be spelled `git log master --`.
+
+<path>...::
 	Show only commits that are enough to explain how the files
 	that match the specified paths came to be.  See "History
 	Simplification" below for details and other simplification
 	modes.
-+
-Paths may need to be prefixed with "\-- " to separate them from
-options or the revision range, when confusion arises.
 
 include::rev-list-options.txt[]