Improve documentation of project.el commands

* lisp/progmodes/project.el (project-find-regexp): Require 'grep'
to be able to call 'grep-read-files'.
(project-search, project-query-replace-regexp): Doc fixes.

* doc/emacs/maintaining.texi (Projects): New section.
* doc/emacs/emacs.texi (Top): Add "Projects" to the detailed menu.

4 files changed, 86 insertions, 4 deletions

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index c3cb37e6a6d..6ef4ca63ae7 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -785,6 +785,7 @@ GDB Graphical Interface
 Maintaining Large Programs
 
 * Version Control::     Using version control systems.
+* Projects::            Commands for handling source files in a project.
 * Change Log::          Maintaining a change history for your program.
 * Xref::                Find definitions and references of any function,
                           method, struct, macro, @dots{} in your program.
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index a6f66f6e7f3..ebcdddfcae3 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -14,6 +14,9 @@ Unified interface to Support for Version Control Systems
 (@acronym{VCS}) that record the history of changes to source files.
 
 @item
+Commands for handling programming projects.
+
+@item
 A specialized mode for maintaining @file{ChangeLog} files that provide
 a chronological log of program changes.
 
@@ -38,6 +41,7 @@ Lisp Regression Testing}).
 
 @menu
 * Version Control::     Using version control systems.
+* Projects::            Commands for handling source files in a project.
 * Change Log::          Maintaining a change history for your program.
 * Xref::                Find definitions and references of any function,
                           method, struct, macro, @dots{} in your program.
@@ -1630,6 +1634,77 @@ different revision with @kbd{C-u C-x v v}.
 @include vc1-xtra.texi
 @end ifnottex
 
+@node Projects
+@section Working with Projects
+@cindex projects
+
+@cindex project root
+  A @dfn{project} is a collection of files used for producing one or
+more programs.  Files that belong to a project are typically stored in
+a hierarchy of directories; the top-level directory of the hierarchy
+is known as the @dfn{project root}.
+
+@cindex project back-end
+  Whether a given directory is a root of some project is determined by
+the project-specific infrastructure, known as @dfn{project back-end}.
+Emacs currently supports two such back-ends: VC (@pxref{Version
+Control}), whereby a VCS repository is considered a project; and EDE
+(@pxref{EDE}).  This is expected to be extended in the future to
+support additional types of projects.
+
+  Which files do or don't belong to a project is also determined by
+the project back-end.  For example, the VC back-end doesn't consider
+``ignored'' files (@pxref{VC Ignore}) to be part of the project.
+
+  Emacs provides commands for handling project files conveniently.
+This section describes these commands.
+
+@cindex current project
+  All of the commands described here share the notion of the
+@dfn{current project}.  The current project is determined by the
+@code{default-directory} (@pxref{File Names}) of the buffer that is
+the current buffer when the command is invoked.  If that directory
+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.
+
+@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.
+
+@findex project-search
+  @kbd{M-x project-search} is an interactive variant of
+@code{project-find-regexp}.  It prompts for a regular expression to
+search in the current project's files, but instead of finding all the
+matches and displaying them, it stops when it finds a match and visits
+the matched file at the locus of the match, allowing you to edit the
+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
+@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
+response causes Emacs to exit the query-replace loop, you can later
+continue with @w{@kbd{M-x fileloop-continue @key{RET}}}.
+
 @node Change Log
 @section Change Logs
 
diff --git a/etc/NEWS b/etc/NEWS
index b41541c715f..d3f27e328e7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -978,7 +978,10 @@ The mode is automatically enabled in files that start with the
 
 ** project.el
 
++++
 *** New commands 'project-search' and 'project-query-replace-regexp'.
+
+---
 *** New user option 'project-read-file-name-function'.
 
 ** Etags
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index ccd8cc049d4..f4678681858 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -437,6 +437,7 @@ triggers completion when entering a pattern, including it
 requires quoting, e.g. `\\[quoted-insert]<space>'."
   (interactive (list (project--read-regexp)))
   (require 'xref)
+  (require 'grep)
   (let* ((pr (project-current t))
          (files
           (if (not current-prefix-arg)
@@ -606,7 +607,8 @@ PREDICATE, HIST, and DEFAULT have the same meaning as in
 (defun project-search (regexp)
   "Search for REGEXP in all the files of the project.
 Stops when a match is found.
-To continue searching for next match, use command \\[fileloop-continue]."
+To continue searching for the next match, use the
+command \\[fileloop-continue]."
   (interactive "sSearch (regexp): ")
   (fileloop-initialize-search
    regexp (project-files (project-current t)) 'default)
@@ -614,9 +616,10 @@ To continue searching for next match, use command \\[fileloop-continue]."
 
 ;;;###autoload
 (defun project-query-replace-regexp (from to)
-  "Search for REGEXP in all the files of the project.
-Stops when a match is found.
-To continue searching for next match, use command \\[fileloop-continue]."
+  "Query-replace REGEXP in all the files of the project.
+Stops when a match is found and prompts for whether to replace it.
+If you exit the query-replace, you can later continue the query-replace
+loop using the command \\[fileloop-continue]."
   (interactive
    (pcase-let ((`(,from ,to)
                 (query-replace-read-args "Query replace (regexp)" t t)))