Add a man page.

Remove the outdated README and get rid of that TODO item.
Update the gemspec with the description in the man page.

diff --git a/doc/README b/doc/README
deleted file mode 100644 (file)
index 4657422..0000000
--- a/doc/README
+++ /dev/null
@@ -1,73 +0,0 @@
-1. What is it?
-
-Mailshears prunes leftover mail-stuff.
-
-If you manage your mail system through a database, deleting a user or
-domain from the database probably doesn't remove the physical mail
-files and directory structure. Other stuff can be left behind
-too. Mailshears helps you clean up.
-
-
-2. Requirements
-
-Right now, mailshears is targeted at one type of setup:
-
-  * You're either using PostfixAdmin[1], or your users, domains, and
-    aliases are stored using the PostfixAdmin schema. This wouldn't be
-    too hard to change; on the other hand, it's a good schema.
-
-  * You use Dovecot[2] as your mailstore. This is an optional plugin, but
-    if you use something else for your physical mail storage,
-    mailshears can't help you. I would of course accept patches
-    implementing new plugins.
-
-    In fact, at the moment, the "Dovecot" plugin doesn't really do
-    anything Dovecot-specific. It just specializes the Mailstore to
-    use a <domain>/<localpart> filesystem layout.  It would make a lot
-    of sense to make that configurable, and just call it a
-    FilesystemMailstore.
-
-  * You maybe use Roundcube[3] webmail. Another optional
-    plugin. Specifically, roundcube-1.0.2 is supported at the moment.
-
-
-3. Installation
-
-You put it in a directory somewhere, and run bin/mailshears. To make
-it do anything, you'll need to create a config file. The default is
-stored in mailshears.example.conf.yml; I suggest you copy that to
-$HOME/.mailshears.conf.yml and edit it to fit your environment.
-
-You'll probably want to set up a cron job to run it every once in a
-while.
-
-
-4. How it works
-
-Mailshears gets a list of users and domains from your PostfixAdmin
-database. It then delegates to the plugins. A plugin represents
-something that you would like to clean up. For example, the Dovecot
-plugin represents the physical mail files/directories. The Roundcube
-plugin represents a Roundcube SQL database.
-
-Each plugin knows how to get a list of its own users and domains. If
-there's a user or domain in the plugin list that isn't in the
-PostfixAdmin list, then mailshears knows that you've deleted that user
-or domain from the database. So, it asks the plugin to clean up.
-
-By default, it doesn't actually /do/ anything. There's a variable in
-the config file that you'll need to set before mailshears will touch
-your junk.
-
-
-5. How to report bugs
-
-Email them to me at michael@orlitzky.com.
-
-
-
-[1] http://postfixadmin.sourceforge.net/
-
-[2] http://dovecot.org/
-
-[3] http://www.roundcube.net/

diff --git a/doc/TODO b/doc/TODO
index b7ea25759d037746ed0f918b89a1019fde4920f1..ce3024c5706a7252ea5cd7aa0f63e284db740b40 100644 (file)
--- a/doc/TODO
+++ b/doc/TODO
@@ -11,10 +11,6 @@
 
 * Add OpenDKIM support.
 
 
 * Add OpenDKIM support.
 

-* Write a man page.
-
-* Update the README.
-

 * Make a release.
 
 * Implement moving of domains.
 * Make a release.
 
 * Implement moving of domains.

