Re: An anonymous IRC user's opinion

[Johan Myréen]

I understand Emacs is a volunteer project and finding good documentation writers is difficult. I was just suggesting what direction I would like to see Emacs documentation going. Emacs has a good and extensive manual that provides mostly a great reference to how to use Emacs as an editor. What I am proposing is a higher level view, a kind of cookbook on how to do different things with Emacs.

I just started my Emacs (from the main branch) with -q and opened a Rust source file. Emacs out of the box does not even recognize the .rs file extension: the file is opened in Fundamental mode. A novice Emacs user might guess that he or she needs to install a Rust mode for Emacs to recognize we are editing Rust source code. But by only doing this the user is missing out on so much useful functionality Emacs has to offer. How is the user supposed to know that ¨Eglot" is the way to connect to a language server, or that a package named ¨Company" provides completion? The only way right now is to search for this on the internet, which is associated with the quality problems I described in my previous message.

Software has grown more complex during the years Emacs has been in existence, and so have the expectations of the public using it. Emacs has fantastic collections of packages, each focusing on different things. This is a good modular design. Some of these packages can be used to form, for example, a working Rust development environment. The problem is finding these packages. How does a new Emacs user know what to look for?

So I am proposing a "task-oriented" category in the Emacs documentation. I don´t think there is such a category.

Eglot is part of Emacs, but it cannot be started automatically because the LSP server, which is a
separate piece of software, needs to be installed and configured first; are we supposed to be held
responsible for that as well

 

No, all I am talking about is documentation. In fact I really dislike some things that happen by magic, but are undocumented. They typically break over time, which is a bigger headache to fix than configuring things by hand using good documentation.

I'm guessing VSCode comes with pre-configured LSP servers, a single
Rust mode, and a single Git interface.  Am I mistaken?

No, VSCode does not come pre-configured for Rust development. But, there is a good, task-oriented web page that describes in simple terms what needs to be installed and configured to start writing Rust code using VSCode. Similar pages exist for Java, _javascript_, C++, C#, Python, Go, etc. More importantly, this documentation can be found on code.visualstudio.com (https://code.visualstudio.com/docs/languages/rust), not on YouTube.com or robert.kra.hn or some other random website.

Johan Myréen

On Wed, 9 Oct 2024 at 16:14, Eli Zaretskii <eliz@gnu.org> wrote:

> From: Johan Myréen <johan.myreen@gmail.com>
> Date: Wed, 9 Oct 2024 14:09:13 +0300
>
> I see this more as a documentation problem. Emacs lacks "official" documentation on how to configure an
> environment to do certain things, which includes installing certain Elisp packages, and configuring them.

My analysis is different.  Emacs lacks volunteers who'd sit down and
write documentation on how to configure Emacs for this or that job.
Once that is written, and written well, admitting it into Emacs is
usually a no-brainer.

Mind you: the above is an extremely non-trivial job, because the sheer
number of possible "jobs" which Emacs can support is mind-boggling.
Even if someone describes in excruciating detail how to configure
Emacs for Rust development, that only helps people who need to develop
programs in Rust, but doesn't help at all to, say, someone who needs to
write a thesis about some academic subject, or read email from Gmail
or even develop C++ programs, or...

> In the good old days software development meant editing a few C files in Emacs and then running make.
> This no longer meets the expectations people have of a software development environment. For example,
> creating a contemporary environment to write and build software using the Rust programming language and
> Emacs, you need Rust mode, rust-ts-mode for Treesitter integration, Eglot to communicate with
> rust-analyzer (a Language Server implementation for Rust) for completion and goto definition, Company
> mode for code completion, Magit for version control, DAP mode for debugging, and so on. Many of these
> packages have alternative implementations, for example rustic-mode instead of rust-mode.

This is an exaggeration to some degree.  rust-ts-mode is part of
Emacs, and could be turned on automatically when a Rust file is
visited; we didn't do that because we are unsure whether users of an
unbundled Rust mode will protest.  Eglot is part of Emacs, but it
cannot be started automatically because the LSP server, which is a
separate piece of software, needs to be installed and configured
first; are we supposed to be held responsible for that as well?  We do
have TAGS support for Rust (goto definition etc., so alternative to
LSP), and the new etags-regen-mode might just make the job of using
TAGS much easier and seamless.  Magit is nice, but not really
necessary, since we have VC built in, which doesn't need to be
configured.  DAP is not necessary, since Emacs has a GDB front-end
(which doesn't need to be configured, just invoked with a single
command), and GDB supports debugging Rust programs.

So things are not that bad, are they?

I do agree that good tutorials which would mention all this stuff
would make things better, at least for those who read documentation
(how many do?), but that needs volunteers to sit down and write that
up.  Would you please consider doing something like that for some jobs
with which you are familiar?

> I'm not saying you can't edit Rust code without all these packages, but these packages combined provide
> the minimum that the competition (e.g. Visual Studio Code) offers.

I'm guessing VSCode comes with pre-configured LSP servers, a single
Rust mode, and a single Git interface.  Am I mistaken?  If so, is that
how we want to treat our users? will they agree to be treated like
that?