smugfs(4): new program

man/man4/smugfs.4

@@ -0,0 +1,278 @@
+.TH SMUGFS 4
+.SH NAME
+smugfs \- file system access to SmugMug photo sharing
+.SH SYNOPSIS
+.B smugfs
+[
+.B -DFH
+]
+[
+.B -k
+.I keypattern
+]
+[
+.B -m
+.I mtpt
+]
+[
+.B -s
+.I srvname
+]
+.SH DESCRIPTION
+.I Smugfs
+is a user-level file system that provides access to images
+stored on the SmugMug photo sharing service.
+It logs in after
+obtaining a password from 
+.IR factotum (4)
+using
+.B server=smugmug.com
+and
+.I keypattern
+(if any)
+as key criteria
+(see
+.IR auth (3)).
+Then 
+.I smugfs
+serves a virtual directory tree mounted at
+.I mtpt
+(default
+.BR /n/smug )
+and posted at 
+.I srvname ,
+if the 
+.B -s
+option is given.
+.PP
+The directory tree is arranged in five levels:
+root, user, category, album, and image.
+For example,
+.B /n/smug/cmac/
+is a user directory,
+.B /n/smug/cmac/People/
+is a category directory,
+.B /n/smug/cmac/People/Friends/
+is an album directory,
+and
+.B /n/smug/cmac/albums/Friends/2631/
+is an image directory.
+.PP
+SmugMug allows fine-grained classification
+via subcategories, but subcategories are not yet implemented.
+.ig
+  Subcategories are inserted as
+an additional directory level between category 
+and album.
+[Subcategories are not yet implemented.]
+..
+.PP
+All directories contain a special control file named
+.BR ctl ;
+text commands written to 
+.B ctl
+change 
+.IR smugfs 's
+behavior or implement functionality
+that does not fit nicely into the file system
+interface.
+.PP
+.I Smugfs
+caches information about users, categories, albums,
+and images.  If changes are made outside of
+.I smugfs
+(for example, using a web browser),
+the cache may need to be discarded.
+Writing the string
+.B sync
+to a directory's
+.B ctl
+file causes
+.I smugfs
+to discard all cached information used to
+present that directory and its children.
+Thus, writing
+.B sync
+to the root
+.B ctl
+file discards all of
+.I smugfs 's
+cached information.
+.SS "Root directory"
+The root directory contains directories
+named after users.
+By default, it contains only a directory for
+the logged-in user, but other directories will
+be created as needed to satisfy directory lookups.
+.PP
+In addition to user directories, the root directory
+contains three special files:
+.BR ctl ,
+.BR rpclog ,
+and
+.BR uploads .
+Reading
+.B rpclog
+returns a list of recent RPCs issued to the SmugMug API server.
+Reads at the end of the file block until a new RPC is issued.
+The
+.B uploads
+file lists the file upload queue (q.v.).
+.SS "User directories"
+User directories contain category directories
+named after the categories.
+SmugMug pre-defines a variety of categories,
+so it is common to have many categories that
+do not contain albums.
+.PP
+In a user directory, creating a new directory
+creates a new category on SmugMug.
+Similarly, renaming or removing a category
+directory renames or removes the category on SmugMug.
+Categories cannot be removed if they contain albums.
+.PP
+User directories also contain a directory
+named
+.B albums
+that itself contains all of that user's albums.
+.SS "Category directories"
+Each category directory contains album directories
+named using the album's title.
+.PP
+In a category directory, creating a new directory
+creates a new album on SmugMug.
+Similarly, renaming or removing an album directory
+renames or removes the album on SmugMug.
+Albums cannot be removed if they contain images.
+.ig
+.PP
+Category directories might also contain subcategory directories.
+Like albums, subcategories can be renamed and removed (when empty).
+Unlike albums, subcategories cannot be created via ordinary
+file system operations.
+Instead, write the command
+.B subcategory
+.I name
+to the category's
+.B ctl
+file.
+.PP
+Subcategories are identical to categories
+except that they cannot themselves contain subcategories.
+..
+.SS "Album directories"
+Each album directory contains image directories
+named using the image's decimal SmugMug ID.
+Image directories cannot be created or renamed,
+but they can be removed.  Removing an image directory
+removes the image from the album on SmugMug.
+.PP
+Album directories also contain three special files,
+.BR ctl ,
+.BR settings ,
+and
+.BR url .
+.PP
+The
+.B settings
+file contains the album settings in textual form,
+one setting per line.
+Each line represents a single setting and is formatted
+as an alphabetic setting name followed by a single tab
+followed by the value.
+Many settings can be changed by writing new setting lines,
+in the same format, to the
+.B settings
+file.
+.PP
+Copying a file into the album directory queues it for
+uploading to SmugMug to be added to the album.
+Files disappear from the album directory once they
+have finished uploading, replaced by new image directories.
+The 
+.B uploads
+file in the root directory lists all pending uploads,
+which are stored temporarily
+in 
+.BR /var/tmp .
+.SS "Image directories"
+Each image directory contains an image file, named
+with its original name, if available.
+If the image belongs to another user, SmugMug does not
+expose the original name, so the file is named
+.RB \fInnnn\fP .jpg ,
+where
+.I nnnn
+is the SmugMug image ID number.
+The file content is the original image
+or else the largest image available.
+.PP
+The directory contains a 
+.B settings
+file holding per-image settings, similar to the 
+file in the album directory;
+and a
+.B url
+file, containing URLs to the various sized images
+on the SmugMug server.
+.SH EXAMPLES
+.LP
+Mount
+.I smugfs
+on
+.BR /n/smug ;
+the current user must have write access to 
+.B /n/smug
+and
+.BR /dev/fuse .
+.IP
+.EX
+% smugfs
+.EE
+Watch API calls as they execute:
+.IP
+.EX
+% cat /n/smug/rpclog &
+.EE
+Create a new album in the Vacation category
+and fill it with photos:
+.IP
+.EX
+% mkdir /n/smug/you/Vacation/Summer
+% cp *.jpg /n/smug/you/Vacation/Summer
+.EE
+.LP
+The photos are now uploading in the background.
+Wait for the uploads to finish:
+.IP
+.EX
+% while(test -s /n/smug/uploads) sleep 60
+.EE
+.LP
+Make the album publicly viewable and share it.
+.IP
+.EX
+% echo public 1 >/n/smug/you/Vacation/Summer/settings
+% cat /n/smug/you/Vacation/Summer/url | mail friends
+.EE
+.SH SOURCE
+.B \*9/src/cmd/smugfs
+.SH SEE ALSO
+SmugMug, 
+.HR http://smugmug.com/
+.SH BUGS
+.PP
+If multiple categories or albums have the same name,
+only one will be accessible via the file system interface.
+Renaming the accessible one via 
+.IR mv (1)
+will resolve the problem.
+.PP
+Boolean values appear as
+.B true
+and
+.B false
+in settings files but must be changed using
+.B 1
+and
+.BR 0 .