diff --git a/mkapachepw.1 b/mkapachepw.1
index 6671a3e..62d1977 100644
--- a/mkapachepw.1
+++ b/mkapachepw.1
@@ -121,12 +121,23 @@
 arbiters of what actually makes it into the output group and user
 files, regardless of other conditions that may be in effect.
 
+There is another reason why you might explicitly enumerate a user to
+be included in the output user file.  By default, \fCmkapachepw\fP
+does
+.B not
+include users in the output that cannot login - i.e. Users whose
+hashed password is \fC*\fP.  You can override this by naming
+such a user explicitly as an argument to the \fC-U\fP option.
 
 By combining these options with the starting GID and UID options
 described below, you can achieve a very fine grain of control of just
 which groups and users actually end up in a production Apache access
 control system.
 
+You can repeat these options as many times as you wish on the command
+line.  The argument to each of these options merely needs to be one or
+more enmeration specifications as described above.
+
 
 .TP
 .B -g number
@@ -171,22 +182,92 @@
 
 
 .TP
-.B -I
+.B -I name of group file to include
 
 .TP
-.B -i
+.B -i name of user file to include
+
+These options provide a way to include additional group and user files when producing
+the final Apache access control files.   These files must be in standard Apache
+format for group and user files respectively.  These options can be
+repeated on the command line to include multiple files:
+
+.ft C \" Courier
+.nf
+    mkapachepw.py -I engineering-groups.inc -I marketing-groups.inc -i engineering-users.inc -i ...
+.fi
+.ft \" revert
+
+
+\fCmkapachepw\fP combines the contents of these files with the content of
+the OS group and user databases (unless the \fC-s\fP option is selected) to
+create a single, in-memory list of groups and users.  The program then
+"filters" these against the starting GID and UID specification as well
+as any specific enumerated inclusions or exclusions to produce a final
+pair of group and user files for use by Apache.
+
+Any files you request to be included will be processed
+.B after
+\fCmkapachepw\fP reads the OS group and user databases.  This means
+that, if one of your included files has a group/user name that is 
+the same as one of the system groups/user, you will get a "collision".
+Unless you prohibit collisions (see the \fC-c\fP option below), this means
+the entry from the included file will supercede the OS entry.  Say, for
+example, you have user named \fCmary\fP both in your OS and in one
+of your included files.  Then, the password specified for \fCmary\fP in the
+.B included file
+will end up in the final Apache user access control file, not the
+password found in the OS user database.
+
+Comments and blank lines found in any included file are removed.  After
+\fCmkapachepw\fP has combined all the entries found in the OS databases
+and all the included files, and decided which ones to actually emit
+into the output files, it sorts them into alphabetic order.
+
+It's important to realize that \fCmkapachepw\fP does no "sanity"
+checking on included files.  It presumes them to be in correct Apache
+format for group and user access control files respectively.  If you
+include a file that is not in this format, the program will probably
+blow up spectacularly, and write garbage output files, or nothing at
+all.
 
 .TP
 .B -c
+inhibit collisions
+
+Ordinarily, if an included file has the same group or user name as one
+found in the underlying OS databases, \fCmkapachepw\fP merely warns you
+of this "collision", accepts the values found in the included file in
+place of the system values, and continues.  If you select this option,
+the program will strictly prohibit collisions and exit immediately when
+it detects one.
 
 .TP
 .B -q
+quiet mode
+
+This inhibits the display of collision warnings.
 
 .TP
-.B -O
+.B -O group filename
+
+Names the file to which group information will be written.  (default:
+\fC./.htgroups\fP).  The file is produced with read permission for the
+owner only.  Be sure to change the owner/group for this file as
+appropriate for your Apache installation, when actually installing it.
+
+If you specify \fC-\fP here, group output is written to stdout.
 
 .TP
-.B -o
+.B -o user filename
+
+Names the file to which user information will be written.  (default:
+\fC./.htusers\fP).  The file is produced with read permission for the
+owner only.  Be sure to change the owner/group for this file as
+appropriate for your Apache installation, when actually installing it.
+
+
+If you specify \fC-\fP here, group output is written to stdout.
 
 .TP
 .B -h
@@ -265,7 +346,7 @@
 .ft \" revert
 
 .SH DOCUMENT REVISION INFORMATION
-$Id: mkapachepw.1,v 1.103 2005/04/12 09:22:30 toor Exp $
+$Id: mkapachepw.1,v 1.104 2005/04/12 09:49:08 toor Exp $