142 lines
5.5 KiB
Markdown
142 lines
5.5 KiB
Markdown
# Editor setup
|
|
|
|
Both `john-slop-fmt` and `john-slop-lsp` are operational. The LSP publishes only
|
|
configured Unicode replacement and control findings by default, keeping noisy
|
|
or error-prone heuristics out of the normal editor loop. Safe ASCII-replacement
|
|
findings additionally provide versioned quick fixes, and the server implements
|
|
whole-document formatting with the exact same replacement planner as
|
|
`john-slop-fmt`.
|
|
|
|
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. It selects
|
|
the external `john-slop-fmt` adapter. To exercise formatting through the LSP
|
|
instead, omit the `formatter = ...` line; `:format` then requests
|
|
`textDocument/formatting` from `john-slop-lsp`. Both routes resolve the same
|
|
configuration and produce the same text. 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"]
|
|
```
|
|
|
|
When several language servers advertise formatting, retain an explicit Helix
|
|
`formatter` or select the intended server interactively; John Slop must not
|
|
silently replace language-specific formatting from `rust-analyzer` or another
|
|
primary server.
|
|
|
|
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 heuristic diagnostics, and apply
|
|
available ASCII quick fixes. The registration shape and `allowlist` follow the
|
|
plugin's current upstream documentation.
|
|
|
|
Clients that expose LSP document formatting can request it directly from John
|
|
Slop instead of configuring `formatprg`; both paths use the same replacement
|
|
catalog. Keep `formatprg=john-slop-fmt` when the Vim client cannot select one
|
|
formatter among multiple attached language servers.
|
|
|
|
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. Use `args = ["--diagnostics", "diagnostics.toml"]` (and
|
|
the equivalent Vim command argument) for a project runtime diagnostic catalog.
|
|
Add `--all-diagnostics` to exercise every configured rule during testing, or
|
|
`--minimum-diagnostic-weight 10` to retain Unicode findings and opt into only
|
|
non-Unicode findings with weight 10 or greater. This visibility filter does not
|
|
change detector scoring or formatting.
|
|
`--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
|
|
```
|
|
|
|
After starting the server with `--all-diagnostics`, open
|
|
`examples/fixtures/style/example.txt` to see `repeated-transition` and other
|
|
style findings, or `examples/fixtures/source/example.rs` to see source-only
|
|
placeholder and narration findings alongside typography. Advice maps to LSP
|
|
information, warnings to warnings, and configured errors to errors. Every
|
|
diagnostic carries its stable heuristic rule ID as the code and includes the
|
|
configured remediation text.
|