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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 21, 2013, 06:51 UTC
Message-ID: <7vtxn0wf4j.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1366458313-7186-5-git-send-email-artagnon@gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

Show 22 quoted lines

> In its current form, the note talks about separating options from
> "branch names" and "refnames" in the same sentence.  This is entirely
> inaccurate, as the rev spec need not be a set of branch names or ref
> names.  Rewrite it to use the word "revisions".
>
> 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 f03ae74..1a9c3ca 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -75,8 +75,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 revisions, when confusion arises.

I think "branch names" was an attempt to make it more newbie friendly by sacrificing technical accuracy. With the suggested update (see the review for the previous one), it would be easier to read if this part said "options or the revision range".

Two other things I noticed with the current text are:

 * As the synopsis section shows, on the command line, --options
   come first, then revision range and then pathspec.  The order of
   the description should follow that as well.  The current text
   shows <since>..<until> at the very beginning, which is wrong.

 * The part with the new "-L" option seems to be throwing the
   overall formatting off.  Its second paragraph "<start> and <end>
   can take..." is not indented to the same level as its first
   paragraph "Trace the evolution of...", and the following items,
   like "--full-line-diff" and "[--] <pathspec>..." are indented one
   level too deeply.