john-slop/docs/editors.md

112 lines
3.7 KiB
Markdown

# Editor setup
Both `john-slop-fmt` and `john-slop-lsp` are operational. The LSP publishes
configured ASCII-replacement warnings and versioned quick fixes; it does not
publish the broader heuristic evidence findings.
Install all three binaries somewhere on `PATH`, then confirm the editor-facing
help is available:
```sh
john-slop-fmt --help
john-slop-lsp --help
```
## Helix (`hx` / `helix-term`)
Helix configures formatters and language servers in `languages.toml`. Put this
in `~/.config/helix/languages.toml` on Linux, or in `.helix/languages.toml` for
project-local configuration:
```toml
[language-server.john-slop]
command = "john-slop-lsp"
[[language]]
name = "john-slop-text"
language-id = "plaintext"
scope = "text.john-slop"
file-types = ["txt"]
formatter = { command = "john-slop-fmt" }
language-servers = ["john-slop"]
auto-format = false
```
This complete custom language entry makes the repository's `example.txt`
fixtures useful without depending on a built-in plain-text grammar. Use
`:format` to run the formatter. Set `auto-format = true` only if save-time
replacement is wanted.
For an existing language, merge John Slop into that language's entry rather
than replacing its useful defaults. For example, Rust should retain
`rust-analyzer`:
```toml
[[language]]
name = "rust"
formatter = { command = "john-slop-fmt" }
language-servers = ["rust-analyzer", "john-slop"]
```
Run `hx --health rust` (or the selected language name) to confirm both binaries
are visible. Helix documents that a formatter reads the buffer from stdin and
writes it to stdout, while an LSP command must be on `PATH`; those are the
contracts the two John Slop milestones target. See the official
[Helix language configuration reference](https://docs.helix-editor.com/languages.html).
## Vim
Vim's native `formatprg` option is enough for formatting. Add this to
`~/.vimrc`:
```vim
augroup john_slop_format
autocmd!
autocmd BufRead,BufNewFile *.txt setfiletype text
autocmd FileType text,markdown,rust setlocal formatprg=john-slop-fmt
augroup END
```
Use `gggqG` to filter the whole buffer through the formatter, or select a range
and press `gq`. Vim requires `formatprg` programs to read stdin and write stdout;
see the official [`formatprg` and `gq` help](https://vimhelp.org/options.txt.html#%27formatprg%27).
Classic Vim needs an LSP client plugin. With
[`prabirshrestha/vim-lsp`](https://github.com/prabirshrestha/vim-lsp), register
John Slop in `~/.vimrc`:
```vim
if executable('john-slop-lsp')
au User lsp_setup call lsp#register_server({
\ 'name': 'john-slop',
\ 'cmd': {server_info->['john-slop-lsp']},
\ 'allowlist': ['text', 'markdown', 'rust'],
\ })
endif
```
Use the plugin's `:LspStatus`, `:LspNextDiagnostic`, and `:LspCodeAction`
commands to inspect server state, move through replacement diagnostics, and
apply the ASCII quick fix. The registration shape and `allowlist` follow the
plugin's current upstream documentation.
The server uses the same configuration layers as the other binaries. Add
`args = ["--config-name", "editorial"]` to the Helix language-server table, or
append those arguments to the Vim `cmd` list, when an editor-specific named
configuration is wanted. `--log-json` is available for troubleshooting and
writes lifecycle metadata to stderr without document contents.
## Try the shared fixtures
Open `examples/fixtures/typography/example.txt` in either editor. Its expected
formatter result is the adjacent `formatted.txt`; the shared manifest records
three replacements and one typography rule. Compare detector and formatter
output with:
```sh
cargo run --bin john-slop -- --output concise \
examples/fixtures/typography/example.txt
cargo run --bin john-slop-fmt -- \
examples/fixtures/typography/example.txt
```