fish-shell
completions: fix long descriptions
Issue
There are quite a few completions that have very long descriptions, most likely auto-generated ones from the manpage haven't been fixed up by anyone. I think we should list these up so people can work on it in chunks since it's a mundane task...
I ran a simple script to check for all descriptions >80 characters (arbitrary number):
for f in share/completions/*.fish
set desc_str (string replace -rf "^complete.*-d\s?[\"|']([^-]*)[\"|']\s?.*" '$1' <$f)
set n 0
for d in $desc_str
if test (echo $d | wc -c) -gt 80
if test $n -lt 1
echo $f
set n 1
end
echo (echo $d | wc -c) chars: $d
end
end
if test $n -gt 0
echo --------------------------
end
end
Script output is here: https://gist.github.com/ammgws/a0f49d719a5145675c76ff161627c111
Progress
- [x] adduser.fish (#7550)
- [x] animate.fish
- [x] ansible-playbook.fish
- [x] ansible.fish (9ffaade0db3392801a41c649486e21574151bb53)
- [x] ant.fish
- [x] atom.fish (848f3ac9)
- [x] awk.fish (#7125)
- [x] badblocks.fish (#7788)
- [x] bison.fish (https://github.com/fish-shell/fish-shell/pull/8658/commits/8b423206aafb6815caddda9f0ae946b94288edc1)
- [x] btrfs.fish (f88d7dd31249e7fc338a037425654d72923eea4d)
- [x] bundle.fish (#8034)
- [ ] bzr.fish
- [ ] cdrecord.fish
- [ ] cf.fish
- [ ] compare.fish
- [ ] composer.fish
- [ ] composite.fish
- [ ] convert.fish
- [ ] csc.fish
- [x] curl.fish (#7788)
- [ ] cwebp.fish
- [ ] darcs.fish
- [x] dhclient.fish (#8034)
- [ ] display.fish
- [ ] entr.fish
- [ ] exercism.fish
- [x] feh.fish (#7109)
- [x] find.fish (c065d24632e12c9988bd6629be9b6a02c6d1fdc6)
- [x] fsharpc.fish (#7569)
- [x] fsharpi.fish (#7569)
- [x] fzf.fish (#7081)
- [ ] gcc.fish
- [ ] gdb.fish
- [x] git.fish (#7752)
- [x] gitk.fish (#7752)
- [x] go.fish (#7291)
- [ ] heroku.fish
- [ ] iex.fish
- [x] jest.fish (#7752)
- [ ] jhipster.fish
- [ ] kitchen.fish
- [ ] latexmk.fish
- [ ] lpadmin.fish
- [ ] lpstat.fish
- [x] lsof.fish (#7752)
- [x] lsusb.fish (#7752)
- [x] minikube.fish (#7752)
- [ ] mix.fish
- [x] mocha.fish (#7550)
- [ ] mocp.fish
- [ ] mogrify.fish
- [ ] montage.fish
- [ ] mvn.fish
- [ ] node.fish
- [ ] oggenc.fish
- [ ] opam.fish
- [x] p4.fish (#8647)
- [ ] pg_dump.fish
- [ ] pg_dumpall.fish
- [ ] pg_restore.fish
- [ ] phpunit.fish
- [x] ping.fish (23f9373)
- [ ] pkgfile.fish
- [x] pydf.fish
- [x] python3.fish (https://github.com/fish-shell/fish-shell/commit/fb57a98aefcf7e181752c29507d0b8ffafe0ebd9)
- [ ] qubes-gpg-client.fish
- [ ] quilt.fish
- [x] read.fish (#7788)
- [ ] rmmod.fish
- [x] rpm.fish (#7891)
- [ ] rsync.fish
- [ ] sass-convert.fish
- [ ] sass.fish
- [ ] scons.fish
- [ ] scss.fish
- [ ] sfdx.fish
- [ ] stack.fish
- [x] sudo.fish (#7163)
- [ ] svn.fish
- [ ] sysbench.fish
- [ ] tcpdump.fish
- [ ] tmutil.fish
- [x] tmux.fish (#7569, #8034)
- [ ] tsc.fish
- [ ] tshark.fish
- [x] umount.fish (#7378)
- [x] useradd.fish (#7788)
- [x] valgrind.fish (#7550)
- [x] vbc.fish
- [x] wesnoth.fish (#7569)
- [x] wget.fish (#7550)
- [x] xargs.fish (c065d24632e12c9988bd6629be9b6a02c6d1fdc6)
- [x] xbps-*.fish (c065d24632e12c9988bd6629be9b6a02c6d1fdc6)
- [x] xgettext.fish (c065d24632e12c9988bd6629be9b6a02c6d1fdc6)
- [x] yarn.fish (c065d24632e12c9988bd6629be9b6a02c6d1fdc6)
- [x] zypper.fish (c065d24632e12c9988bd6629be9b6a02c6d1fdc6)
I don't like hard limits for things like these.
It's probably better to have a description that is 60 characters long if that's necessary to explain it, than to neuter that description. In turn some descriptions don't even have to be 20 characters long.
(similar things apply to hard line length limits that linters like so much)
I would aim for 60 as a soft limit. After that, the longer it is the harder it is to justify.
The majority of the completions mentioned haven't been fixed yet. Was this closed on mistake, @faho ?
Yes, a PR mentioned "fixes #6981", so merging it auto-closed this one. Sorry, reopening!
Is the checklist at the top up to date? I would like to do one if that's okay!
@T19700 ~~No, it's not really up-to-date. There have been recent PRs that we've not yet selected.~~ Edit: I think I've checked them all.
Honestly feel free to pick whichever interests you, just check that
- there are descriptions there worthy of fixing (e.g. they're too long)
- there's not already an open PR - https://github.com/fish-shell/fish-shell/pulls (currently there are none about fixing descriptions).
Alternatively, if you want to overthink finding too long descriptions, I've messed with this little function:
function print_description
argparse l/len= n/names-only -- $argv
or return
set -l len $_flag_len 100
set -l names_only $_flag_names_only
for file in $argv
set -l lines (string match -re '^\s*complete ' < $file | while read -lat f
argparse c/command= p/path= e/erase \
s/short-option= l/long-option= o/old-option= \
a/arguments= w/wraps= n/condition= d/description= \
k/keep-order f/no-files F/force-files r/require-parameter x/exclusive \
C/do-complete= \
-- $f 2>/dev/null
or continue
if set -q _flag_d[1]
echo $_flag_d
end
end | sort -u | string match -r '^.{'$len[1]',}$')
and echo (set_color blue)$file(set_color normal)
and not set -q names_only[1]
and printf %s\n $lines
end
end
Use like print_description --len=100 -n share/completions/*.fish to show you all completion files with descriptions at least 100 characters long.
This doesn't work 100%, for one it won't be reading continuation lines:
complete -c foo -d \
'this is the description and it is really long
but it won't be read'
But it should point towards a bunch. For example it shows the longest description in all of fish right now is:
https://github.com/fish-shell/fish-shell/blob/eb7603f1c6ed1fca33da0faa3252e3a62326fecc/share/completions/gcc.fish#L894
At a whopping 295 characters.
Hi again! I'm working on the quilt.fish function right now and there are many instances of the word "specified", is there an abbreviation that is acceptable to replace them with? Like "spec."?
is there an abbreviation that is acceptable to replace them with? Like "spec."?
@T19700:
"given" often works. We don't really abbreviate words in that way, unless it's a well-known abbreviation like "e.g." or "i.e.".
Say you have
complete -c quilt -a delete -r -d "Remove the specified or topmost patch from the series file"
you could rewrite this description as "Remove the given patch (or top) from the series file".
However, this is already 58 characters, which is okay. It's under the 60 soft limit I gave at the top. My proposed rewrite is 52.
Or you can just use "this" instead of "the specified":
complete -c quilt -a annotate -r -d "Print an annotated listing of the specified file"
"Print a listing of this file"
Okay, thank you! I've gotten all of the definitions down to around 70 characters, does that sound good? There are some that are tough to get lower than that. Ill submit a pull request by the end of the day for it if 70 is good.
Like I said, 60 is a "soft" limit. It's something to aim for. If you really do need more, that's okay!
@faho I saw that you've worked a bit on GCC completion file, that's why I decided to publish whatever I have now :) being postponing my old branch for a while, but grasping ALL GCC flags before pushing it'd take too long.
So maybe we can discuss what to do with those over my PR https://github.com/fish-shell/fish-shell/pull/9722.
Alright, I've done some more work on this, and we no longer have any excessively long (>100 characters) descriptions.
Some still go up to 96, but to be honest for a lot I'm not sure how to phrase it shorter, without making it nonsensical.
So I am going to call this fixed for now - the big problem has been solved (gcc had a 408 character description, mvn had a 224 char one).
That doesn't mean that descriptions couldn't still be improved across the board, of course.