john-slop/docs/editors.md

3.3 KiB

Editor setup

Current status: john-slop-fmt is operational. john-slop-lsp remains an explicit Milestone 6 scaffold and returns an unsupported diagnostic when started without --help.

Install all three binaries somewhere on PATH, then confirm the editor-facing help is available:

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:

[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:

[[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.

Vim

Vim's native formatprg option is enough for formatting. Add this to ~/.vimrc:

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.

Classic Vim needs an LSP client plugin. With prabirshrestha/vim-lsp, register John Slop in ~/.vimrc:

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

The plugin's :LspStatus, :LspNextDiagnostic, and :LspCodeAction commands will expose server state, diagnostics, and replacement quick fixes once Milestone 6 lands. The registration shape and allowlist follow the plugin's current upstream documentation.

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:

cargo run --bin john-slop -- --output concise \
  examples/fixtures/typography/example.txt
cargo run --bin john-slop-fmt -- \
  examples/fixtures/typography/example.txt