Fetch Personalized Command Explanations with 'um' from Your Terminal

I stumbled upon this page: http://ratfactor.com/cards/um

Dave Gauer describes how he has a shell script, um, that he can use as a man replacement to help remember how to use a command. Dave’s implementation uses the cards} from his own Wiki, because the um pages there are “consolidated, I won’t forget about them, it’s easy to list, create, and update pages.” (To be honest, though, I can’t figure out where his um cards actually are, and what they look like.)

Since I’m using a Zettelkasten for all my stuff, I have notes that contain examples for commands I don’t use a lot, like ffmpeg. That’s just as powerful.

File Naming Scheme

Let’s say I want a result for um sed that produces helpful sed explanations and examples.

How do I identify the corresponding note?

  • By file name:
    • I should ignore the note’s ID;
    • the note’s file name should contain explitic markers to identify the command;
    • the file name should also be human-readable.
  • Via index:
    • Map the command name to an overview note.
    • I could create a (Multi)Markdown table of key–value-pairs.

The file name option sounds simplest to implement: No need for a Markdown table parser. Then again, Marin Todorov has a package for that.

The naming scheme? Basically this:

ZETTELID § `COMMANDNAME` rest of readable title

For example:

202304181909 § `sed` command.md
  • The §, per my convention, denotes an overview of sorts.
  • Surrounding the program name in backticks works with my Markdown expectations.
  • The human-readable string can be anything else.

I’d need to grep for "§ " followed by the search term in backticks. That’s simple:

$ find . -name "*§ \`sed\`*"
./202304181909 § `sed` command.md

Making a function of this:

um() {
    find . -name "*§ \`$1\`*"

Then um sed produces the same filename.

But I don’t want filenames; I want content!

Pretty Printing of Markdown

The potato version would simply use cat or less (or the PAGER environment variable, if set).

I could also use mdcat to show rendered Markdown inside the Terminal. (Notably absent: tables and footnotes.)

um() {
    find ~/Archiv/ -name "*§ \`$1\`*" | head -n 1 | xargs -I {} mdcat {}

I’m limiting the output of find to the first result, just to be sure, and then pass the filename to mdcat.

Note I changed the path to search in to my notes directory instead of .. Trailing slash required.

Surprising output? Read on

The output of um sed on my machine then is this:

┄202304181909 § sed command

#sed #shell

{{202211120933 Use sed and xargs -n2 to rename files.md}} {{202106211122 Use sed to prefix STDOUT.md}} {{201805011641 Use sed for stateful
replacements in text files.txt}}

This is just a concatenation of 3 filenames, you say?

You’re correct!

That’s because I need to figure out a way to transclude this overview to show all the atomic notes at once in a concatenated output.

Here’s a better example: um tmux.

That contains a couple of examples in the note itself.

File transclusion is tricky and even less standardized, so I’ll keep that as an exercise for future-me.