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: Sun, 22 Mar 2020 23:24:13 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1

On 22.03.2020 16:18, Eli Zaretskii wrote:
From: Dmitry Gutov <address@hidden>
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.



reply via email to

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