From 926b8f132862dbcbc0a23c77765180d2a75bbc61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ellis=20Keny=C5=91?= Date: Sat, 19 Nov 2022 16:43:31 +0000 Subject: [PATCH] docs(format): redo docs to handle refactor --- modules/editor/format/README.org | 195 +++++++++++++------------------ 1 file changed, 80 insertions(+), 115 deletions(-) diff --git a/modules/editor/format/README.org b/modules/editor/format/README.org index dd23f3988..bb38e23a7 100644 --- a/modules/editor/format/README.org +++ b/modules/editor/format/README.org @@ -3,44 +3,37 @@ #+created: July 26, 2020 #+since: 21.12.0 -#+begin_quote - 🔨 This module has been scheduled for a rewrite. Its documentation will remain - incomplete and edge cases left unpatched in the meantime. A preview of this - rewrite can be found [[https://github.com/hlissner/doom-emacs-private/tree/master/modules/editor/format][in my private config]]. -#+end_quote - * Description :unfold: -This module integrates code formatters into Emacs. Here are some of the -formatters that it currently supports: +Code style is something that's hotly debated since the beginning of time. -#+begin_quote -asmfmt, black, brittany, cabal-fmt, clang-format, cmake-format, dartfmt, dfmt, -dhall format, dockfmt, elm-format, emacs, fish_indent, fprettify, gleam format, -gofmt, iStyle, jsonnetfmt, ktlint, latexindent, ledger-mode, lua-fmt, mix -format, nixfmt, node-cljfmt, ocp-indent, perltidy, prettier, purty, rufo, -rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy -#+end_quote +Tabs or spaces? +2-width or 4-width indentation? + +Which is right? Doom doesn't care, but we will try and make it easy for you to +format code within the safety of Emacs. + +At present, the module wraps [[https://github.com/radian-software/apheleia/][apheleia]], which includes some more detail on the +internals of the package; but the long and short of it is on-save your code will +be formatted and returned to the buffer using +[[https://tools.ietf.org/doc/tcllib/html/rcs.html#section4][RCS patching]]. ** Maintainers -/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] +- [[doom-user:][@elken]] + +[[doom-contrib-maintainer:][Become a maintainer?]] ** Module flags - +onsave :: Enable reformatting of a buffer when it is saved. See - [[var:+format-on-save-enabled-modes]] to control what major modes to (or not to) + [[var:+format-on-save-disabled-modes]] to control what major modes to (or not to) format on save. ** Packages -- [[doom-package:format-all]] +- [[doom-package:apheleia]] ** Hacks -- format-all has been heavily modified to suit Doom's goals for this module: - - Reformatted text is applied to the buffer by RCS patch, as to reduce its - affect on cursor position. - - Adds partial formatting, i.e. you can now reformat a subset of the buffer. - - Adds the ability to use any arbitrary formatter on the current buffer if you - pass the universal argument to [[fn:+format/buffer]] or [[fn:+format/region]] (i.e. - removes the major-mode lock on formatters). +As of writing this, apheleia doesn't /yet/ support regions or similar kinds of +buffers, so there are a couple of hacks to attempt to rectify this. ** TODO Changelog # This section will be machine generated. Don't edit it by hand. @@ -51,98 +44,64 @@ rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy This module has no direct requirements, but each language will need one of their supported formatter programs in order for this to work. In their absence, -[[doom-package:format-all]] will fail silently. +[[doom-package:apheleia]] will fail silently. -Supported formatters: -- Angular/Vue (prettier) -- Assembly (asmfmt) -- Bazel Starlark (buildifier) -- BibTeX (emacs) -- C/C++/Objective-C (clang-format) -- Cabal (cabal-fmt) -- Clojure/ClojureScript (node-cljfmt) -- CMake (cmake-format) -- Crystal (crystal tool format) -- CSS/Less/SCSS (prettier) -- D (dfmt) -- Dart (dartfmt) -- Dhall (dhall format) -- Dockerfile (dockfmt) -- Elixir (mix format) -- Elm (elm-format) -- Emacs Lisp (emacs) -- Fish Shell (fish_indent) -- Fortran 90 (fprettify) -- Gleam (gleam format) -- Go (gofmt) -- GraphQL (prettier) -- Haskell (brittany) -- HTML/XHTML/XML (tidy) -- Java (clang-format) -- JavaScript/JSON/JSX (prettier) -- Jsonnet (jsonnetfmt) -- Kotlin (ktlint) -- LaTeX (latexindent) -- Ledger (ledger-mode) -- Lua (lua-fmt) -- Markdown (prettier) -- Nix (nixfmt) -- OCaml (ocp-indent) -- Perl (perltidy) -- PHP (prettier plugin-php) -- Protocol Buffers (clang-format) -- PureScript (purty) -- Python (black) -- R (styler) -- Ruby (rufo) -- Rust (rustfmt) -- Scala (scalafmt) -- Shell script (shfmt) -- Snakemake (snakefmt) -- Solidity (prettier-plugin-solidity) -- SQL (sqlformat) -- Swift (swiftformat) -- Terraform (terraform fmt) -- TOML (prettier-plugin-toml) -- TypeScript/TSX (prettier) -- Verilog (iStyle) -- YAML (prettier) +To see if a particular mode has a configured formatter, check for the mode in +[[var:apheleia-mode-alist]] which corresponds to the list of formatters defined in +[[var:apheleia-formatters]] -* TODO Usage -#+begin_quote - 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] -#+end_quote +* Usage +** With +onsave +When this flag is enabled, you shouldn't need to do anything other than write +code and save it. -* TODO Configuration -#+begin_quote - 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] -#+end_quote +** Without +onsave +Without the flag, formatting will only occur when either =apheleia-format-buffer= +or =+format/buffer= is called. -** Automatic reformatting when saving buffers -There are two ways to achieve this. Either through the =+onsave= flag, or by -adding ~format-all-mode~ to the hook of each major mode you want this behavior -enabled in. +* Configuration + +Detailed configuration can be found [[https://github.com/radian-software/apheleia/#user-guide][upstream]], but for most purposes here we +provide a simple macro that looks like the below: -If you choose the former, what modes it applies to can be changed by modifying -~+format-on-save-enabled-modes~, which contains a list of major modes. If the -first item in the list is the symbol ~not~, the list is negated. This is its -default value: #+begin_src emacs-lisp -(setq +format-on-save-enabled-modes - '(not emacs-lisp-mode ; elisp's mechanisms are good enough - sql-mode ; sqlformat is currently broken - tex-mode ; latexindent is broken - latex-mode)) +(set-formatter! 'unique-name '("command" "line" "here") :modes '(name-of-major-mode)) #+end_src -If you want to format code when you save a buffer, but want more granular -control over which major modes this behavior is enabled in, there is an -alternative. Make sure [[doom-module:+onsave]] is disabled before you try this: +There are a few bonus symbols that apheleia uses (for example =npx= will be +replaced by a correct path to npx) which are all documented in the link above. + +** Disabling formatters +*** Permanently +To permanently disable a particular formatter with no provided alternative + #+begin_src emacs-lisp -(add-hook 'python-mode-hook #'format-all-mode) -(add-hook 'js2-mode-hook #'format-all-mode) +(setq apheleia-formatters (delq (assoc 'csharpier apheleia-formatters) apheleia-formatters)) #+end_src +*** Per-buffer +If you want to save without formatting, this is done by first passing the +universal argument thus; =SPC u SPC f s= for evil users, =C-u C-x C-s= for non-evil +users. + +If you want to save more than a handful of time, you can set +[[var:apheleia-inhibit]] to disable even if =apheleia-global-mode= is on. + +*** Onsave only +This behaviour is controlled via [[var:+format-on-save-disabled-modes]] thus; + +#+begin_src emacs-lisp +(setq +format-on-save-disabled-modes + '(emacs-lisp-mode ; elisp's mechanisms are good enough + sql-mode ; sqlformat is currently broken + tex-mode ; latexindent is broken + latex-mode)) +#+end_src + +In this case, =emacs-lisp-mode=, =sql-mode=, =tex-mode= and =latex-mode= will not be +formatted on save, but can still be formatted by manually invoking the commands +=apheleia-format-buffer= or =+format/buffer=. + ** Disabling the LSP formatter If you are in a buffer with ~lsp-mode~ enabled and a server that supports =textDocument/formatting=, it will be used instead of [[doom-package:format-all]]'s formatter. @@ -151,25 +110,31 @@ If you are in a buffer with ~lsp-mode~ enabled and a server that supports + To disable this behavior in one mode: ~(setq-hook! 'python-mode-hook +format-with-lsp nil)~ -** TODO Defining your own formatters -See the ~set-formatter!~ function. - -** TODO Selecting a specific formatter for a particular buffer +** Selecting a specific formatter for a particular buffer Set the buffer-local variable ~+format-with~ to the name of the formatter to use. e.g. #+begin_src emacs-lisp +;; Overrides `apheleia-mode-alist` (setq-hook! 'python-mode-hook +format-with 'html-tidy) -;; Or set it to `:none' to disable formatting -(setq-hook! 'python-mode-hook +format-with :none) +;; Or set it to `nil' to fallback to `apheleia-mode-alist` +(setq-hook! 'python-mode-hook +format-with nil) #+end_src Formatters are referred to by the name they were defined with. They can be -looked up in the ~format-all-mode-table~ hash table or in format-all's [[https://github.com/lassik/emacs-format-all-the-code/blob/master/format-all.el#L512][source -code]]. +looked up in the ~apheleia-mode-alist~ hash table. * Troubleshooting -/There are no known problems with this module./ [[doom-report:][Report one?]] +There are a few fail-safes apheleia has to prevent accidental code wipe, +included silently failing if the command errors or doesn't exist. + +Check that the command you've specified runs fine in a terminal first before +reporting this as an issue. + +If any errors are reported from the command, run =apheleia-goto-error= to jump to +the error buffer and handle any problems raised there. + +Any issues specific to apheleia should most often be reported upstream [[https://github.com/radian-software/apheleia/issues][here]]. * Frequently asked questions /This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]