master 3b44829: Update and improve documentation of project.el commands

[Eli Zaretskii]

branch: master
commit 3b44829823f43d3736b8ec9db2258eeff7f6c16a
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Update and improve documentation of project.el commands
    
    * doc/emacs/custom.texi (Prefix Keymaps): Document
    'project-prefix-map'.
    * doc/emacs/maintaining.texi (Project File Commands)
    (Switching Projects): Describe key bindings for the commands
    described in the sections.  Document 'project-list-file'.
    (Project Buffer Commands): New section.
    * doc/emacs/emacs.texi (Top): Add Project sections to the detailed
    menu.
    
    * etc/NEWS: Add entries for project.el, and mark documented entries as
    appropriate.
---
 doc/emacs/custom.texi      |   4 ++
 doc/emacs/emacs.texi       |   6 ++
 doc/emacs/maintaining.texi | 161 +++++++++++++++++++++++++++++++++------------
 etc/NEWS                   |  16 ++++-
 4 files changed, 142 insertions(+), 45 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 00c8ee4..acd7fb1 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1630,6 +1630,10 @@ characters are actually defined by this map.
 @item
 @vindex mode-specific-map
 @code{mode-specific-map} is for characters that follow @kbd{C-c}.
+@item
+@vindex project-prefix-map
+@code{project-prefix-map} is for characters that follow @kbd{C-x p},
+used for project-related commands (@pxref{Projects}).
 @end itemize
 
 @node Local Keymaps
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 6b82aeb..5b6b7b7 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -857,6 +857,12 @@ Customizing VC
 * CVS Options::           Options for CVS.
 @end ifnottex
 
+Projects
+
+* Project File Commands::   Commands for handling project files.
+* Project Buffer Commands:: Commands for handling project buffers.
+* Switching Projects::      Switching between projects.
+
 Change Logs
 
 * Change Log Commands:: Commands for editing change log files.
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index cc7415e..43ec2d4 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1657,12 +1657,43 @@ the project back-end.  For example, the VC back-end 
doesn't consider
 ``ignored'' files (@pxref{VC Ignore}) to be part of the project.
 
 @menu
-* Project File Commands:: Commands for handling project files.
-* Switching Projects::    Switching between projects.
+* Project File Commands::   Commands for handling project files.
+* Project Buffer Commands:: Commands for handling project buffers.
+* Switching Projects::      Switching between projects.
 @end menu
 
 @node Project File Commands
-@subsection Project File Commands
+@subsection Project Commands That Operate on Files
+
+@table @kbd
+@item C-x p f
+Visit a file that belongs to the current project
+(@code{project-find-file}).
+@item C-x p g
+Find matches for a regexp in all files that belong to the current
+project (@code{project-find-regexp}).
+@item M-x project-search
+Interactively search for regexp matches in all files that belong to
+the current project.
+@item C-x p r
+Perform query-replace for a regexp in all files that belong to the
+current project (@code{project-query-replace-regexp}).
+@item C-x p d
+Run Dired in the current project's root directory
+(@code{project-dired}).
+@item C-x p v
+Run @code{vc-dir} in the current project's root directory
+(@code{project-vc-dir}).
+@item C-x p s
+Start an inferior shell in the current project's root directory
+(@code{project-shell}).
+@item C-x p e
+Start Eshell in the current project's root directory
+(@code{project-eshell}).
+@item C-x p c
+Run compilation in the current project's root directory
+(@code{project-compile}).
+@end table
 
   Emacs provides commands for handling project files conveniently.
 This subsection describes these commands.
@@ -1676,25 +1707,26 @@ doesn't seem to belong to a recognizable project, these 
commands
 prompt you for the project directory.
 
 @findex project-find-file
