docs(format): redo docs to handle refactor
This commit is contained in:
Ellis Kenyő
Ellis Kenyo
parent
457aeeccc0
commit
926b8f1328
1 changed files with 80 additions and 115 deletions
|
|
@ -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?]]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue