Commands in GoldenDict – Offline Dictionary of man, grep, pupppet help and your commands

NEW: There is a new, better version of this article and program.
Add Python reference, man pages and your own commands to dictionary.
This example shows how to add commands as dictionaries to GoldenDict. Commands show information for the exact versions of software we have installed and this information (man, puppet help…) gets updated automatically with the software.
By using ‘grep’ as a command, we can quickly add any one-thing-per-line as a dictionary.

NEW: There is a new, better version of this article and program.

Acute – Discard Output If Command Fails

We want to suppress command output if the exit status is failed, so that dictionary interface is not cluttered with “No documentation for ‘foobar'” messages. For this, I created a script called ‘acute’.

# acute 0.1.0 - run command, discard output if it fails
# Copyright 2017 Tero Karvinen
OUT=$($* 2>&1) && echo -e "$OUT\n\n"||true

As you can see, acute is almost the opposite of chronic(1) from moreutils.
To make ‘acute’ available to all users, write it to a text file, make it runnable and copy it to /usr/local/bin:

$ nano acute
$ chmod ugo+x acute
$ sudo cp acute /usr/local/bin/acute

And test it – it should work for any user, in any directory, without typing a path to the command.

$ acute echo See you at
See you at

Acute works for many commands

$ acute puppet help "%GDWORD%"
$ acute man "%GDWORD%"
$ acute apt-cache show "%GDWORD%"

Acute works by checking command exit status $?. It only works with commands that set exit status to failed when they fail to find documentation. It doesn’t work for commands that always return true, such as pydoc3 or puppet describe. For them, you could try something like “puppet describe ‘%GDWORD%’|grep -vz ‘^Unknown type'” or ”acute pydoc3 ‘%GDWORD%’|grep -vz ‘^No Python documentation'”, but I haven’t tested this yet.

Grep – Show Only Matching Lines

The most obvious thing. If you have a file with your favorite command lines, you can just grep it.
Many files come as one-thing-per-line, such as CSV or TSV dumps. Even if you later plan to turn it into a real dictionary (DSL, AAR, ZIM…), it’s good to try it first. Rapid prototyping, MVP and failing fast.

$ acute grep -C 2 "%GDWORD%" /home/tero/docs/commands.tmd

What Next?

If you need references for things you don’t have installed, see my offline reference for programmers.
What commands do you integrate to your dictionary?
This article has been updated and chapters rearranged. Added version number to acute.

Posted in Uncategorized | Tagged , , , , , , , | Leave a comment

Leave a Reply

Your email address will not be published. Required fields are marked *