Follow Emacs guidelines/best practices in documentation/modules

[systemcrafters]

Follow Emacs guidelines/best practices in documentation/modules

[daviwil]

Either of those options in CI would be great!

[bkaestner]

Do you consider each module its own package? Or should the whole rational-emacs be considered a package? Depending on that we might need an additional rational-pkg.el in modules/ or need to fix a lot of lints, see https://github.com/bkaestner/rational-emacs/actions.

[daviwil]

Good question, I would technically consider each to be their own package. One of the goals was that each module should, in theory, be usable outside of Rational Emacs, though I don't know how realistic that will be in practice. What do you think is the best approach?

[bkaestner]

I'm not sure yet. At the moment, rational is not self-contained, as it needs/has some functionality in init.el and early-init.el. Without the appropriate user configuration, none of the packages can be loaded/byte compiled.

We probably need a rational.el base module first, that provides the functionality from the current init.el/early-init.el. On the one hand, that would also enable installation as a package from MELPA or similar. On the other hand, that's somewhat contradictory to creating a base distribution.

Hm. Maybe we could slim down the current {early-}init.el, put those functions into their own modules and load those modules instead? The biggest challenge might be the byte-compilation against packages that are unknown at byte-compile time if we don't take care.

[daviwil]

Maybe a new rational-core.el module that has the core functionality that is needed at init time? It would definitely make sense to pull all of the functions and variables we define out of the init.el files.

[daviwil]

rational.el (or rational-emacs.el) would also be fine if the customization group name somehow needs to be the same as the package name.

[jeastman]

Maybe a new rational-core.el module that has the core functionality that is needed at init time? It would definitely make
sense to pull all of the functions and variables we define out of the init.el files.

rational.el (or rational-emacs.el) would also be fine if the customization group name somehow needs to be the same as the package name.

PR #68 added to create a new module called rational-emacs.

The PR puts this new module in the top-level directory (where the init.el and early-init.el files are). If desired, this could be pushed into the modules directly.

[jeastman]

I've been struggling with the idea of what constitutes a "module" in this project. So far, it seems like we have defined that as a related set of configuration which is applied when the "module" is loaded.

The first item listed in Emacs manual entry (info "(elisp) Coding Conventions") states:

Simply loading a package should not change Emacs’s editing behavior. Include a command or commands to enable and disable the feature, or to invoke it.
This convention is mandatory for any file that includes custom definitions. If fixing such a file to follow this convention requires an incompatible change, go ahead and make the incompatible change; don’t postpone it.

Despite defining features (with provides), the modules in Rational Emacs don't really define "features" and typically change the editing behavior of Emacs directly.

It could be argued that Rational Emacs itself is the "package" and, outside of the early-init.el and init.el files, nothing is changed without requiring a specific "module". However, I think this is a bit of a stretch.

One way to address this is with the pattern used by global modes (using (example-mode) to toggle the mode) where a variable is used to track the enabled state of the module. Implementing this would require something along the lines of functions to "enable" and "disable" the module. I can envision this being controlled by an auto-loaded example-module (e.g. (rational-ui t)) function which is used to "turn on" the module instead of simply loading the module (e.g. (load 'rational-ui)).

If done cleanly, this would also provide the capability to use unload-feature to completely unload a module.

Implementing something of this nature would be a complex change (I think). I'm curious what other people think.

[jeffbowman]

There are parts I agree with, simply using require on a rationa-module should not necessarily intrinsically change how Emacs works. I don't think any of the "modules" follows the advice of changing how Emacs works. To follow that, we need to go back through all the modules and remove every key binding, as well as wrap a lot of things in functions a user would call in their own config. This is probably a good idea - we might want to look into it a bit more.

I'm not sure the concept of modes applies here though. I guess if I squint hard enough I can probably get there (ala rational-editing-mode, rational-ui-mode, etc). If we go that route, one additional advantage is hook functions to control the configuration of various aspects of a module (ie call the methods to turn on/off various features, etc). Still, the concept of modes here just doesn't fit in my mental model of what we are doing.

If we are providing a more sensible "out-of-the-box" experience for Emacs users, then we are possibly taking the "opinionated" approach to a starting Emacs configuration (examples might be how we configure whitespace, that we use vertico instead of selectrum, the absence of precient, etc.). If we are thinking a bit more generally to a framework of things you might want to use to build your own configuration, then we have some work to do (see my first paragraph), and the implication is the user must write their own configuration and they cannot just require a module (unless we put some ###autoload stuff in them) and expect some nifty behavior.

[jeastman]

I'm not sure the concept of modes applies here though.

I was not implying we should implement modes. Just referencing how modes work through via "turn on", "turn off" mechanism.

then we are possibly taking the "opinionated" approach to a starting Emacs configuration

I agree. By configuring defaults and general setup, it is an "opinionated" take on a "sensible starting point".

If we stick to a "sensible starting point", I don't think we end up with that much value. I think it is more like an "opinionated starting point" for "all the different things" you can configure. This is supported by the "categories" of modules ("UI related" -> rational-ui) we have started.

I think the problem comes in when we have all of the details to deal with. Different people have different opinions on different functionality. One of the great benefits of Emacs is that you can adjust that functionality to no end. If we take a stand on a "sensible" configuration of something, we likely need a way for that "thing" to be changed or ignored. Managing this could involve a lot of overhead and be no better than configuring the different features on your own. I believe this is in-line with what you are suggesting in your first paragraph.

The other alternative is we just provide the configuration as-is. It would serve as a model configuration with a strong opinion. If someone doesn't like a particular aspect of that configuration, they are left to fork and modify it. However, I am not so certain this was the original intent.

I do not, personally, have a strong grasp of what we expect a "module" in this project to do (or not do). Some of it feels invasive, some of it feels too light. I'd really like to hear what other people's expectations are.

[jeffbowman]

I was not implying we should implement modes. Just referencing how modes work through via "turn on", "turn off" mechanism.

Ah, gotcha... thanks for the clarification!

If we stick to a "sensible starting point", I don't think we end up with that much value. I think it is more like an "opinionated starting point" for "all the different things" you can configure. This is supported by the "categories" of modules ("UI related" -> rational-ui) we have started.

Agree

If we take a stand on a "sensible" configuration of something, we likely need a way for that "thing" to be changed or ignored. Managing this could involve a lot of overhead and be no better than configuring the different features on your own. I believe this is in-line with what you are suggesting in your first paragraph.

Yes. This is quite the conundrum. I feel that anything we do must be reversible by the eventual user should the choose to do so. Ideally, it would be easily reversible. This was the motivation to switch to advise-add rather than fset for the y-or-n-p stuff; fset is nearly impossible to reverse. If we instead stick with simply providing "opinionated sensible default" values for the defcustom variables of a package, this becomes a lot more manageable, the user only need customize the package differently in their own code to revert our opinion. This means we should not (as a general rule) provide custom key bindings as those are personal to the user and can also be difficult to override or revert (for example, try it with the evil-nerd-commenter package, I'm still fighting with it to find a good solution).

I'd really like to hear what other people's expectations are.

Yes, please!

[jeffbowman]

Closing in anticipation of Crafted Emacs V2