-
Notifications
You must be signed in to change notification settings - Fork 114
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Follow Emacs guidelines/best practices in documentation/modules #59
Comments
Either of those options in CI would be great! |
Do you consider each module its own package? Or should the whole |
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? |
I'm not sure yet. At the moment, We probably need a Hm. Maybe we could slim down the current |
Maybe a new |
|
Attempts to address issue SystemCrafters#59. Fix for issue SystemCrafters#62. The contents of early-init.el and init.el have moved to functions in the rational-emacs.el file. early-init.el and init.el are updated to call the appropriate functions in this new module. All functions are updated to reflect the module name 'rational-emacs'.
PR #68 added to create a new module called 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 |
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:
Despite defining features (with It could be argued that One way to address this is with the pattern used by global modes (using If done cleanly, this would also provide the capability to use Implementing something of this nature would be a complex change (I think). I'm curious what other people think. |
There are parts I agree with, simply using 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 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 |
I was not implying we should implement modes. Just referencing how modes work through via "turn on", "turn off" mechanism.
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" -> 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. |
Ah, gotcha... thanks for the clarification!
Agree
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
Yes, please! |
Closing in anticipation of Crafted Emacs V2 |
As per
(info "(elisp) Tips for Documentation Strings")
, the function documentations should use the imperative verb forms:For example, within
rational-updates.el
, the documentation forrational-updates-check-for-latest
might be changed into:There are also many more tips in the given info page. We might consider
checkdoc
and/orpackage-lint
in the CI.The text was updated successfully, but these errors were encountered: