docs(format): redo docs to handle refactor

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
+Code style is something that's hotly debated since the beginning of time.
-formatters that it currently supports:
 
-#+begin_quote
+Tabs or spaces?
-asmfmt, black, brittany, cabal-fmt, clang-format, cmake-format, dartfmt, dfmt,
+2-width or 4-width indentation?
-dhall format, dockfmt, elm-format, emacs, fish_indent, fprettify, gleam format,
+
-gofmt, iStyle, jsonnetfmt, ktlint, latexindent, ledger-mode, lua-fmt, mix
+Which is right? Doom doesn't care, but we will try and make it easy for you to
-format, nixfmt, node-cljfmt, ocp-indent, perltidy, prettier, purty, rufo,
+format code within the safety of Emacs.
-rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy
+
-#+end_quote
+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:
+As of writing this, apheleia doesn't /yet/ support regions or similar kinds of
-  - Reformatted text is applied to the buffer by RCS patch, as to reduce its
+buffers, so there are a couple of hacks to attempt to rectify this.
-    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).
 
 ** TODO Changelog
 # This section will be machine generated. Don't edit it by hand.
@@ -51,97 +44,63 @@ 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:
+To see if a particular mode has a configured formatter, check for the mode in
-- Angular/Vue (prettier)
+[[var:apheleia-mode-alist]] which corresponds to the list of formatters defined in
-- Assembly (asmfmt)
+[[var:apheleia-formatters]]
-- 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)
 
-* TODO Usage
+* Usage
-#+begin_quote
+** With +onsave
- 🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
+When this flag is enabled, you shouldn't need to do anything other than write
-#+end_quote
+code and save it.
 
-* TODO Configuration
+** Without +onsave
-#+begin_quote
+Without the flag, formatting will only occur when either =apheleia-format-buffer=
- 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
+or =+format/buffer= is called.
-#+end_quote
 
-** Automatic reformatting when saving buffers
+* Configuration
-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
+Detailed configuration can be found [[https://github.com/radian-software/apheleia/#user-guide][upstream]], but for most purposes here we
-enabled in.
+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
+(set-formatter! 'unique-name '("command" "line" "here") :modes '(name-of-major-mode))
-      '(not emacs-lisp-mode  ; elisp's mechanisms are good enough
+#+end_src
+
+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
+(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
 
-If you want to format code when you save a buffer, but want more granular
+In this case, =emacs-lisp-mode=, =sql-mode=, =tex-mode= and =latex-mode= will not be
-control over which major modes this behavior is enabled in, there is an
+formatted on save, but can still be formatted by manually invoking the commands
-alternative. Make sure [[doom-module:+onsave]] is disabled before you try this:
+=apheleia-format-buffer= or =+format/buffer=.
-#+begin_src emacs-lisp
-(add-hook 'python-mode-hook #'format-all-mode)
-(add-hook 'js2-mode-hook #'format-all-mode)
-#+end_src
 
 ** Disabling the LSP formatter
 If you are in a buffer with ~lsp-mode~ enabled and a server that supports
@@ -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
+** Selecting a specific formatter for a particular buffer
-See the ~set-formatter!~ function.
-
-** TODO 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
+;; Or set it to `nil' to fallback to `apheleia-mode-alist`
-(setq-hook! 'python-mode-hook +format-with :none)
+(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
+looked up in the ~apheleia-mode-alist~ hash table.
-code]].
 
 * 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?]]