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.

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.