id3fsd: update man page

diff --git a/sbin/id3fsd b/sbin/id3fsd
index a699cb2..93d2d6c 100755 (executable)
--- a/sbin/id3fsd
+++ b/sbin/id3fsd
@@ -36,6 +36,7 @@ my $optret=GetOptions(
     "help|h"       => \$help,
     "database|f=s" => \$dbpath,
     "t|tagdepth=s" => \$tagdepth,
+    "o=s"          => sub {;}, # silently drop options passed by mount
     );
 
 usage() if(scalar(@ARGV) != 2 || !$optret || $help);
@@ -73,6 +74,16 @@ B<id3fsd> [B<-vh>] S<B<[-f >I<dbfile>]> [B<-->] I<SOURCEDIR> I<MOUNTPOINT>
 id3fsd provides a browsable filesystem of your music files, organised
 into sub-directories by id3 tags (or flac/ogg comments).
 
+id3fsd allows you to construct boolean queries from a tag folksonomy
+such as:
+
+  goth/AND/decade/1980s/
+  postrock/AND/NOT/rating/terrible/
+  thrash/OR/rapmetal/AND/NOT/wears-a-red-hat/
+  prog/AND/decade/1970s/OR/psychedelia/AND/decade/1960s/
+  location/sweden/AND/screamo/AND/postrock/
+
+Multiple tags can be stored in the genre tag, separated by commas.
 An index should first be created with L<id3fs-index(1)>, then id3fsd
 can mount the files in I<SOURCEDIR> on the directory I<MOUNTPOINT>.
 
@@ -82,7 +93,15 @@ at I<SOURCEDIR>/B<.id3fs>.
 The resulting filesystem is read-only. Tags appear as directories,
 and files appear as symlinks to the actual files in I<SOURCEDIR>.
 
-FIXME: better description, allow_others/fuse.conf, fstab, explain genre tag
+=head1 QUICKSTART
+
+To mount a view of F<~/music> on F<~/tags>:
+
+  $ mkdir ~/tags
+  $ id3fs-index ~/music
+  $ id3fsd ~/music ~/tags
+
+You may need to be in the I<fuse> group, or be root.
 
 =head1 OPTIONS
 
@@ -106,6 +125,105 @@ End of options.
 
 =back
 
+=head1 FILESYSTEM LAYOUT
+
+A path in the filesystem consists of a tag query expression, followed
+by directories containing the matching files, arranged by artist and
+album.
+
+Example paths:
+
+  /krautrock/AND/year/1971/
+  /krautrock/AND/year/1971/Can
+  /krautrock/AND/year/1971/Can/Tago Mago/01-Paperhouse.mp3
+  /krautrock/AND/year/1971/Can/NOALBUM/Can - Oh Yeah (Live).mp3
+  /krautrock/AND/year/1971/Can/TRACKS/01-Paperhouse.mp3
+  /krautrock/AND/year/1971/Can/TRACKS/Can - Oh Yeah (Live).mp3
+  /krautrock/AND/year/1971/NOARTIST/unknown-track.mp3
+  /krautrock/AND/year/1971/TRACKS/01-Paperhouse.mp3
+
+=head2 Tags
+
+Tags are extracted from the B<genre> tag of audio files with
+L<id3fs-index(1)>.
+
+Within the genre frame/comment, tags are separated by commas.
+
+Tags can have values, separated by a slash, eg I<metal/thrash>,
+I<rating/5>. Certain tags are automatically filled in from other file
+metadata, see L</"Special Tags>.
+
+=head2 Special Directories
+
+=over 4
+
+=item B<ALL>
+
+This is a special directory in the root of the filesystem, that
+provides access to all the indexed files, regardless of tags assigned.
+
+=item B<TRACKS>
+
+All tracks that match the given tag expression, whether they have an
+assigned artist and album or not.
+
+=item B<NOARTIST>
+
+Tracks matching the given expression that do not have an artist tag.
+
+=item B<NOALBUM>
+
+Tracks matching the given expression that do not have an album tag.
+
+=back
+
+=head2 Special Tags
+
+Several tags are automatically derived from other metadata in the
+audio files:
+
+=over 4
+
+=item B<year>
+
+Extracted from the B<year> or B<DATE> tag. If not found defaults to
+B<year/UNKNOWN>.
+
+=item B<decade>
+
+Also extracted from the B<year> or B<DATE> tag. If not found
+defaults to B<decade/UNKNOWN>.
+
+=item B<v1genre>
+
+If a mp3 file has an ID3V1.1 genre tag, its value is assigned to
+v1genre.
+
+=item B<audiotype>
+
+Type of audio file (mp3, ogg, flac). Always set.
+
+=back
+
+=head1 FUSE AND MOUNTING AUTOMATICALLY
+
+For others to be able to view your id3fs mount(s), you need to set the
+option B<user_allow_other> in F</etc/fuse.conf>.
+
+To mount a filesystem automatically, put an entry in F</etc/fstab>
+like:
+
+  id3fsd#/source/dir    /mount/point    defaults   0   0
+
+=head1 CAVEATS
+
+Because id3fs offers a combinatorial explosion of views of your files,
+processes recursing into the mount point will take a B<long> time to
+traverse it.
+
+Ensure your backups, cron jobs, F</etc/updatedb.conf>, etc. are
+configured to exclude the mount point.
+
 =head1 EXAMPLES
 
 To mount an id3fs filesystem which indexes B<~/music/albums> on
@@ -127,8 +245,6 @@ and mount the filesystem:
 
 Then explore the tags in ~/music/tags/
 
-FIXME: fstab
-
 =head1 BUGS
 
 Please report any found to ianb@erislabs.net
@@ -141,19 +257,21 @@ L<id3fs-index(1)>, L<http://fuse.sourceforge.net>
 
 Ian Beckwith <ianb@erislabs.net>
 
+Many thanks to Aubrey Stark-Toller for help wrangling SQL.
+
 =head1 AVAILABILITY
 
 The latest version can be found at:
 
-B<http://erislabs.net/ianb/projects/id3fs/>
+L<http://erislabs.net/ianb/projects/id3fs/>
 
 =head1 COPYRIGHT
 
-Copyright 2010 Ian Beckwith <ianb@erislabs.net>
+Copyright (C) 2010  Ian Beckwith <ianb@erislabs.net>
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 3 of the License, or
+the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.
 
 This program is distributed in the hope that it will be useful,