From: Ian Beckwith <ianb@erislabs.net>
Date: Fri, 24 Sep 2010 02:02:29 +0000 (+0100)
Subject: id3fs-index: document
X-Git-Tag: debian/1.0-1~181
X-Git-Url: http://erislabs.net/gitweb/?p=id3fs.git;a=commitdiff_plain;h=cd69739c61886e975d3ea0b0ec19c0e0fcba49bb

id3fs-index: document
---

diff --git a/bin/id3fs-index b/bin/id3fs-index
index 62a631e..99ae6bb 100755
--- a/bin/id3fs-index
+++ b/bin/id3fs-index
@@ -2,7 +2,7 @@
 # Ian Beckwith <ianb@erislabs.net>
 #
 
-use lib '/home/ianb/projects/id3fs/id3fs/lib';
+use lib '/home/ianb/projects/id3fs/id3fs/lib'; # FIXME: remove
 use strict;
 use Getopt::Long qw(Configure);
 use ID3FS::DB;
@@ -14,15 +14,15 @@ my $verbose=0;
 my $help=0;
 my $basedir=undef;
 my $dbpath=undef;
-
 my @extensions=qw(mp3); # ogg flac); # FIXME
+
 Configure(qw(bundling no_ignore_case));
 my $optret=GetOptions(
     "verbose|v"      => \$verbose,
     "quiet|q"        => sub { $verbose=0; },
     "help|h"         => \$help,
-    "basedir|d=s"    => \$basedir,
-    "database|db=s"  => \$dbpath,
+    "dir|d=s"        => \$basedir,
+    "database|f=s"   => \$dbpath,
     "extensions|e=s" => sub { @extensions=split(/\s+|\s*,\s*/, $_[1]); },
     );
 
@@ -58,26 +58,32 @@ sub wanted
 
 sub usage
 {
-    die("Usage: $me [-v] [-q] [-h] [--] file...\n".
-	" -v\tVerbose\n".
-	" -q\tQuiet (default)\n".
-	" -h\tThis help\n".
-	" --\tEnd of options\n");
+    die("Usage: $me [-vqh] [-d basedir] [-b dbpath] [-e mp3,ogg,flac] [--] DIR...\n".
+	" -v|--verbose\t\t\tVerbose\n".
+	" -q|--quiet\t\t\tQuiet (default)\n".
+	" -d|--dir=PATH\t\t\tBase directory of source files (default: ARGV[0])\n".
+	" -f|--database=FILE\t\tPath to database file (default: basedir/.id3fs)\n".
+	" -e|--extensions=EXT1,EXT2\tFile extensions to index (default: mp3, ogg, flac)\n".
+	" -h|--help\t\t\tThis help\n".
+	" --\t\t\t\tEnd of options\n");
 }
 
 __END__
 
-
 =head1 NAME
 
-program - description
+id3fs-index - Add files to id3fs index
 
 =head1 SYNOPSIS
 
-B<> [I<-v>] [I<-q>] [I<-h>] [I<file>...]
+B<id3fs-index> [I<-vqh>] S<[I<-d >B<basedir>]> S<[I<-f >B<dbpath>]> S<[I<-e >B<mp3,ogg,flac>]> [--] [B<DIR>...]
 
 =head1 DESCRIPTION
 
+Extracts id3 tags from mp3 files (and comment tags from ogg and flac
+files) and adds them to a sqlite database, ready for mounting
+with L<id3fsd(8)>.
+
 =head1 OPTIONS
 
 =over 4
@@ -90,6 +96,28 @@ Enable verbose operation.
 
 Quiet (no output). This is the default.
 
+=item S<B<-d >I<PATH>> | S<B<--dir=>I<PATH>>
+
+Specify base directory of source files. All files will be indexed
+relative to this point.
+
+If not specified, defaults to the first non-option argument on the
+command line. Note that to avoid ambiguities, if more than one
+directory is specified on the command line, the base directory must
+be specified explicitly.
+
+All files indexed must be under the base directory.
+
+=item S<B<-f >I<FILE>> | S<B<--database=>I<FILE>>
+
+Database file to use. If not specified, defaults to
+a hidden file called B<".id3fs"> under the base directory.
+
+=item S<B<-e >I<EXT1,EXT2>> | S<B<--extensions=>I<EXT1,EXT2>>
+
+File extensions to consider when indexing.
+Defaults to B<.mp3>, B<.ogg> and B<.flac>.
+
 =item B<-h>
 
 Show a short help message.
@@ -100,18 +128,37 @@ End of options.
 
 =back
 
-=head1 FILES
+=head1 EXAMPLES
+
+Index all files in the current directory:
+
+    id3fs-index .
+
+Index current directory, printing each subdirectory as it recurses
+into it:
+
+    id3fs-index -v .
 
-=head1 ENVIRONMENT
+Just index some sub-directories:
 
-=head1 DIAGNOSTICS
+    id3fs-index -d . dir1 dir2
+
+Store the database in a custom location:
+
+    id3fs-index -f ~/.id3fs/index.sqlite .
+
+Only index .mp3 and .flac files:
+
+    id3fs-index -e mp3,flac .
 
 =head1 BUGS
 
-None known. Please report any found to ianb@erislabs.net
+Please report any found to ianb@erislabs.net
 
 =head1 SEE ALSO
 
+L<id3fsd(8)>
+
 =head1 AUTHOR
 
 Ian Beckwith <ianb@erislabs.net>