[PATCH] send-email: clarify dual-mode behavior

[Bagas Sanjaya <bagasdotme@gmail.com>]

git send-email can be operated in two modes: one that sends
already-prepared patches and one that generates patches from
revision range on-the-fly for sending. Clarify it in the documentation
and usage help.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 This patch is based on [PATCH v5 2/3] send-email: programmatically
 generate bash completions [1]. PATCH v5 3/3 can be replaced with
 this patch, or be integrated as stand-alone patch.

 Questions:

   1. Do all supported revision range syntaxes from git rev-list also be
      accepted by git send-email? I only test `A..B` and `B ^A` syntaxes
      and assumed that all are supported.
   2. Does git send-email also accepts options understood by git
      rev-list? I interpreted that git send-email accepts file, directory
      or rev-list ranges but not rev-list options (I interpreted from
      previous synopsis before this patch but it said `rev-list options`).

 [1]:
https://lore.kernel.org/git/20210924024606.20542-3-tbperrotta@gmail.com/

 Documentation/git-send-email.txt | 14 ++++++++------
 git-send-email.perl              |  3 ++-
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 3db4eab4ba..b1d239d74c 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -9,17 +9,19 @@ git-send-email - Send a collection of patches as emails
 SYNOPSIS
 --------
 [verse]
-'git send-email' [<options>] <file|directory|rev-list options>...
+'git send-email' [<options>] <file|directory>...
+'git send-email' [<options>] <revision range>
 'git send-email' --dump-aliases
 
 
 DESCRIPTION
 -----------
-Takes the patches given on the command line and emails them out.
-Patches can be specified as files, directories (which will send all
-files in the directory), or directly as a revision list.  In the
-last case, any format accepted by linkgit:git-format-patch[1] can
-be passed to git send-email.
+In the first form, take the patches in the <file> or <directory> and
+email them out. In the second form, generate patches from the specified
+<revision range> and email them out. <revision range> can be syntaxes
+that are accepted by linkgit:git-rev-list[1]. Options that are
+understood by linkgit:git-format-patch[1] can also be specified in
+<options> if the second form is used.
 
 The header of the email is configurable via command-line options.  If not
 specified on the command line, the user will be prompted with a ReadLine
diff --git a/git-send-email.perl b/git-send-email.perl
index 0214b55b4f..5d623f2fa8 100755
--- a/git-send-email.perl
+++ b/git-send-email.perl
@@ -39,7 +39,8 @@ package main;
 
 
 my $USAGE = <<EOT
-git send-email [options] <file | directory | rev-list options>
+git send-email [options] <file | directory>...
+git send-email [options] <revision range>
 git send-email --dump-aliases
 
   Composing:
-- 
2.25.1