From e4372165fb5d754425594cf6b1b31238cdb6974a Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sun, 19 Oct 2008 16:12:19 +0000
Subject: [PATCH] (Reading File Names): Document `read-shell-command' and
 `minibuffer-local-shell-command-map'.

---
 doc/lispref/ChangeLog    |  5 +++++
 doc/lispref/minibuf.texi | 36 +++++++++++++++++++++++++++++++-----
 etc/NEWS                 |  1 +
 3 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 7e107a0532c..f61bbe840ba 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2008-10-19  Eli Zaretskii  <eliz@gnu.org>
+
+	* minibuf.texi (Reading File Names): Document `read-shell-command'
+	and `minibuffer-local-shell-command-map'.
+
 2008-10-19  Martin Rudalics  <rudalics@gmx.at>
 
 	* windows.texi (Resizing Windows): Remove var{} around "window" in
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 8140e143a71..ea4971b4ae9 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -632,7 +632,8 @@ for reading certain kinds of names with completion.
 * Completion Commands::    Minibuffer commands that do completion.
 * High-Level Completion::  Convenient special cases of completion
                              (reading buffer name, file name, etc.)
-* Reading File Names::     Using completion to read file names.
+* Reading File Names::     Using completion to read file names and
+                             shell commands.
 * Programmed Completion::  Writing your own completion-function.
 @end menu
 
@@ -1102,7 +1103,7 @@ function @code{read-file-name}.
 @end defvar
 
 @node High-Level Completion
-@subsection High-Level Completion  Functions
+@subsection High-Level Completion Functions
 
   This section describes the higher-level convenient functions for
 reading certain sorts of names with completion.
@@ -1275,9 +1276,9 @@ and @code{read-input-method-name}, in @ref{Input Methods}.
 @cindex read file names
 @cindex prompt for file name
 
-  Here is another high-level completion function, designed for reading a
-file name.  It provides special features including automatic insertion
-of the default directory.
+  Here is a couple of other high-level completion function, designed
+for reading file names and shell commands.  They provide special
+features including automatic insertion of the default directory.
 
 @defun read-file-name prompt &optional directory default existing initial predicate
 This function reads a file name in the minibuffer, prompting with
@@ -1460,6 +1461,31 @@ The file is @point{}
 @end example
 @end defopt
 
+@defun read-shell-command prompt &optional initial-contents hist &rest args
+This function reads a shell command from the minibuffer, prompting
+with @var{prompt} and providing intelligent completion.  It completes
+the first word of the command using candidates that are appropriate
+for command names.  The rest of the shell command arguments are
+completed as file names.
+
+This function works by calling @code{read-from-minibuffer}
+(@pxref{Text from Minibuffer}), passing it
+@code{minibuffer-local-shell-command-map} as the @var{keymap}
+argument.  The optional arguments @var{initial-contents} and
+@var{hist} are passed to @code{read-from-minibuffer} unaltered, except
+that if @var{hist} is omitted or @code{nil}, it defaults to
+@code{shell-command-history} (@pxref{Minibuffer History,
+shell-command-history}), and the @var{read} argument is passed as
+@code{nil}.  The rest of @var{args}, if present, are used by
+@code{read-from-minibuffer} as its @var{default} and
+@var{inherit-input-method} arguments.
+@end defun
+
+@defvar minibuffer-local-shell-command-map
+This keymap is used by @code{read-shell-command} for completing
+command and file names that are part of a shell command.
+@end defvar
+
 @node Programmed Completion
 @subsection Programmed Completion
 @cindex programmed completion
diff --git a/etc/NEWS b/etc/NEWS
index 6a7783e6293..91be9d943ff 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1584,6 +1584,7 @@ string of days, hours, etc.
 +++
 *** `apply-partially' performs a "curried" application of a function.
 
++++
 *** `read-shell-command' does what its name says, with completion.  It
 uses the minibuffer-local-shell-command-map for that.
 
-- 
2.39.5