;doc:shell completions: mention zsh; cleanups

simonmichael · Feb 22, 2025 · d4884de · d4884de
1 parent afd6540
commit d4884de
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 28 deletions.
diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md
@@ -640,9 +640,8 @@ The config file feature was added in hledger 1.40 and is considered *experimenta
 
 ## Shell completions
 
-If you use the bash shell, you can optionally set up context-sensitive autocompletions when you press TAB in a hledger command line.
-At a bash shell prompt, try pressing
-`hledger<SPACE><TAB><TAB>` (should list all hledger commands)
+If you use the bash or zsh shells, you can optionally set up context-sensitive autocompletion for hledger command lines.
+Try pressing `hledger<SPACE><TAB><TAB>` (should list all hledger commands)
 or `hledger reg acct:<TAB><TAB>` (should list your top-level account names).
 If completions aren't working, or for more details, see [Install > Shell completions](install.html#shell-completions).
 

diff --git a/hledger/shell-completion/README.md b/hledger/shell-completion/README.md
@@ -2,8 +2,13 @@
 
 This code generates shell completion scripts for hledger's command line interface.
 Context-sensitive completions are usually triggered by pressing the tab key once or twice after typing the command `hledger ` (or `hledger-ui` or `hledger-web`).
-Currently only Bash is supported, but Zsh or Fish could be added.
 
+Currently there are detailed bash completions here in the hledger repo, which this doc is mostly about;
+and there are some zsh completions maintained in zsh-completions repo.
+
+## bash completions
+
+An old demo:
 [![asciicast](https://asciinema.org/a/227935.svg)](https://asciinema.org/a/227935)
 
 To use hledger's bash shell completions, these must be installed on your system:
@@ -12,24 +17,9 @@ To use hledger's bash shell completions, these must be installed on your system:
 - hledger's bash completion script
 - hledger, hledger-ui, and/or hledger-web
 
-For user setup and usage instructions, please see [Install > Shell completions](https://hledger.org/install.html#shell-completions).
-
-To test the bash completions, at a bash shell prompt, type
-`hledger<SPACE><TAB><TAB>` (should list all hledger commands)
-or `hledger reg acct:<TAB><TAB>` (should list your top-level account names).
-
-The bash completion script can handle:
-
-- hledger's command argument
-- general flags
-- command-specific flags, after the command argument
-- flag values, for flags that have standard values
-- query prefixes
-- account names from the journal, after an account name prefix
-- appropriate data from the journal, after these query prefixes: `acct:`, `code:`, `cur:`, `desc:`, `note:`, `payee:`, `real:`, `status:`, `tag:`
-- amount comparison operators, after `amt:`.
+For latest user setup instructions and feature list, please see [Install > Shell completions](https://hledger.org/install.html#shell-completions).
 
-## Generating hledger shell completions
+### Generating the bash completions
 
 In the main hledger repo,
 first build and install an up-to-date version of hledger in PATH,
@@ -49,7 +39,7 @@ You can add `-jNUMPROCS` to make it run faster.
 Data from the journal (account names, payee names etc.) is not gathered here;
 the script detects those dynamically at completion time.
 
-## Installing the generated shell completions
+### Installing the bash completions
 
 (If you want a released version of the completion script, use the Install page link above instead.)
 
@@ -64,19 +54,20 @@ bash will use it when completing command lines beginning with "hledger" or "hled
 You can also just source the script it in your shell startup; this will load completions eagerly, adding a delay to your shell start up time.
 Or you can source it in your current bash session for testing.
 
-## Packaging hledger shell completions
+### Packaging the bash completions
 
 It's great when hledger packagers can make shell completions just work for users.
 
 Currently there is one completion script: `hledger-completion.bash`.
 It is included in the hledger package's tarball on Hackage.
 
-For hledger version 1.40, the up-to-date script is at 
+hledger versions before 1.40 don't have up-to-date bash completions.
+
+For hledger 1.40, the up-to-date script is at 
 https://github.com/simonmichael/hledger/blob/39dfe5702e1b401f1883d814907d242958eec9c1/hledger/shell-completion/hledger-completion.bash.
 
-From releases after 1.40, it will be included in the bindists provided in Github releases,
-and available at urls like 
-https://github.com/simonmichael/hledger/blob/1.40/hledger/shell-completion/hledger-completion.bash
+Since hledger 1.41, this is included in the Github release bindists, and available at urls like 
+https://github.com/simonmichael/hledger/blob/1.41/hledger/shell-completion/hledger-completion.bash
 
 After it has been loaded, this script will provide completions for hledger, hledger-ui and hledger-web.
 Note if it is installed only as `hledger`, bash-completion will not load it until the user types `hledger<SPACE><TAB>`.
@@ -88,7 +79,12 @@ Here is a place to track the status of shell completions in hledger packages. As
 - Arch Linux AUR: packaging in progress
 - Others: unknown
 
-## Completion scripts for other shells
+## zsh completions
+
+There are some [zsh completions](https://github.com/zsh-users/zsh-completions/blob/master/src/_hledger) in the zsh-completions repo.
+
+
+## Completions for other shells
 
 You're welcome to add completion scripts for other shells. It should not be too
 hard! All available hledger options and commands are already there (generated by