diff --git a/doc/man1/mailshears.1 b/doc/man1/mailshears.1
new file mode 100644 (file)
index 0000000..de6ce68
--- /dev/null
+++ b/doc/man1/mailshears.1
@@ -0,0 +1,184 @@
+.TH mailshears 1
+
+.SH NAME
+mailshears \- mangle your mail garden
+.SH SYNOPSIS
+
+\fBmailshears\fR [ [\fBprune\fR] | [\fBrm\fR <\fItargets\fR>] | [\fBmv\fR <\fIsrc\fR> <\fIdst\fR>] ]
+
+.SH DESCRIPTION
+
+Managing a mail system with virtual users is annoying. The
+authoritative database of users is stored in one table, but every
+other piece of software keeps its own database of users.
+
+If you're using PostfixAdmin to manage your users, what happens when
+you delete a user? Chances are, nothing happens: mail directories are
+left behind, webmail preferences are saved, address books become
+orphaned. That's what mailshears was designed to fix. It cleans up
+after you remove a user or domain.
+
+Another stupidly difficult task is renaming a single email
+account. It's easy to move the user in one database, but then all of
+the remaining filesystem directories and databases need to be updated
+as well. Since these two tasks are related, mailshears does them both.
+
+It is assumed that you use the \fBPostfixAdmin schema\fI with
+\fBPostgreSQL\fR for your virtual users and domains. The rest of the
+functionality is provided by plugins. The following are supported at
+the moment:
+\#
+.IP \(bu 2
+Agendav (database)
+.IP \(bu
+DAViCal (datbase)
+.IP \(bu
+Dovecot (filesystem)
+.IP \(bu
+PostfixAdmin (database)
+.IP \(bu
+Roundcube (database)
+
+You are free to pick and choose the plugins that you need. The Dovecot
+plugin is a misnomer: as long as your mail is stored on disk in
+directories of the form \(dqexample.com/user\(dq, it should work for
+you.
+
+.SH MODES
+Mailshears has three modes, each of which takes different
+arguments. The default mode prunes leftover stuff.
+\#
+.IP \(bu 2
+\fBprune\fR
+
+The default \(dqprune\(dq mode removes leftovers from your mail
+system. The list of current users is collected from PostfixAdmin.  The
+other plugins are then queried to find any extra users/domains to
+remove.
+\#
+.IP \(bu
+\fBrm\fR
+
+The \(dqrm\(dq mode removes a list of users and/or domains called
+\fItargets\fR.
+\#
+.IP \(bu
+\fBmv\fR
+
+The \(dqmv\(dq mode renames the \fIsrc\fR user to \fIdst\fR. The
+source user and destination domains must exist. Domains may not be
+moved.
+
+.SH EXAMPLES
+
+Pruning leftover users and domains:
+
+.nf
+.I $ mailshears
+mailshears, 2015-11-08 17:01:47 -0500 (Plugin: PrunePlugin)
+-----------------------------------------------------------
+AgendavPrune - Removed user booger@example.com.
+DavicalPrune - Removed user booger@example.com (Principal ID: 2).
+DovecotPrune - Removed user booger@example.com (/tmp/mailshears-test/example.com/booger).
+DovecotPrune - Removed user jeremy@example.com (/tmp/mailshears-test/example.com/jeremy).
+RoundcubePrune - Removed user booger@example.com (User ID: 2).
+.fi
+
+Removing a specific user:
+
+.nf
+.I $ mailshears rm adam@example.net
+mailshears, 2015-11-08 17:04:42 -0500 (Plugin: RmPlugin)
+--------------------------------------------------------
+AgendavRm - Removed user adam@example.net.
+DavicalRm - User adam@example.net not found.
+DovecotRm - Removed user adam@example.net (/tmp/mailshears-test/example.net/adam).
+PostfixadminRm - Removed user adam@example.net.
+RoundcubeRm - Removed user adam@example.net (User ID: 3).
+.fi
+
+Removing a domain:
+
+.nf
+.I $ mailshears rm example.net
+mailshears, 2015-11-08 17:05:42 -0500 (Plugin: RmPlugin)
+--------------------------------------------------------
+AgendavRm - Removed domain example.net.
+DavicalRm - Domain example.net not found.
+DovecotRm - Removed domain example.net (/tmp/mailshears-test/example.net).
+PostfixadminRm - Removed domain example.net.
+RoundcubeRm - Removed domain example.net.
+.fi
+
+Renaming an existing user:
+
+.nf
+.I $ mailshears mv alice@example.com alice@example.net
+mailshears, 2015-11-08 17:06:29 -0500 (Plugin: MvPlugin)
+--------------------------------------------------------
+AgendavMv - Source user alice@example.com not found.
+DavicalMv - Moved user alice@example.com (Principal ID: 1) to alice@example.net (Principal ID: 1).
+DovecotMv - Moved user alice@example.com (/tmp/mailshears-test/example.com/alice) to alice@example.net (/tmp/mailshears-test/example.net/alice).
+PostfixadminMv - Moved user alice@example.com to alice@example.net.
+RoundcubeMv - Moved user alice@example.com (User ID: 1) to alice@example.net (User ID: 1).
+.fi
+
+.SH CONFIGURATION
+
+Mailshears is configured with a YAML file containing all of the
+database settings and plugin information. This file should be located
+at ~/.mailshears.conf.yml, in your home directory.
+
+The following two settings are global:
+\#
+.IP \(bu 2
+\fIi_mean_business\fR (default: false) If this is set to false, mailshears
+will output some \(dqwhat if\(dq information but won't actually
+(re)move anything.
+\#
+.IP \(bu
+\fIplugins\fR (default: ['postfixadmin'])
+A list of enabled plugins. Valid values are \(dqagendav\(dq,
+\(dqdavical\(dq, \(dqdovecot\(dq, \(dqpostfixadmin\(dq, and
+\(dqroundcube\(dq.
+.P
+The \(dqdovecot\(dq plugin supports the following:
+\#
+.IP \(bu 2
+\fIdovecot_mail_root\fR (default: /tmp/mailshears-test)
+
+The location of your mail store. The domain directories should be
+located one level beneath dovecot_mail_root.
+.P
+The database plugins all have the same configutation options:
+connections settings preceded by the plugin name. So in what follows,
+<plugin> would be replaced by \(dqagendav\(dq, \(dqdavical\(dq, or so
+on. Their meanings should be self-explanatory.
+\#
+.IP \(bu 2
+\fI<plugin>_dbhost\fR (default: localhost)
+\#
+.IP \(bu
+\fI<plugin>_dbport\fR (default: 5432)
+\#
+.IP \(bu
+\fI<plugin>_dbopts\fR (default: empty)
+\#
+.IP \(bu
+\fI<plugin>_dbtty\fR (default: empty)
+\#
+.IP \(bu
+\fI<plugin>_dbuser\fR (default: 'postgres')
+\#
+.IP \(bu
+\fI<plugin>_dbpass\fR (default: empty)
+\#
+.IP \(bu
+\fI<plugin>_dbname\fR (default: <plugin>)
+.P
+An example configuration file, mailshears.example.conf.yml, is shipped
+with mailshears.
+
+.SH BUGS
+
+Send bugs to michael@orlitzky.com.

diff --git a/mailshears.gemspec b/mailshears.gemspec
index acc46359e8c335923b950d6453db133d0213deff..6af744f0486d29ac836dec338591166f3445d705 100644 (file)
--- a/mailshears.gemspec
+++ b/mailshears.gemspec
@@ -7,9 +7,24 @@ Gem::Specification.new do |s|
   s.email             = ['michael@orlitzky.com']
   s.homepage          = 'http://michael.orlitzky.com/code/mailshears.php'
   s.summary           = 'Prune unused mail directories.'
   s.email             = ['michael@orlitzky.com']
   s.homepage          = 'http://michael.orlitzky.com/code/mailshears.php'
   s.summary           = 'Prune unused mail directories.'

-  s.description       = s.summary
-  s.license           = 'AGPL-3'
+  s.description       = <<-EOF
+    Managing a mail system with virtual users is annoying. The
+    authoritative database of users is stored in one table, but every
+    other piece of software keeps its own database of users.
+
+    If you're using PostfixAdmin to manage your users, what happens when
+    you delete a user? Chances are, nothing happens: mail directories are
+    left behind, webmail preferences are saved, address books become
+    orphaned. That's what mailshears was designed to fix. It cleans up
+    after you remove a user or domain.

 
 

+    Another stupidly difficult task is renaming a single email
+    account. It's easy to move the user in one database, but then all of
+    the remaining filesystem directories and databases need to be updated
+    as well. Since these two tasks are related, mailshears does them both.
+  EOF
+
+  s.license           = 'AGPL-3'

   s.required_rubygems_version = '>= 1.3.6'
 
   # If you have runtime dependencies, add them here
   s.required_rubygems_version = '>= 1.3.6'
 
   # If you have runtime dependencies, add them here