fmaury/seirdy.one
1
0
Fork 0
mirror of https://git.sr.ht/~seirdy/seirdy.one synced 2024-11-23 12:52:10 +00:00
Code Issues Projects Releases Wiki Activity

Mention vim, whatis, and apropos manpage integration

Browse source
This commit is contained in:
Rohan Kumar 2022-06-13 08:34:42 -07:00
parent 6e3273e602
commit 69e5d38b2c
No known key found for this signature in database
GPG key ID: 1E892DB2A5F84479
2 changed files with 13 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
content/posts/cli-best-practices.gmi
View file

@ -88,6 +88,8 @@ Avoiding reliance on color and using whitespace and/or indentation for pseudo-he
3. Related to no. 2: use a well-understood format for "-h" and "--help" output. This makes auto-generating shell completions much easier. Alternatively, delegate the generation of both to a library that follows this advice.
4. Ensure that the "whatis" and "apropos" commands work as intended after installing your man pages. These commands parse the beginnings of man pages to give one-line summaries of programs, and often power advanced tab-completion setups.
Code snippet 2 (console): This is what tab-completion for MOAC looks like with fzf-tab.
```
$ moac -
@ -123,7 +125,7 @@ These considerations are far more subjective, debatable, and deserving of skepti
=> https://git.sr.ht/~seirdy/moac/tree/master/item/cmd/moac/testdata/scripts moac testdata
=> https://git.sr.ht/~seirdy/moac/tree/master/item/cmd/moac-pwgen/testdata/scripts moac-pwgen testdata
4. Make your man pages as similar to other man pages on the target OS as possible. Many programs parse man pages, and expect them to follow a predictable structure. Try testing your man pages in multiple programs, just as people test Web pages in multiple browser engines. w3mman (included in w3m) is a good example to make sure auto-hyperlinking works. Pandoc is another tool worth trying.
4. Make your man pages as similar to other man pages on the target OS as possible. Many programs parse man pages, and expect them to follow a predictable structure. Try testing your man pages in multiple programs, just as people test Web pages in multiple browser engines. w3mman (included in w3m) is a good example to make sure auto-hyperlinking works. Vim uses its own man page parser to look up the currently-selected word (put your caret over a word and type "Shift + K"). Pandoc is another tool worth testing; it can convert man pages to a variety of different formats.
=> https://manpages.debian.org/unstable/w3m/w3mman.1.en.html w3mman man page
=> https://pandoc.org/ Pandoc

12
content/posts/cli-best-practices.md
View file

@ -99,7 +99,9 @@ This is a non-exhaustive list of simple, baseline recommendations for designing
2. Try adding shell completions for your program, so users can tab-complete options. This is particularly helpful in shells like Zsh that support help-text in tab completions, especially when combined with plugins like [fzf-tab](https://github.com/Aloxaf/fzf-tab) that enable fuzzy-searching help-text (see [code snippet 2](#code-2)).
3. Related to no. 5: use a well-understood format for `-h` and `--help` output. This makes auto-generating shell completions much easier. Alternatively, delegate the generation of both to a library that follows this advice.
3. Related to no. 2: use a well-understood format for `-h` and `--help` output. This makes auto-generating shell completions much easier. Alternatively, delegate the generation of both to a library that follows this advice.
4. Ensure that the `whatis` and `apropos` commands work as intended after installing your man pages. These commands parse the beginnings of man pages to give one-line summaries of programs, and often power advanced tab-completion setups.
{{<codefigure samp="true">}} {{< codecaption lang="console" >}} This is what tab-completion for [MOAC](https://sr.ht/~seirdy/moac) looks like with fzf-tab. {{< /codecaption >}}
@ -136,7 +138,13 @@ These considerations are far more subjective, debatable, and deserving of skepti
3. Include an extended list of example command invocations and expected output. Make that document double as a test suite. My [`moac` testdata](https://git.sr.ht/~seirdy/moac/tree/master/item/cmd/moac/testdata/scripts) and [`moac-pwgen` testdata](https://git.sr.ht/~seirdy/moac/tree/master/item/cmd/moac-pwgen/testdata/scripts) scripts are good examples. This can serve as a check for API stability, and even as a source of documentation.
4. Make your man pages as similar to other man pages on the target OS as possible. Many programs parse man pages, and expect them to follow a predictable structure. Try testing your man pages in multiple programs, just as people test Web pages in multiple browser engines. [`w3mman`](https://manpages.debian.org/unstable/w3m/w3mman.1.en.html) (included in [w3m](https://github.com/tats/w3m)) is a good example to make sure auto-hyperlinking works. [Pandoc](https://pandoc.org/) is another tool worth trying.
4. Make your man pages as similar to other man pages on the target OS as possible. Many programs parse man pages, and expect them to follow a predictable structure. Try testing your man pages in multiple programs, just as people test Web pages in multiple browser engines. Some examples:
- [`w3mman`](https://manpages.debian.org/unstable/w3m/w3mman.1.en.html) (included in [w3m](https://github.com/tats/w3m)) is a good example to make sure auto-hyperlinking works.
- Editors like Vim support looking up man pages for the currently-selected word. Try pressing <kbd>Shift</kbd>+<kbd>k</kbd> while your caret is on a command name.
- [Pandoc](https://pandoc.org/) is another tool worth testing; it can convert man pages to a variety of different formats.
5. Conform to tools that share a similar niche. If you're using Rust to make a fast alternative to popular coreutils: model its behavior, help-text, and man pages after `ripgrep` and `fd`. If you're making a linter for Go: copy `go vet`.