Configuration, customization, hooks

[lassik]

From the MELPA PR thread:

@lassik: I thought some more about the minor mode and before-save-hook and the customize variables and I'd like to hold off on those for now because It's far from obvious how to do them right.

The thing is that everyone working on a particular codebase should really be using the same external formatter with the same settings (whether they use Emacs, Vim or any other editor). Otherwise version control diffs will eventually turn into a mess and much of the point of auto-formatting in the first place is moot. This implies that formatter settings should really be stored in an editor-independent file that is checked into version control. (Ideally some existing settings file such as .editorconfig would be extended for this purpose instead of making Yet Another Dotfile with its own syntax and filename globbing rules :))

So basically, I think any effort that we spent putting code formatting settings in Emacs would only serve to detract from the much more important goal of specifying a unified cross-editor settings file. We should work together with people from the Vim, Atom and other communities to make it a reality sooner. Once a de facto cross-editor standard is agreed upon, we can then add a global minor mode for Emacs and people can leave it always enabled and not worry about configuring it specifically for Emacs. (EDIT: Maybe we should just wait for Unibeautify to finish this, they already have this: https://unibeautify.com/docs/config-file.html)

@purcell: I get your point about standardising configuration into .editorconfig etc., and supporting such a thing is a worthy goal that isn't in conflict with providing good Emacs-only configuration for the package: if format-all had a very Emacs-oriented configuration system, then it would be easy to translate settings to it from any editorconfig standard that might arise.

[lassik]

I thought about this some more.

---

The domain model from the user's point of view would seem to be:

• A particular codebase has particular style settings.

• The settings are stored in a file in version control.

• The settings are needed by:

  • Auto-formatters
  • Text editors (e.g. Emacs modes with buffer-local settings for indent-tabs-mode, c-basic-offset etc.)

• When you open an existing file in an existing project, or create a new file in that project, the text editor should match the style specified in the project's settings file.

• Additionally, text editors need default settings for new projects so that code looks the way you want right away when you start typing. That's what the global customizable values for indent-tabs-mode, c-basic-offset etc. are for - to specify your preferred default style for new projects or little throwaway programs.

• (It's possible to manually change the buffer-local value of c-basic-offset and other such variables without changing them in a settings file. To provide a seamless experience, any external auto-formatters called by Emacs should reflect the changed buffer-local values, overriding the project's settings file. However, it's a little difficult to see the point of this activity since)

  • All but the shortest-lived projects should have a settings file.
  • The settings file should be correct, and fixes and updates should be committed to version control instead of each developer doing ad-hoc fixes for themselves.
  • The buffer-local values are probably more likely to deviate from the project settings file by accident than by purpose.

---

The domain model we need in software would be:

• A file (e.g. .unibeautifyrc.yml or .editorconfig) in the root directory of each project (or sub-project) containing style settings in a universal format understood by all text editors and auto-formatters (one can dream).

• Each auto-formatter maps the universal settings to its own internal settings. (Ideally, the internal settings are a 1:1 copy of the relevant universal settings). The auto-formatter reads the universal settings from the universal settings file or from command line arguments. If it can't read the universal settings directly, we need a translator from the universal settings to the formatter's settings.

• Each text editor maps the universal settings to its own internal settings. (In Emacs, some settings are global like indent-tabs-mode, some are shared by many modes like c-basic-offset, and some are specific to a particular mode like lisp-backquote-indentation.) We need a translator from the universal settings to the text editor's settings. In Emacs, we should probably have one package that contains the translations for all universal settings pertaining to all languages - that's the easiest way to keep them in sync with updates to the universal standard. It might be useful for the translation to be bidirectional, so that Emacs can create or update the universal settings file based on a buffer's variables.

• When a text editor like Emacs calls an external formatter, what to do? If we're editing a file in an existing project and the formatter can read the settings directly from the universal settings file itself, we're done. We could also parse the settings file in Emacs and give the settings to the formatter as command line arguments.

• If we're editing a temp buffer that doesn't have a filename, or we're editing a file in a new project that doesn't have a universal settings file, this is the thorny case. We could have a mapping:

  • Emacs settings -> universal settings -> a particular formatter's settings, or:
  • Emacs settings -> a particular formatter's settings

But I would really like to avoid coding and maintaining such mappings in Emacs. It sounds like a very thankless job, without a clear payoff, and difficult to do well.

---

What's important to note here is that in no case should format-all have its own customize variables for things like indent style and brace placement. If it concerns itself with such variables at all, it should re-use the ones from Emacs and its major modes. The maximum amount of configuration we should have is picking which formatter to use for what language.

We could also let the user set command line switches for each formatter, but I think that's a really bad fit to the above model - it re-uses neither Emacs own variables, nor the proposed universal style settings, but introduces a third set of redundant settings to concern ourselves with (actually, N extra sets, since many formatters are again bound to have different names for the same things).

[lassik]

TL;DR: This is a social problem, not a technical one. Let's be social.

What I'd really like us to do:

• Find the best / most comprehensive / most popular / most promising universal settings file done by others. Is it .unibeautifyrc? .editorconfig extension? In any case there should be only one such file. Supporting multiple different files for basically the exact same job is a huge waste of effort and will only prolong the current decades-long state of affairs where there is no standard for this now-obvious task :-(

• Write an Emacs package to read that file to get Emacs variables (c-basic-offset, etc.) so that editing code works nicely.

• Use that file to pick which external formatter format-all should use for each language. Eventually just use unibeautify for everything if they do a really good job of it?

• The external formatter either reads its settings from that file, or it doesn't. It could also read its settings from some formatter-specific file that people will add to their projects (like .clang-format). In any case, Emacs doesn't make an effort to send any settings to the formatter (since that would mainly be useful for throwaway programs and temp buffers). Talk to formatters' maintainers and persuade them to adopt the universal settings file. If they won't adopt that file maybe they'll adopt some config file, whatever it is. That's better than only getting ad hoc settings from text editors that may or may not send all the right ones.

• Years from now, if lots of formatters have adopted the universal standard settings, we could add a feature to format-all to translate Emacs settings to the universal ones and send them to compliant formatters via command line arguments. This would solve the issue with temp buffers and new projects.

[oscu0]

As someone who almost always works on single files, I'd appreciate if this package never demanded local configuration and other such things. This package is very important to me - I've started and quit switching to Emacs for the first time because of a lack of a universal formatting frontend.