Improve docs

tag.sh

@@ -1,20 +1,56 @@
 #!/usr/bin/env bash
 set -ueo pipefail
 [ "${DEBUG:-0}" = "1" ] && set -x
-# usage:
-#   - init - create an empty database
-#   - import - import $FILE or import $DIR, both can be multiple values
-#   - autoimport ($REGEX|video) $FOLDER - will import all files in $FOLDER with a $REGEX filter,
-#                                         or one of the preset filters:
-#                                         - video
-#   - add (tag|filename) $VALUE - adds a new tag or filename of $VALUE
-#   - list (tags|files) - lists all the values in a table
-#   - bytag $TAG - list all files by tag label
-#   - tag $FILENAME $TAG - tag $FILENAME with $TAG, $TAG can be repeated
-#   - listtags $FILENAME - list all tags for $FILENAME
+: <<'DOCS'
+=head1 NAME
 
-# TODO: adjust sqlite_insert_multiple to allow defining columns per insert, currently it's hardcoded to 2
-# TODO: merge sqlite_insert_single and sqlite_insert_multiple probably as result of the above
+tags is a tool for keeping file tags in a SQLite database.
+
+=head1 SYNOPSIS
+
+tag [OPTIONS] <init|import|add|list|bytag|listtags>
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<init>
+
+Create an empty database.
+
+=item B<import> I<filename>
+
+Import filename, can be single value or multiple values.
+
+=item B<autoimport> I<regexp> I<path>
+
+Import all files in I<path>. Can be filtered using custom I<regexp>, or one of the regular expression presets (currently only "video").
+
+=item B<add> I<type> I<value>
+
+Adds a new item of the specified I<type>: C<tag>, C<file>, C<hash>.
+
+=item B<list> I<type> I<[--bytag|--byfile]> 
+
+List C<tags>, C<files>, C<hashes> (these are all table names, internally).
+
+=item B<tag> I<[-i|--interactive]> I<--file|--id> I<tag>
+
+Tags I<filename> with one or more I<tag>.
+
+=back
+
+=head1 TODO
+
+* adjust sqlite_insert_multiple to allow defining columns per insert, currently it's hardcoded to 2
+* merge sqlite_insert_single and sqlite_insert_multiple probably as result of the above
+* listtags doesn't work with full path
+* listtags doesn't work after tagging a file
+
+=head1 LICENSE AND COPYRIGHT
+
+=cut
+DOCS
 
 SCRIPT_DIR=$(dirname "$(readlink "$0")")
 SCRIPT_NAME=$(basename "$0")
@@ -80,7 +116,8 @@ add() {
     [ "$1" = "path" ] && shift && add_path "$@" && exit 0
     [ "$1" = "hash" ] && shift && add_hash "$@" && exit 0
     [ "$1" = "file" ] && fail "Use \"$SCRIPT_NAME add path\" instead."
-    fail "Usage: $SCRIPT_NAME add tag/path/hash"
+    pod2usage "$0"
+    exit 1
 }
 
 sqlite_query() {
@@ -118,11 +155,11 @@ sqlite_insert_single() {
 
 sqlite_insert_multi() {
     # $TABLE $COLUMN $VALUE1 $VALUE2
-    [ -z "$1" ] && fail "No table specified."
+    [ -z "${1:-}" ] && fail "No table specified."
     TABLE="$1"
-    [ -z "$2" ] && fail "No column(s) supplied."
+    [ -z "${2:-}" ] && { pod2usage "$0"; exit 1 ; }
     COLUMN="$2"
-    [[ -z "$3" || -z "$4" ]] && fail "No column values supplied."
+    [[ -z "${3:-}" || -z "${4:-}" ]] && { pod2usage "$0"; exit 1 ; }
     shift 2
     VALUES="($1,$2)"
     if [[ ! -z "${3:-}" && ! -z "${4:-}" ]]; then
@@ -216,7 +253,7 @@ dbfile_exists() {
 
 main() {
 
-    [ -z "${1:-}" ] && fail "Usage: tag init/add/import/autoimport/list/listtags"
+    [ -z "${1:-}" ] && { pod2usage "$0"; exit 1; }
 
     if [[ "$1" = "init" ]]; then
         init "${2:-$DB_FILE}"
@@ -245,7 +282,7 @@ main() {
     fi 
 
     if [[ "$1" = "list" ]]; then
-        [ -z "$2" ] && fail "No table supplied."
+        [ -z "${2:-}" ] && { pod2usage "$0"; exit 1 ; }
         TABLE_NAME="$2"
         sqlite_query "SELECT * FROM \"${TABLE_NAME}\""
         exit 0
@@ -279,7 +316,7 @@ main() {
     fi 
 
     if [[ "$1" = "listtags" ]]; then
-        [ -z "${2:-}" ] && fail "Usage: $SCRIPT_NAME listtags filename"
+        [ -z "${2:-}" ] && { pod2usage "$0"; exit 1 ; }
         listtags "$2"
         exit 0
     fi