Merge branch 'rr/shortlog-doc'

Update documentation for "log" and "shortlog".

* rr/shortlog-doc:
  builtin/shortlog.c: make usage string consistent with log
  builtin/log.c: make usage string consistent with doc
  git-shortlog.txt: make SYNOPSIS match log, update OPTIONS
  git-log.txt: rewrite note on why "--" may be required
  git-log.txt: generalize <since>..<until>
  git-log.txt: order OPTIONS properly; move <since>..<until>
  revisions.txt: clarify the .. and ... syntax
  git-shortlog.txt: remove (-h|--help) from OPTIONS

Documentation/git-log.txt

@@ -9,7 +9,7 @@ git-log - Show commit logs
 SYNOPSIS
 --------
 [verse]
-'git log' [<options>] [<since>..<until>] [[\--] <path>...]
+'git log' [<options>] [<revision range>] [[\--] <path>...]
 
 DESCRIPTION
 -----------
@@ -24,13 +24,6 @@ each commit introduces are shown.
 OPTIONS
 -------
 
-<since>..<until>::
-	Show only commits between the named two commits.  When
-	either <since> or <until> is omitted, it defaults to
-	`HEAD`, i.e. the tip of the current branch.
-	For a more complete list of ways to spell <since>
-	and <until>, see linkgit:gitrevisions[7].
-
 --follow::
 	Continue listing the history of a file beyond renames
 	(works only for a single file).
@@ -69,14 +62,23 @@ produced by --stat etc.
 	Note that only message is considered, if also a diff is shown
 	its size is not included.
 
+<revision range>::
+	Show only commits in the specified revision range.  When no
+	<revision range> is specified, it defaults to `HEAD` (i.e. the
+	whole history leading to the current commit).  `origin..HEAD`
+	specifies all the commits reachable from the current commit
+	(i.e. `HEAD`), but not from `origin`. For a complete list of
+	ways to spell <revision range>, see the "Specifying Ranges"
+	section of linkgit:gitrevisions[7].
+
 [\--] <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.
 +
-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[]
 

Documentation/git-shortlog.txt

@@ -8,8 +8,8 @@ git-shortlog - Summarize 'git log' output
 SYNOPSIS
 --------
 [verse]
-git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]
-'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] <commit>...
+git log --pretty=short | 'git shortlog' [<options>]
+'git shortlog' [<options>] [<revision range>] [[\--] <path>...]
 
 DESCRIPTION
 -----------
@@ -26,10 +26,6 @@ reference to the current repository.
 OPTIONS
 -------
 
--h::
---help::
-	Print a short usage message and exit.
-
 -n::
 --numbered::
 	Sort output according to the number of commits per author instead
@@ -60,6 +56,21 @@ OPTIONS
 If width is `0` (zero) then indent the lines of the output without wrapping
 them.
 
+<revision range>::
+	Show only commits in the specified revision range.  When no
+	<revision range> is specified, it defaults to `HEAD` (i.e. the
+	whole history leading to the current commit).  `origin..HEAD`
+	specifies all the commits reachable from the current commit
+	(i.e. `HEAD`), but not from `origin`. For a complete list of
+	ways to spell <revision range>, see the "Specifying Ranges"
+	section of linkgit:gitrevisions[7].
+
+[\--] <path>...::
+	Consider only commits that are enough to explain how the files
+	that match the specified paths came to be.
++
+Paths may need to be prefixed with "\-- " to separate them from
+options or the revision range, when confusion arises.
 
 MAPPING AUTHORS
 ---------------

Documentation/revisions.txt

@@ -244,11 +244,13 @@ To summarize:
 
 '<rev1>..<rev2>'::
 	Include commits that are reachable from <rev2> but exclude
-	those that are reachable from <rev1>.
+	those that are reachable from <rev1>.  When either <rev1> or
+	<rev2> is omitted, it defaults to 'HEAD'.
 
 '<rev1>\...<rev2>'::
 	Include commits that are reachable from either <rev1> or
-	<rev2> but exclude those that are reachable from both.
+	<rev2> but exclude those that are reachable from both.  When
+	either <rev1> or <rev2> is omitted, it defaults to 'HEAD'.
 
 '<rev>{caret}@', e.g. 'HEAD{caret}@'::
   A suffix '{caret}' followed by an at sign is the same as listing

builtin/log.c

@@ -37,7 +37,7 @@ static const char *fmt_patch_subject_prefix = "PATCH";
 static const char *fmt_pretty;
 
 static const char * const builtin_log_usage[] = {
-	N_("git log [<options>] [<since>..<until>] [[--] <path>...]\n")
+	N_("git log [<options>] [<revision range>] [[--] <path>...]\n")
 	N_("   or: git show [options] <object>..."),
 	NULL
 };

builtin/shortlog.c

@@ -10,9 +10,7 @@
 #include "parse-options.h"
 
 static char const * const shortlog_usage[] = {
-	N_("git shortlog [-n] [-s] [-e] [-w] [rev-opts] [--] [<commit-id>... ]"),
-	"",
-	N_("[rev-opts] are documented in git-rev-list(1)"),
+	N_("git shortlog [<options>] [<revision range>] [[--] [<path>...]]"),
 	NULL
 };