Re: [PATCH v2 6/7] Documentation: put blame/log -L in sticked form

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

Thomas Rast <tr@thomasrast.ch> writes:

> The next patch will document gitk -L, but gitk does not understand the
> separated form ('gitk -L :foo:bar' results in an error).  Spell
> git-blame and git-log -L, which are supposed to be "the same" option,
> without the spaces to prevent confusion.

I agree that this patch may reduce confusion locally, but if we were
to go in this direction, we should be consistent and enforce "stuck"
form everywhere, not just the options you happened to have passed
thru to gitk, but other options such as "-S <revs-file>", and also
other commands that do not have anything to do with gitk (e.g. "git
commit -C<commit>", not "git commit -C <commit>".  Otherwise you
will give a wrong impression to readers as if they have to remember
which ones need to use the stuck form and which ones do not.

> Signed-off-by: Thomas Rast <tr@thomasrast.ch>
> ---
>  Documentation/blame-options.txt | 8 ++++----
>  Documentation/git-blame.txt     | 8 ++++----
>  Documentation/git-log.txt       | 6 +++---
>  3 files changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt
> index 0cebc4f..28ca95e 100644
> --- a/Documentation/blame-options.txt
> +++ b/Documentation/blame-options.txt
> @@ -9,13 +9,13 @@
>  --show-stats::
>  	Include additional statistics at the end of blame output.
>  
> --L <start>,<end>::
> --L :<regex>::
> +-L<start>,<end>::
> +-L:<regex>::
>  	Annotate only the given line range. May be specified multiple times.
>  	Overlapping ranges are allowed.
>  +
> -<start> and <end> are optional. ``-L <start>'' or ``-L <start>,'' spans from
> -<start> to end of file. ``-L ,<end>'' spans from start of file to <end>.
> +<start> and <end> are optional. ``-L<start>'' or ``-L<start>,'' spans from
> +<start> to end of file. ``-L,<end>'' spans from start of file to <end>.
>  +
>  include::line-range-format.txt[]
>  
> diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
> index f2c85cc..085dba1 100644
> --- a/Documentation/git-blame.txt
> +++ b/Documentation/git-blame.txt
> @@ -9,7 +9,7 @@ SYNOPSIS
>  --------
>  [verse]
>  'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
> -	    [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
> +	    [-L<range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
>  	    [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] [--] <file>
>  
>  DESCRIPTION
> @@ -139,12 +139,12 @@ lines 40-60 for file `foo`, you can use the `-L` option like so
>  (they mean the same thing -- both ask for 21 lines starting at
>  line 40):
>  
> -	git blame -L 40,60 foo
> -	git blame -L 40,+21 foo
> +	git blame -L40,60 foo
> +	git blame -L40,+21 foo
>  
>  Also you can use a regular expression to specify the line range:
>  
> -	git blame -L '/^sub hello {/,/^}$/' foo
> +	git blame -L'/^sub hello {/,/^}$/' foo
>  
>  which limits the annotation to the body of the `hello` subroutine.
>  
> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index 34097ef..87c10fa 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -62,8 +62,8 @@ produced by --stat etc.
>  	Note that only message is considered, if also a diff is shown
>  	its size is not included.
>  
> --L <start>,<end>:<file>::
> --L :<regex>:<file>::
> +-L<start>,<end>:<file>::
> +-L:<regex>:<file>::
>  
>  	Trace the evolution of the line range given by "<start>,<end>"
>  	(or the funcname regex <regex>) within the <file>.  You may
> @@ -152,7 +152,7 @@ EXAMPLES
>  	This makes sense only when following a strict policy of merging all
>  	topic branches when staying on a single integration branch.
>  
> -`git log -L '/int main/',/^}/:main.c`::
> +`git log -L'/int main/',/^}/:main.c`::
>  
>  	Shows how the function `main()` in the file 'main.c' evolved
>  	over time.