emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: emacs-27 561e9fb: Improve documentation of project.el commands


From: Dmitry Gutov
Subject: Re: emacs-27 561e9fb: Improve documentation of project.el commands
Date: Sat, 21 Mar 2020 23:19:25 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1

Hi Eli,

Thanks for this. I have some nitpicks, but they're not essential, so please treat them at your discretion.

On 21.03.2020 13:26, Eli Zaretskii wrote:
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index c3cb37e..6ef4ca6 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.

Not sure I like the word "source" here.

All commands listed below just as well work on documentation files, build configuration files, etc. Basically anything a user might want to read or edit inside the project. Pictures as well.

The Project API can be easily extended with the notion of source files, e.g. to feed them to 'etags', rebuilding the database with minimal user intervention, but so far no specific feature has called for it.

  * 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 a6f66f6..ebcdddf 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.

Same for the word "programming" here.

Maybe somebody is writing a book? And the project consists of TeX files, or Markdown, or any other specialized text files. Or a website? In the simplest case, I wouldn't call it a programming project either.

+@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.

Same thing here: the files could be used for anything, really.

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}.

Can we really say "the project root" (instead of "a")? The current version of the API says that a project can have multiple roots. Though I plan to do away with this possibility later.

And is "hierarchy of directories" a better term than "directory tree"?

+  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.

Excellent.

+@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}}}.

Personally, I'd rather leave these two undocumented, since they're slower in significant number of cases, don't work over Tramp, and might make an impression that the last one is *the* preferred way to do search-and-replace. Whereas Xref mode buffers have a handy 'r' binding for that.

But they might look more cozy and familiar to our older users, so IDK.

There's also command called project-or-external-find-regexp, which I sometimes find handy e.g. because it searches load-path when in emacs-lisp-mode buffers. But I've been struggling with describing the general semantics of "external roots", and this term is likely to change in the next version.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]