twoman - Script documentation format

Many scripts don’t come with option parsing to support a -h flag or manual pages. But a way to document the arguments without relying on flags is still useful. leah2 and I use the second line of scripts for the synopsis and a short description. Following comment lines are used for more documentation if necessary.

This looks similar to the following example:

#!/bin/sh
# script arg [args...] - Description
# More lines until the first non-comment line

I followed this convention for years and it helped a lot, many of the scripts written for Void Linux use this format, including Leahs awesome xtools script collection for working with xbps-src.

Some day I wrote the man2 script and to look at the documentation without having to use a pager or file editor. Leah rewrote it with just sed(1) which replaced my script. Some time later the script was renamed to twoman.

$ twoman xpkg
xpkg [-RamOHDLvV] - convenient package lister
$ twoman git-merge-pr
git merge-pr [PRNUM][@REMOTE] [GIT-AM FLAGS...] - list or apply GitHub pull request from command-line

Another example is diffed a script to clean and change patch files with a bit more documentation.

$ twoman diffed
diffed [-CHT] [-pN|-a|-P PREFIX] [-s SUBST -r REPL] [-x EXCLUDE] - filter for unified diffs
  -C                 remove all non-diff lines
  -H                 remove diff headers
  -T                 remove file timestamps
  -p N               strip N levels of directories from file names
  -a                 add a/ b/ to file names
  -P                 add PREFIX to file names
  -s SUBST -r REPL   replace regexp SUBST with REPL in filenames
  -x EXCLUDE         exclude diffs touching files matching regexp EXCLUDE
To the extent possible under law, Leah Neukirchen has waived
all copyright and related or neighboring rights to this work.
http://creativecommons.org/publicdomain/zero/1.0/
05may2016:: don't modify /dev/null path
09sep2016:: known bug: lines which remove -- or add ++ are regarded
            as new diffs
16jan2018:: add -a, -P

Where can I get it?

Leahs version for zsh(1):

# twoman - show inline "manpage"
# 13feb2017  +leah+
twoman() {
  for cmd; do
    sed -n '1{/^[^#][^!]/q;d};0,/^$\|^[^#]/s/^# //p' ${commands[$cmd]?not found}
  done
}

And my version as a shell script:

#!/bin/sh
# twoman CMD... - show comments at the beginning of a script
for cmd; do
        cmd=$(command -v "$cmd" 2>/dev/null)
        [ -z "$cmd" ] && continue
        sed -rn '1{/^[^#][^!]/q;d;};/^$|^[^#]/q;s/^# //p' $cmd
done