docs(:editor): update READMEs to new format
This commit is contained in:
Henrik Lissner
Henrik Lissner
parent
c27f005011
commit
9ada400805
13 changed files with 877 additions and 531 deletions
|
|
@ -1,30 +1,17 @@
|
|||
#+TITLE: editor/format
|
||||
#+DATE: July 25, 2020
|
||||
#+SINCE: v3.0.0
|
||||
#+STARTUP: inlineimages nofold
|
||||
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::editor format][Issues]] ↖ [[doom-module-source:editor/format][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
|
||||
--------------------------------------------------------------------------------
|
||||
#+TITLE: :editor format
|
||||
#+SUBTITLE: Standardize your ugly code
|
||||
#+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]].
|
||||
🔨 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
|
||||
|
||||
* Table of Contents :TOC_3:noexport:
|
||||
- [[#description][Description]]
|
||||
- [[#maintainers][Maintainers]]
|
||||
- [[#module-flags][Module Flags]]
|
||||
- [[#plugins][Plugins]]
|
||||
- [[#hacks][Hacks]]
|
||||
- [[#prerequisites][Prerequisites]]
|
||||
- [[#features][Features]]
|
||||
- [[#configuration][Configuration]]
|
||||
- [[#automatic-reformatting-when-saving-buffers][Automatic reformatting when saving buffers]]
|
||||
- [[#disabling-the-lsp-formatter][Disabling the LSP formatter]]
|
||||
- [[#defining-your-own-formatters][Defining your own formatters]]
|
||||
- [[#selecting-a-specific-formatter-for-a-particular-buffer][Selecting a specific formatter for a particular buffer]]
|
||||
- [[#troubleshooting][Troubleshooting]]
|
||||
|
||||
* Description
|
||||
* Description :unfold:
|
||||
This module integrates code formatters into Emacs. Here are some of the
|
||||
formatters that it currently supports:
|
||||
|
||||
|
|
@ -37,88 +24,102 @@ rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy
|
|||
#+end_quote
|
||||
|
||||
** Maintainers
|
||||
This module has no dedicated maintainers.
|
||||
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
|
||||
|
||||
** Module Flags
|
||||
+ =+onsave= Preform buffer-wide reformatting of a buffer when you save it. See
|
||||
~+format-on-save-enabled-modes~ to control what major modes to (or not to)
|
||||
** 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)
|
||||
format on save.
|
||||
|
||||
** Plugins
|
||||
+ [[https://github.com/lassik/emacs-format-all-the-code][format-all]]
|
||||
** Packages
|
||||
- [[doom-package:][format-all]]
|
||||
|
||||
** 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
|
||||
- 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 ~+format/buffer~ or ~+format/region~ (i.e.
|
||||
- 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).
|
||||
|
||||
* Prerequisites
|
||||
This module depends on external programs to perform the actual formatting. These
|
||||
will need to be installed for them to work. In their absence, =format-all= will
|
||||
fail silently.
|
||||
** TODO Changelog
|
||||
# This section will be machine generated. Don't edit it by hand.
|
||||
/This module does not have a changelog yet./
|
||||
|
||||
+ 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)
|
||||
* Installation
|
||||
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
||||
|
||||
* TODO Features
|
||||
# An in-depth list of features, how to use them, and their dependencies.
|
||||
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.
|
||||
|
||||
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)
|
||||
|
||||
* TODO Usage
|
||||
#+begin_quote
|
||||
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
|
||||
#+end_quote
|
||||
|
||||
* TODO Configuration
|
||||
#+begin_quote
|
||||
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||||
#+end_quote
|
||||
|
||||
* Configuration
|
||||
** 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
|
||||
|
|
@ -128,29 +129,29 @@ 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 elisp
|
||||
#+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))
|
||||
#+END_SRC
|
||||
#+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 =+onsave= is disabled before you try this:
|
||||
|
||||
#+BEGIN_SRC elisp
|
||||
alternative. Make sure [[doom-module:][+onsave]] is disabled before you try this:
|
||||
#+begin_src emacs-lisp
|
||||
(add-hook 'python-mode-hook #'format-all-mode)
|
||||
(add-hook 'js2-mode-hook #'format-all-mode)
|
||||
#+END_SRC
|
||||
#+end_src
|
||||
|
||||
** 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 =format-all='s formatter.
|
||||
=textDocument/formatting=, it will be used instead of [[doom-package:][format-all]]'s formatter.
|
||||
|
||||
+ To disable this behavior universally use: ~(setq +format-with-lsp nil)~
|
||||
+ To disable this behavior in one mode: ~(setq-hook! 'python-mode-hook +format-with-lsp nil)~
|
||||
+ 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.
|
||||
|
|
@ -158,17 +159,24 @@ 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 elisp
|
||||
#+begin_src emacs-lisp
|
||||
(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)
|
||||
#+END_SRC
|
||||
#+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]].
|
||||
|
||||
* Troubleshooting
|
||||
# Common issues and their solution, or places to look for help.
|
||||
/There are no known problems with this module./ [[doom-report:][Report one?]]
|
||||
|
||||
* Frequently asked questions
|
||||
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
||||
|
||||
* TODO Appendix
|
||||
#+begin_quote
|
||||
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
||||
#+end_quote
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue