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

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

[Dmitry Gutov]

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.

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

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sat, 21 Mar 2020 23:19:25 +0200
> 
> > +* 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.

Yes, I was aware of that.  But since saying that a project is a
collection of arbitrary files would make the issue harder to
understand, I decided to compromise, as I believe currently no one
really uses this for non-program files.  If this ever becomes a
practical problem, we can always rephrase.

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

Well, it looked to me that at least on the command level we rally
expect to have one root, so the current wording is still okay.
Especially if the multiple-roots alternative will be going away.

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

I think it's the same thing.  Wed use both interchangeably in our
documentation.  Why, you think "directory tree" will be easier to
understand or something?

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

Likewise.  I decided not to document it for now.  If it proves to be
popular, we can add it in the future.

Thanks.

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

[Dmitry Gutov]

On 22.03.2020 16:18, Eli Zaretskii wrote:
>> From: Dmitry Gutov <dgutov@yandex.ru>
>> Date: Sat, 21 Mar 2020 23:19:25 +0200
>>
>>> +* 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.
> 
> Yes, I was aware of that.  But since saying that a project is a
> collection of arbitrary files would make the issue harder to
> understand,

Regardless of how we define a project, this heading can say "Commands 
for handling files in a project" without a loss of clarify, I believe.

> I decided to compromise, as I believe currently no one
> really uses this for non-program files.  If this ever becomes a
> practical problem, we can always rephrase.

You're probably responding to my second quote here. But why not say 
"Command for handling files in a project"? Again, no real loss of 
clarity, this sentence is not a definition.

But later, we could say something like:

   A project is a collection of files united by common purpose (for 
example, used for producing one or more programs)

Maybe no one uses project-find-file currently for other purposes, but 
they surely can. And people do use Emacs for other purposes. And the 
manual is the way we tell people about what's possible, isn't it?

>>> 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.
> 
> Well, it looked to me that at least on the command level we rally
> expect to have one root, so the current wording is still okay.

Um, not really. All built-in commands should work with multi-root 
projects fine. We don't have any such project backends, though.

> Especially if the multiple-roots alternative will be going away.

True.

>> And is "hierarchy of directories" a better term than "directory tree"?
> 
> I think it's the same thing.  Wed use both interchangeably in our
> documentation.  Why, you think "directory tree" will be easier to
> understand or something?

This choice of words gives me a somewhat more complicated mental image, 
like a sparse collection of subdirectories, where some are included, and 
some are not. Which kind of comes out to the same thing, but in a more 
complex way.

>> 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.
> 
> Likewise.  I decided not to document it for now.  If it proves to be
> popular, we can add it in the future.

Fair enough.

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

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Sun, 22 Mar 2020 23:24:13 +0200
> 
> > Yes, I was aware of that.  But since saying that a project is a
> > collection of arbitrary files would make the issue harder to
> > understand,
> 
> Regardless of how we define a project, this heading can say "Commands 
> for handling files in a project" without a loss of clarify, I believe.

It isn't about clarity, I think, it's about making the feature less
abstract and more lucrative to our audience.

> > I decided to compromise, as I believe currently no one
> > really uses this for non-program files.  If this ever becomes a
> > practical problem, we can always rephrase.
> 
> You're probably responding to my second quote here. But why not say 
> "Command for handling files in a project"? Again, no real loss of 
> clarity, this sentence is not a definition.

For the same reason: to be more attractive to the reader.

> >> And is "hierarchy of directories" a better term than "directory tree"?
> > 
> > I think it's the same thing.  Wed use both interchangeably in our
> > documentation.  Why, you think "directory tree" will be easier to
> > understand or something?
> 
> This choice of words gives me a somewhat more complicated mental image, 
> like a sparse collection of subdirectories, where some are included, and 
> some are not. Which kind of comes out to the same thing, but in a more 
> complex way.

That's not what I had in mind, but these commands do support sparse
trees as well: it's all about what are "the project files", isn't it?

Would "directory tree hierarchy" solve your problems here?

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

[Dmitry Gutov]

On 23.03.2020 16:29, Eli Zaretskii wrote:

>> Regardless of how we define a project, this heading can say "Commands
>> for handling files in a project" without a loss of clarify, I believe.
> 
> It isn't about clarity, I think, it's about making the feature less
> abstract and more lucrative to our audience.

I'm rather against this part because it brings in an inaccuracy as well: 
all project commands work on arbitrary kinds of files. Not just source 
files, but documentation, build configuration, etc.

And making it seem like they handle only a subset of what they actually 
do doesn't sound "lucrative" to me.

>>> I decided to compromise, as I believe currently no one
>>> really uses this for non-program files.  If this ever becomes a
>>> practical problem, we can always rephrase.
>>
>> You're probably responding to my second quote here. But why not say
>> "Command for handling files in a project"? Again, no real loss of
>> clarity, this sentence is not a definition.
> 
> For the same reason: to be more attractive to the reader.

That makes an assumption that the reader is a programmer.

>>>> And is "hierarchy of directories" a better term than "directory tree"?
>>>
>>> I think it's the same thing.  Wed use both interchangeably in our
>>> documentation.  Why, you think "directory tree" will be easier to
>>> understand or something?
>>
>> This choice of words gives me a somewhat more complicated mental image,
>> like a sparse collection of subdirectories, where some are included, and
>> some are not. Which kind of comes out to the same thing, but in a more
>> complex way.
> 
> That's not what I had in mind, but these commands do support sparse
> trees as well: it's all about what are "the project files", isn't it?

True.

> Would "directory tree hierarchy" solve your problems here?

It's still a more complex explanation than I would choose. But please 
never mind me here, in the end you probably know your the audience (the 
people who read the manuals) better.

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

[Eli Zaretskii]

OK, let's just leave it at that.  We disagree here, and I don't think
the disagreements are worth any further argument.

Thanks.