-  The command @code{project-find-file} is a convenient way of visiting
-files (@pxref{Visiting}) that belong to the current project.  Unlike
-@kbd{C-x C-f}, this command doesn't require to type the full file name
-of the file to visit, you can type only the file's base name (i.e.,
-omit the leading directories).  In addition, the completion candidates
-considered by the command include only the files belonging to the
-current project, and nothing else.  If there's a file name at point,
-this command offers that file as the default to visit.
+  The command @kbd{C-x p f} (@code{project-find-file}) is a convenient
+way of visiting files (@pxref{Visiting}) that belong to the current
+project.  Unlike @kbd{C-x C-f}, this command doesn't require to type
+the full file name of the file to visit, you can type only the file's
+base name (i.e., omit the leading directories).  In addition, the
+completion candidates considered by the command include only the files
+belonging to the current project, and nothing else.  If there's a file
+name at point, this command offers that file as the default to visit.
 
 @findex project-find-regexp
-  The command @code{project-find-regexp} is similar to @code{rgrep}
-(@pxref{Grep Searching}), but it searches only the files that belong
-to the current project.  The command prompts for the regular
-expression to search, and pops up an Xref mode buffer with the search
-results, where you can select a match using the Xref mode commands
-(@pxref{Xref Commands}).  When invoked with a prefix argument, this
-command additionally prompts for the base directory from which to
-start the search; this allows, for example, to limit the search only
-to project files under a certain subdirectory of the project root.
+  The command @kbd{C-x p g} (@code{project-find-regexp}) is similar to
+@code{rgrep} (@pxref{Grep Searching}), but it searches only the files
+that belong to the current project.  The command prompts for the
+regular expression to search, and pops up an Xref mode buffer with the
+search results, where you can select a match using the Xref mode
+commands (@pxref{Xref Commands}).  When invoked with a prefix
+argument, this command additionally prompts for the base directory
+from which to start the search; this allows, for example, to limit the
+search only to project files under a certain subdirectory of the
+project root.
 
 @findex project-search
   @kbd{M-x project-search} is an interactive variant of
@@ -1706,7 +1738,7 @@ matched file.  To find the rest of the matches, type 
@w{@kbd{M-x
 fileloop-continue @key{RET}}}.
 
 @findex project-query-replace-regexp
-  @kbd{M-x project-query-replace-regexp} is similar to
+  @kbd{C-x p r} (@code{project-query-replace-regexp}) is similar to
 @code{project-search}, but it prompts you for whether to replace each
 match it finds, like @code{query-replace} does (@pxref{Query
 Replace}), and continues to the next match after you respond.  If your
@@ -1714,40 +1746,85 @@ response causes Emacs to exit the query-replace loop, 
you can later
 continue with @w{@kbd{M-x fileloop-continue @key{RET}}}.
 
 @findex project-dired
-  The command @code{project-dired} opens a Dired buffer
-(@pxref{Dired}) listing the files in the current project's root
+  The command @kbd{C-x p d} (@code{project-dired}) opens a Dired
+buffer (@pxref{Dired}) listing the files in the current project's root
 directory.
 
 @findex project-vc-dir
-  The command @code{project-vc-dir} opens a VC Directory buffer
-(@pxref{VC Directory Mode}) listing the version control statuses of
-the files in a directory tree under the current project's
-root directory.
+  The command @kbd{C-x p v} (@code{project-vc-dir}) opens a VC
+Directory buffer (@pxref{VC Directory Mode}) listing the version
+control statuses of the files in a directory tree under the current
+project's root directory.
 
 @findex project-shell
-  The command @code{project-shell} starts a shell session
-(@pxref{Shell}) in a new buffer with the current project's root as the
-working directory.
+  The command @kbd{C-x p s} (@code{project-shell}) starts a shell
+session (@pxref{Shell}) in a new buffer with the current project's
+root as the working directory.
 
 @findex project-eshell
