diff --git a/.gitignore b/.gitignore index 5318855..cddec05 100644 --- a/.gitignore +++ b/.gitignore @@ -5,5 +5,6 @@ __pycache__/ Session.vim autoload/ plugged/ +doc/tags .swap/ .undo/ diff --git a/.vimrc b/.vimrc index 806a41a..e454039 100644 --- a/.vimrc +++ b/.vimrc @@ -1,6 +1,9 @@ set nocompatible let g:chopsticks_dir = fnamemodify(resolve(expand('')), ':h') +if index(split(&runtimepath, ','), g:chopsticks_dir) < 0 + let &runtimepath = g:chopsticks_dir . ',' . &runtimepath +endif let s:xdg_config_home = !empty($XDG_CONFIG_HOME) && $XDG_CONFIG_HOME =~# '^/' \ ? $XDG_CONFIG_HOME \ : '~/.config' @@ -38,4 +41,5 @@ call s:load('status') call s:load('cheatsheet') call s:load('tutor') call s:load('beta') +call s:load('help') call s:load('tools') diff --git a/BETA.md b/BETA.md index 052a15e..f2dbcca 100644 --- a/BETA.md +++ b/BETA.md @@ -5,7 +5,8 @@ until the checklist below is closed. Inside Vim, run `:ChopsticksBeta` for the compact checklist, `:ChopsticksBetaLog` for editable local notes, and `:ChopsticksBetaSession` -to append a new session block. +to append a new session block. Run `:ChopsticksHelp` or `:help chopsticks` +for the native Vim reference. ## Install the beta @@ -67,7 +68,8 @@ file, edit Markdown, and use a machine with missing optional tools. - `s` as the default visible jump still feels worth the native override after real editing. - No high-frequency action requires remembering an undocumented key. -- README, QUICKSTART, `SPC ?`, and `:ChopsticksTutor` teach the same layout. +- README, QUICKSTART, `:help chopsticks`, `SPC ?`, and `:ChopsticksTutor` + teach the same layout. - `scripts/test.sh quick` and `scripts/test.sh vim` pass locally. - The README GIF has been regenerated from `.github/demo.tape` after any public key change. diff --git a/CHANGELOG.md b/CHANGELOG.md index fd9f9ec..1f0df00 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,8 +23,12 @@ `[d`, and `]d` - `:ChopsticksTutor` guided practice buffer for learning the final keymap - `:ChopsticksCheatSheet` command, with `SPC ?` as the discoverable default +- `:ChopsticksHelp` and native `:help chopsticks` documentation for in-editor + support without a separate wiki +- `:ChopsticksBeta`, `:ChopsticksBetaLog`, and `:ChopsticksBetaSession` for + guided beta testing and local session notes - Dedicated modules for buffers, utilities, files, runner, quickfix, status, - cheat sheet, and tutor + cheat sheet, tutor, beta testing, and help - Split test runner: `scripts/test.sh` now dispatches to `scripts/test-quick.sh` and `scripts/test-vim.sh` diff --git a/QUICKSTART.md b/QUICKSTART.md index b09684b..d4efcba 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -51,6 +51,7 @@ SPC w save SPC qx save + quit :q! force quit SPC ? cheat sheet (toggle sidebar) +:ChopsticksHelp full native help ``` Classic layout equivalents: @@ -61,6 +62,7 @@ Esc back to Normal ,x save + quit :q! force quit ,? cheat sheet (toggle sidebar) +:ChopsticksHelp full native help ``` ## Find things @@ -137,6 +139,7 @@ syntax. Enable the heavier Markdown tools only when you want them. ## Health check ``` +:ChopsticksHelp full native Vim help :ChopsticksTutor guided practice for the final keymap :ChopsticksStatus see what's installed and what's missing ``` @@ -144,5 +147,6 @@ syntax. Enable the heavier Markdown tools only when you want them. The `SPC ?` cheat sheet follows your active profile, so `minimal` users only see keys for features that are actually loaded. -See [README](README.md) for the full reference. For beta testing and rollback, -see [BETA.md](BETA.md). +Inside Vim, `:help chopsticks` opens the same reference after helptags are +available. See [README](README.md) for the full reference. For beta testing and +rollback, see [BETA.md](BETA.md). diff --git a/README.md b/README.md index 148d032..2d86a16 100644 --- a/README.md +++ b/README.md @@ -48,9 +48,9 @@ That assembly work is the pain chopsticks removes: `gd`, `gr`, `K`, `hjkl`, `cl`, `cc`. - **Remote editing is fragile.** It is built to degrade on TTY, slow SSH, and headless machines instead of assuming a GUI desktop. -- **Custom configs are hard to onboard.** `SPC ?`, `:ChopsticksTutor`, and - `:ChopsticksStatus` make the active keymap and missing tools visible inside - Vim. +- **Custom configs are hard to onboard.** `:ChopsticksHelp`, `SPC ?`, + `:ChopsticksTutor`, and `:ChopsticksStatus` make the active keymap, full + help, and missing tools visible inside Vim. You SSH into a server. You need to edit code. You want LSP, fuzzy find, git integration, format-on-save — not a 20-minute setup. @@ -142,8 +142,9 @@ Git push/pull are intentionally not bound to default hotkeys. Normal-mode `s` is a screen-local EasyMotion jump; use `cl` for native `s` substitute and `cc` for native `S`. -For onboarding, use `:ChopsticksTutor` for a guided practice page, `SPC ?` for -the active keymap, and `:ChopsticksStatus` for tool/LSP health. +For onboarding, use `:ChopsticksHelp` / `:help chopsticks` for full native Vim +help, `:ChopsticksTutor` for a guided practice page, `SPC ?` for the active +keymap, and `:ChopsticksStatus` for tool/LSP health. `QUICKSTART.md` is the 5-minute path; this README is the full reference. During the beta, `:ChopsticksBeta` opens the in-editor test checklist, `:ChopsticksBetaLog` opens editable local notes, and `:ChopsticksBetaSession` @@ -199,7 +200,7 @@ Esc exit insert mode SPC ? cheat sheet ### Survival -`SPC w` save | `SPC W` save all | `SPC qq` quit | `SPC qx` save and quit | `SPC ?` cheat sheet | `:ChopsticksTutor` practice | `:ChopsticksStatus` diagnostics +`SPC w` save | `SPC W` save all | `SPC qq` quit | `SPC qx` save and quit | `SPC ?` cheat sheet | `:ChopsticksHelp` full help | `:ChopsticksTutor` practice | `:ChopsticksStatus` diagnostics @@ -283,27 +284,30 @@ For Markdown LSP, install or select `marksman` first. ``` ~/.vim/ ├── .vimrc thin loader -├── modules/ -│ ├── env.vim TTY detection, truecolor, skip built-in plugins -│ ├── plugins.vim vim-plug + 23–25 plugins -│ ├── core.vim settings, keymaps, performance -│ ├── ui.vim solarized, statusline, startify -│ ├── editing.vim easymotion, yank highlight, blank lines -│ ├── navigation.vim fzf, netrw sidebar, windows, terminal -│ ├── lsp.vim vim-lsp, asyncomplete -│ ├── lint.vim ale, format-on-save -│ ├── git.vim fugitive, gitgutter, conflict nav -│ ├── languages.vim vim-go, markdown, filetype settings -│ ├── buffers.vim buffer commands -│ ├── utilities.vim reindent, trim, clipboard, vimrc helpers -│ ├── files.vim auto mkdir, large-file protection -│ ├── runner.vim run current file -│ ├── quickfix.vim quickfix and location-list helpers -│ ├── status.vim :ChopsticksStatus diagnostics -│ ├── cheatsheet.vim SPC ? and :ChopsticksCheatSheet -│ ├── tutor.vim :ChopsticksTutor guided practice -│ ├── beta.vim :ChopsticksBeta test guide -│ └── tools.vim compatibility placeholder +├── doc/ +│ └── chopsticks.txt :help chopsticks +└── modules/ + ├── env.vim TTY detection, truecolor, skip built-in plugins + ├── plugins.vim vim-plug + 23–25 plugins + ├── core.vim settings, keymaps, performance + ├── ui.vim solarized, statusline, startify + ├── editing.vim easymotion, yank highlight, blank lines + ├── navigation.vim fzf, netrw sidebar, windows, terminal + ├── lsp.vim vim-lsp, asyncomplete + ├── lint.vim ale, format-on-save + ├── git.vim fugitive, gitgutter, conflict nav + ├── languages.vim vim-go, markdown, filetype settings + ├── buffers.vim buffer commands + ├── utilities.vim reindent, trim, clipboard, vimrc helpers + ├── files.vim auto mkdir, large-file protection + ├── runner.vim run current file + ├── quickfix.vim quickfix and location-list helpers + ├── status.vim :ChopsticksStatus diagnostics + ├── cheatsheet.vim SPC ? and :ChopsticksCheatSheet + ├── tutor.vim :ChopsticksTutor guided practice + ├── beta.vim :ChopsticksBeta test guide + ├── help.vim :ChopsticksHelp native Vim help + └── tools.vim compatibility placeholder ``` Each module is self-contained. Comment out one line in `.vimrc` to disable it. Add your own with `call s:load('mine')`. @@ -329,7 +333,7 @@ Each module is self-contained. Comment out one line in `.vimrc` to disable it. A | What's installed? | `:ChopsticksStatus` shows tools, LSP, linters | For deeper checks, start with `:ChopsticksStatus`, `SPC ?`, -`:ChopsticksTutor`, and [QUICKSTART.md](QUICKSTART.md). +`:ChopsticksTutor`, `:ChopsticksHelp`, and [QUICKSTART.md](QUICKSTART.md). ## Contributing diff --git a/doc/chopsticks.txt b/doc/chopsticks.txt new file mode 100644 index 0000000..794f87d --- /dev/null +++ b/doc/chopsticks.txt @@ -0,0 +1,162 @@ +*chopsticks.txt* *chopsticks* A project-work Vim setup + +============================================================================== +CONTENTS *chopsticks-contents* + + 1. What chopsticks solves...............|chopsticks-why| + 2. First five minutes...................|chopsticks-start| + 3. Canonical Space layout...............|chopsticks-v3-space| + 4. Commands.............................|chopsticks-commands| + 5. Profiles and local config............|chopsticks-profiles| + 6. Beta testing.........................|chopsticks-beta| + 7. Troubleshooting......................|chopsticks-troubleshooting| + +============================================================================== +WHAT CHOPSTICKS SOLVES *chopsticks-why* + +Chopsticks is a complete Vim project loop for people who edit locally and over +SSH. It connects fuzzy find, project grep, git, LSP, linting, formatting, +runners, quickfix navigation, and self-documenting keys. + +It is meant to supplement stock Vim, not replace Vim muscle memory. Native +motions and well-known conventions stay where they are useful: gd, gr, K, +hjkl, cl, cc, quickfix, and normal Vim commands. + +============================================================================== +FIRST FIVE MINUTES *chopsticks-start* + +Inside Vim: +> + :ChopsticksTutor guided practice page + SPC ? active keymap cheat sheet + :ChopsticksStatus tool, plugin, and LSP diagnostics + :ChopsticksHelp this help page +< + +Daily loop: +> + SPC SPC find file SPC / grep project + s + 2ch jump on screen gd / gr definition / references + K hover docs SPC rr run current file + SPC gs git status SPC cf format + SPC w save SPC qq quit +< + +============================================================================== +CANONICAL SPACE LAYOUT *chopsticks-v3-space* + +Default layout: Space leader, comma localleader. + +This layout assumes a QWERTY keyboard and CapsLock mapped at the system layer +to tap-Esc / hold-Ctrl. Vim keeps hjkl for windows and standard LSP +motions for code. + +Normal-mode s is a visible EasyMotion jump. This is intentionally different +from stock Vim because screen-local jumping is higher value in project editing. +Use cl for native s substitute and cc for native S substitute. + +High-frequency keys: +> + SPC SPC files SPC , buffers + SPC / grep project SPC Tab alternate file + SPC e/E file sidebar SPC rr run file + SPC gs git status SPC gl git log graph + SPC ca code action SPC cr rename + SPC cf format SPC ? cheat sheet +< + +Classic comma mappings remain available: +> + let g:chopsticks_keymap_style = 'classic' +< + +============================================================================== +COMMANDS *chopsticks-commands* + +User-facing commands: +> + :ChopsticksHelp open this help + :ChopsticksTutor guided practice + :ChopsticksCheatSheet active keymap reference + :ChopsticksStatus health diagnostics + :ChopsticksBeta beta checklist + :ChopsticksBetaLog editable beta notes + :ChopsticksBetaSession append a timestamped beta note block +< + +LSP commands come from vim-lsp: +> + :LspInstallServer install a server for the current filetype + :LspStatus inspect attached servers +< + +============================================================================== +PROFILES AND LOCAL CONFIG *chopsticks-profiles* + +Keep personal choices outside the managed .vimrc: +> + " ${XDG_CONFIG_HOME:-~/.config}/chopsticks.vim + let g:chopsticks_profile = 'engineer' + let g:chopsticks_keymap_style = 'space' +< + +Profiles: + + minimal Core navigation, editing, git, Markdown. No LSP/ALE/completion. + engineer Default. LSP, ALE, completion, syntax extras. + full Engineer plus heavier Markdown feedback. + +Optional habits: +> + let g:chopsticks_enable_jk_escape = 1 + let g:chopsticks_enable_ctrl_s_save = 1 + let g:chopsticks_enable_auto_pairs = 1 + let g:chopsticks_enable_terminal_keymaps = 1 +< + +============================================================================== +BETA TESTING *chopsticks-beta* + +For the v3 beta candidate, record real editing friction instead of abstract +opinions: +> + :ChopsticksBeta compact beta checklist + :ChopsticksBetaLog open editable local notes + :ChopsticksBetaSession append a new session block +< + +Default beta log: +> + ${XDG_CONFIG_HOME:-~/.config}/chopsticks-beta.md +< + +Exit criteria before a stable release: + + - s as jump still feels worth the native override. + - No high-frequency action needs an undocumented key. + - README, QUICKSTART, :help chopsticks, SPC ?, and :ChopsticksTutor agree. + - quick and Vim smoke tests pass locally and over SSH. + - The README GIF matches the public keymap. + +============================================================================== +TROUBLESHOOTING *chopsticks-troubleshooting* + +Start with: +> + :ChopsticksStatus + SPC ? + :ChopsticksTutor + :ChopsticksHelp +< + +Common fixes: + + Plugins missing :PlugInstall + LSP missing Open that filetype, then :LspInstallServer + Need active keys SPC ? + Need full docs :help chopsticks + Need beta notes :ChopsticksBetaSession + Slow large file Syntax, undo, swap, and ALE are auto-reduced + +============================================================================== + vim:tw=78:ts=8:ft=help:norl: diff --git a/install.sh b/install.sh index 8cfd327..5772816 100755 --- a/install.sh +++ b/install.sh @@ -719,6 +719,21 @@ if [[ $_plug_count -eq 0 ]]; then fi ok "Plugins installed ($_plug_count)" +step "Installing Vim help" +if [[ -d "$SCRIPT_DIR/doc" ]]; then + # shellcheck disable=SC2016 # $CHOPSTICKS_HELP_DIR is expanded by Vim. + if CHOPSTICKS_HELP_DIR="$SCRIPT_DIR/doc" \ + "$VIM_BIN" -Nu NONE -i NONE -n -es -N \ + -c 'execute "silent! helptags " . fnameescape($CHOPSTICKS_HELP_DIR)' \ + -c 'qa!' >/dev/null 2>&1; then + ok ":help chopsticks" + else + warn "Could not generate Vim help tags. Inside Vim, run: :ChopsticksHelp" + fi +else + skip "Vim help docs not found" +fi + # ============================================================================ # 4. Module Selection # ============================================================================ diff --git a/modules/cheatsheet.vim b/modules/cheatsheet.vim index b341fe0..05f9884 100644 --- a/modules/cheatsheet.vim +++ b/modules/cheatsheet.vim @@ -147,6 +147,7 @@ function! s:CheatSheet() abort \ ' Esc exit insert', \ ' SPC fv edit vimrc', \ ' SPC fV reload vimrc', + \ ' :ChopsticksHelp full help', \ ' :ChopsticksTutor practice', \ ' :ChopsticksStatus health', \ ' :ChopsticksBeta beta test guide', @@ -260,6 +261,7 @@ function! s:CheatSheet() abort \ ' Esc exit insert', \ ' ,ev edit vimrc', \ ' ,sv reload vimrc', + \ ' :ChopsticksHelp full help', \ ' :ChopsticksTutor practice', \ ' :ChopsticksStatus health', \ ' :ChopsticksBeta beta test guide', diff --git a/modules/help.vim b/modules/help.vim new file mode 100644 index 0000000..80898ba --- /dev/null +++ b/modules/help.vim @@ -0,0 +1,18 @@ +" help.vim — native Vim help entrypoint + +function! s:OpenHelp() abort + let l:doc = g:chopsticks_dir . '/doc' + if isdirectory(l:doc) + silent! execute 'helptags ' . fnameescape(l:doc) + endif + + try + help chopsticks + catch /^Vim\%((\a\+)\)\=:E149/ + echohl WarningMsg + echom 'chopsticks help tags are missing; run :helptags ' . l:doc + echohl None + endtry +endfunction + +command! ChopsticksHelp call s:OpenHelp() diff --git a/modules/status.vim b/modules/status.vim index 5c934f9..8e1d2c5 100644 --- a/modules/status.vim +++ b/modules/status.vim @@ -85,6 +85,8 @@ function! s:ChopsticksStatus() abort call add(l:lines, 'chopsticks status') call add(l:lines, repeat('─', 50)) call add(l:lines, '') + call add(l:lines, ' help :ChopsticksHelp :ChopsticksTutor SPC ?') + call add(l:lines, '') if !empty(get(g:, 'chopsticks_beta_label', '')) call add(l:lines, '── beta ──') diff --git a/modules/tutor.vim b/modules/tutor.vim index 8ece162..67e86e2 100644 --- a/modules/tutor.vim +++ b/modules/tutor.vim @@ -28,6 +28,7 @@ function! s:ChopsticksTutor() abort \ ' SPC ? active cheat sheet', \ ' SPC w save', \ ' SPC qx save and quit', + \ ' :ChopsticksHelp full help', \ ' :ChopsticksStatus health check', \ ' :ChopsticksBeta beta checklist', \ ' :ChopsticksBetaLog beta notes', @@ -92,6 +93,7 @@ function! s:ChopsticksTutor() abort \ ' hjkl split navigation', \ '', \ ' support', + \ ' :ChopsticksHelp full help', \ ' :ChopsticksStatus health check', \ ' :ChopsticksBeta beta checklist', \ ' :ChopsticksBetaLog beta notes', diff --git a/scripts/test-quick.sh b/scripts/test-quick.sh index 68457f9..8a2cdd5 100755 --- a/scripts/test-quick.sh +++ b/scripts/test-quick.sh @@ -29,8 +29,10 @@ check_docs() { markdownlint README.md QUICKSTART.md CONTRIBUTING.md CHANGELOG.md BETA.md step "Documentation consistency" - for command in ChopsticksBeta ChopsticksBetaLog ChopsticksBetaSession; do - for file in README.md BETA.md modules/beta.vim modules/cheatsheet.vim \ + for command in ChopsticksHelp ChopsticksBeta ChopsticksBetaLog \ + ChopsticksBetaSession + do + for file in README.md BETA.md doc/chopsticks.txt modules/cheatsheet.vim \ modules/tutor.vim modules/status.vim do grep -Fq "$command" "$file" || { @@ -39,6 +41,15 @@ check_docs() { } done done + grep -Fq '*chopsticks.txt*' doc/chopsticks.txt + grep -Fq '*chopsticks-v3-space*' doc/chopsticks.txt + grep -Fq 'command! ChopsticksHelp' modules/help.vim + for command in ChopsticksBeta ChopsticksBetaLog ChopsticksBetaSession; do + grep -Fq "command! $command" modules/beta.vim || { + echo "Missing $command definition in modules/beta.vim" >&2 + exit 1 + } + done if command -v vhs >/dev/null 2>&1; then vhs validate .github/demo.tape diff --git a/scripts/test-vim.sh b/scripts/test-vim.sh index 467f899..d383e34 100755 --- a/scripts/test-vim.sh +++ b/scripts/test-vim.sh @@ -42,11 +42,20 @@ check_vim() { fi mkdir -p "$TMP_ROOT/chopsticks path/modules" + mkdir -p "$TMP_ROOT/chopsticks path/doc" cp .vimrc "$TMP_ROOT/chopsticks path/.vimrc" cp modules/*.vim "$TMP_ROOT/chopsticks path/modules/" + cp doc/*.txt "$TMP_ROOT/chopsticks path/doc/" XDG_CONFIG_HOME="$EMPTY_XDG" vim -u "$TMP_ROOT/chopsticks path/.vimrc" \ -i NONE -es -N -c 'qa!' 2>&1 + XDG_CONFIG_HOME="$EMPTY_XDG" \ + vim -u "$TMP_ROOT/chopsticks path/.vimrc" -i NONE -es -N \ + -c 'ChopsticksHelp' \ + -c 'if expand("%:t") !=# "chopsticks.txt" | cquit | endif' \ + -c 'if search("chopsticks-v3-space", "n") == 0 | cquit | endif' \ + -c 'qa!' 2>&1 + XDG_CONFIG_HOME="$EMPTY_XDG" vim -u NONE -i NONE -es -N \ -c 'let g:chopsticks_profile = "minimal"' \ -c 'source .vimrc' \ @@ -79,6 +88,7 @@ check_vim() { exit 1 fi grep -Fq 'OK vim-lsp stack (installed)' "$TMP_ROOT/status-default.txt" + grep -Fq 'help :ChopsticksHelp :ChopsticksTutor SPC ?' "$TMP_ROOT/status-default.txt" grep -Fq 'candidate 3.0.0-beta.1' "$TMP_ROOT/status-default.txt" grep -Fq 'keymap space' "$TMP_ROOT/status-default.txt" grep -Fq 'commands :ChopsticksBeta :ChopsticksBetaLog' "$TMP_ROOT/status-default.txt" @@ -258,6 +268,7 @@ check_vim() { grep -Fq 'SPC w save' "$TMP_ROOT/cheat-default.txt" grep -Fq 's+2ch easymotion jump' "$TMP_ROOT/cheat-default.txt" grep -Fq 'cl / cc native s / S substitute' "$TMP_ROOT/cheat-default.txt" + grep -Fq ':ChopsticksHelp full help' "$TMP_ROOT/cheat-default.txt" grep -Fq ':ChopsticksTutor practice' "$TMP_ROOT/cheat-default.txt" grep -Fq ':ChopsticksBeta beta test guide' "$TMP_ROOT/cheat-default.txt" grep -Fq ':ChopsticksBetaLog beta notes' "$TMP_ROOT/cheat-default.txt" @@ -332,6 +343,7 @@ check_vim() { -c 'qa!' 2>&1 grep -Fq 'chopsticks tutor' "$TMP_ROOT/tutor-default.txt" grep -Fq 'SPC ? active cheat sheet' "$TMP_ROOT/tutor-default.txt" + grep -Fq ':ChopsticksHelp full help' "$TMP_ROOT/tutor-default.txt" grep -Fq 's + 2 chars visible jump' "$TMP_ROOT/tutor-default.txt" grep -Fq 'cl / cc native s / S substitute' "$TMP_ROOT/tutor-default.txt" grep -Fq 'gd / gr / K definition / refs / docs' "$TMP_ROOT/tutor-default.txt"