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,
     "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);
     );
 
 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 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>.
 
 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>.
 
 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
 
 
 =head1 OPTIONS
 


@@ -106,6 +125,105 @@ End of options.
 
 =back
 
 
 =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
 =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/
 
 
 Then explore the tags in ~/music/tags/
 

-FIXME: fstab
-

 =head1 BUGS
 
 Please report any found to ianb@erislabs.net
 =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>
 
 
 Ian Beckwith <ianb@erislabs.net>
 

+Many thanks to Aubrey Stark-Toller for help wrangling SQL.
+

 =head1 AVAILABILITY
 
 The latest version can be found at:
 
 =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
 
 
 =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
 
 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,
 (at your option) any later version.
 
 This program is distributed in the hope that it will be useful,