-  The command @code{project-eshell} starts an Eshell session in a new
-buffer with the current project's root as the working directory.
-@xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.
+  The command @kbd{C-x p e} (@code{project-eshell}) starts an Eshell
+session in a new buffer with the current project's root as the working
+directory.  @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.
+
+@findex project-compile
+  The command @kbd{C-x p c} (@code{project-compile}) runs compilation
+(@pxref{Compilation}) in the current project's root directory.
+
+@node Project Buffer Commands
+@subsection Project Commands That Operate on Buffers
+
+@table @kbd
+@item C-x p b
+Switch to another buffer belonging to the current project
+(@code{project-switch-to-buffer}).
+@item C-x p k
+Kill all live buffers that belong to the current project
+(@code{project-kill-buffers}).
+@end table
+
+@findex project-switch-to-buffer
+  Working on a project could potentially involve having many buffers
+visiting files that belong to the project, and also buffers that
+belong to the project, but don't visit any files (like the
+@file{*compilation*} buffer created by @code{project-compile}).  The
+command @kbd{C-x p b} (@code{project-switch-to-buffer}) helps you
+switch between buffers that belong to the current project by prompting
+for a buffer to switch and considering only the current project's
+buffers as candidates for completion.
+
+@findex project-kill-buffers
+@vindex project-kill-buffers-ignores
+  When you finish working on the project, you may wish to kill all the
+buffers that belong to the project, to keep your Emacs session
+smaller.  The command @kbd{C-x p k} (@code{project-kill-buffers})
+accomplishes that: it kills all the buffers that belong to the current
+project, except if @code{project-kill-buffers-ignores} tells
+otherwise.
 
 @node Switching Projects
 @subsection Switching Projects
 
+@table @kbd
+@item C-x p p
+Run an Emacs command for another project (@code{project-switch-project}).
+@end table
+
+@findex project-switch-project
+@vindex project-switch-commands
   Commands that operate on project files (@pxref{Project File
 Commands}) will conveniently prompt you for a project directory when
-no project is current.  When you are inside a project but you want to
-operate on a different project, the command
-@code{project-switch-project} can be used.
-
-  This command prompts you to choose a directory among known project
-roots, and then displays the menu of available commands to operate on
-the chosen project.  The variable @code{project-switch-commands}
-controls which commands are available in the menu, and by which keys
-they are invoked.
+no project is current.  When you are inside some project, but you want
+to operate on a different project, use the @kbd{C-x p p} command
+(@code{project-switch-project}).  This command prompts you to choose a
+directory among known project roots, and then displays the menu of
+available commands to operate on the project you choose.  The variable
+@code{project-switch-commands} controls which commands are available
+in the menu, and which key invokes each command.
+
+@vindex project-list-file
+  The variable @code{project-list-file} names the file in which Emacs
+records the list of known projects.  It defaults to the file
+@file{projects} in @code{user-emacs-directory} (@pxref{Find Init}).
 
 @node Change Log
 @section Change Logs
diff --git a/etc/NEWS b/etc/NEWS
index c93057e..650b958 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -502,21 +502,31 @@ information, see the related entry about 'shr-browse-url' 
above.
 
 *** New user option 'project-vc-merge-submodules'.
 
-*** Previously used project directories are now suggested by
-all commands that prompt for a project directory.
+*** Project commands now have their own history.
+Previously used project directories are now suggested by all commands
+that prompt for a project directory.
+
++++
+*** New prefix keymap 'project-prefix-map'.
+Key sequences that invoke project-related commands start with the
+prefix 'C-x p'.  Type "C-x p C-h" to show the full list.
 
 +++
 *** New commands 'project-dired', 'project-vc-dir', 'project-shell',
 'project-eshell'.  These commands run Dired/VC-Dir and Shell/Eshell in
 a project's root directory, respectively.
 
-*** New command 'project-compile', which runs compilation.
++++
+*** New command 'project-compile'.
+This command runs compilation in the current project's root
+directory.
 
 +++
 *** New command 'project-switch-project'.
 This command lets you "switch" to another project and run a project
 command chosen from a dispatch menu.
 
++++
 *** New user option 'project-list-file'.
 
 ** json.el