Linux – Custom help / man -like command (for reminders)

command linelinux

I often end up in a situation, where I don't use a command for a while, but then suddenly need to use it; and I need to wade through several help pages until constructing the command line I want. Case in point: occasionally I need to use nmcli; and then I need to re-check nmcli nm help and nmcli con help several times, until I remember what sort of a command I need.

What I have done then, is basically document some of this in a text file; the problem is then I usually save it on Desktop; then every once in a while I clean the Desktop files, so I end up thinking "ah, I don't really use nmcli-examples.txt all that much, let me move this one elsewhere too"; then when I need it again, I have to issue a find for it first (provided I can remember the file name to look for).

So I was thinking – making a script that: would have a default location set (e.g. ~/customhelp), where one could keep specifically these kind of reminder text files; and would list the files in that directory upon bash smart completion for the first command argument; and would open such a file name supplied on the command line either in less (or in the default GUI text editor if a command line switch is supplied) shouldn't be too difficult.

But I'd rather not try reinventing the wheel, so I was wondering – if any sort of a command for a scheme of usage as described, exists already in a typical GNU/Linux system?

Best Answer

Expanding on the comment by @SamiLaine for using man - one reason I didn't like it, was because I expected it to be tedious to set up, and I think this post will show that; but, it seems to work. First, some introduction can be found here:

First let's create the directory and add it to MANPATH:

mkdir ~/myreminderhelp
echo 'MANPATH=$MANPATH:'$(echo ~/myreminderhelp) >> ~/.bashrc

Let's test if it is found: close the terminal, open a new terminal; and then:

manpath -d 2>&1 | grep myrem

Unfortunately, this reports nothing for me; even if echo $MANPATH says :~/myreminderhelp.

Trying with global /etc/bash.bashrc (after deleting the line in local ~/.bashrc, and restarting terminal again):

sudo bash -c "echo 'MANPATH=$MANPATH:'$(echo ~/myreminderhelp)" # check home dir printout
sudo bash -c "echo 'MANPATH=$MANPATH:'$(echo ~/myreminderhelp) >> /etc/bash.bashrc"

Restart terminal; still manpath does not report this directory. Let's now try this:

sudo bash -c "echo 'MANDATORY_MANPATH  '$(echo ~/myreminderhelp) >> /etc/manpath.config"

Close and reopen terminal again; finally, we get:

$ manpath 
/usr/local/man:/usr/local/share/man:/usr/share/man:/media/extern/texlive/2011/bin/i386-linux/man:~/myreminderhelp

In fact, after finding this, I erased the line from /etc/bash.bashrc, and manpath still reports the directory. So, I guess editing /etc/manpath.config is all that is needed.

Ok, so let's create an example custom reminder file here:

echo "Just a bit of a reminder...

Use nmcli con --help" >> ~/myreminderhelp/nmcli-reminder.txt

Then use txt2man to get a man formatted file, and gzip it:

cat ~/myreminderhelp/nmcli-reminder.txt | txt2man > ~/myreminderhelp/nmcli-reminder.1
gzip ~/myreminderhelp/nmcli-reminder.1

Restart terminal again, try typing man nm and press TAB - autocompletion shows nmcli-reminder is not found...

So let's try put our files in a man section subfolder; the links above indicate section 7 would be appropriate; so:

mkdir ~/myreminderhelp/man7
mv ~/myreminderhelp/nmcli-reminder.* ~/myreminderhelp/man7/
tree ~/myreminderhelp # to check - ok

Restart terminal again; try typing man nm and press TAB - autocompletion finally works:

$ man nmcli # and here press TAB:
nmcli           nmcli-reminder

... but now we have this problem:

$ man nmcli-reminder 
No manual entry for nmcli-reminder

Damn it. Could be that currently, our file is nmcli-reminder.1.gz indicating section 1 - let's rename it:

mv ~/myreminderhelp/man7/nmcli-reminder.1.gz ~/myreminderhelp/man7/nmcli-reminder.7.gz
man nmcli-reminder

... and finally the man command works!

So for this use case, probably it's best to keep the source .txt files directly in ~/myreminderhelp/, and then generate man pages in the appropriate subfolder - as in:

$ tree ~/myreminderhelp/
~/myreminderhelp/
├── man7
│   └── nmcli-reminder.7.gz
└── nmcli-reminder.txt

... the appropriate generation commands for this being:

cat ~/myreminderhelp/nmcli-reminder.txt | txt2man > ~/myreminderhelp/man7/nmcli-reminder.7
gzip ~/myreminderhelp/man7/nmcli-reminder.7

And here is a ~/myreminderhelp/buildreminders.sh script:

#!/usr/bin/env bash

DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

for ix in $DIR/*.txt; do
  bx=$(basename $ix)
  isn=${bx%%.txt}
  echo Processing $isn;
  set -x
  # txt2man -t "$isn" -s 7 $ix > $DIR/man7/${isn}.7
  pandoc -f markdown -t man -s -o $DIR/man7/${isn}.7 $ix
  gzip --force $DIR/man7/${isn}.7
  { set +x; } 2>/dev/null
done

tree -a $DIR

EDIT: Turns out, it is very difficult to get txt2man to leave literal source code unformatted, as it tends to auto-extract information like man (sub)sections etc. I've modified the script above to use pandoc instead (via WritingManPages - HerzbubeWiki) -- at least with pandoc with a Markdown input, you have some control over what is literal preformatted text, and what isn't ...

However, both of these tools will indent contents, as is typical for a man page (since there, section headings are non-indented, rest of the text content as in paragraphs, is). And I'm not sure I end up liking that all too much...

Related Question