Switch to deep structure.

2 files changed, 319 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..af4c4f9
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1 @@
+dist_man_MANS=dircond.1
diff --git a/doc/dircond.1 b/doc/dircond.1
new file mode 100644
index 0000000..7055582
--- /dev/null
+++ b/doc/dircond.1
@@ -0,0 +1,318 @@
+.\" dircond - directory content watcher daemon -*- nroff -*-
+.\" Copyright (C) 2012, 2013 Sergey Poznyakoff
+.\"
+.\" Dircond 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 (at your
+.\" option) any later version.
+.\"
+.\" Dircond is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with dircond. If not, see <http://www.gnu.org/licenses/>.
+.TH DIRCOND 1 "March 8, 2013" "DIRCOND" "Dircond User Reference"
+.SH NAME
+dircond \- directory content watcher
+.SH SYNOPSIS
+\fBdircond\fR [\fB\-dft\fR] [\fB\-F\fR \fIFACILITY\fR] [\fB\-L\fR \fITAG\fR]\
+ [\fB\-P\fR \fIFILE\fR]\
+ [\fB\-u\fR \fIUSER\fR]\
+ [\fICONFIG\fR]
+
+.B dircond -h
+
+.B dircond -V
+.SH DESCRIPTION
+.B Dircond
+monitors a set of directories on the file system and reacts when
+a file system event occurs in any of them.  Directories and events
+to monitor are specified in the configuration file.  When an event
+occurs the utility reacts by invoking an external command configured
+for that event.
+.PP
+The following events can be monitored by the program:
+.TP
+.B access
+A file was accessed.
+.TP
+.B attrib
+A file's metadata changed.
+.TP
+.B close_write
+A writable file was closed.
+.TP
+.B close_nowrite
+An unwritable file closed.
+.TP
+.B create
+A file was created.
+.TP
+.B delete
+A file was deleted.
+.TP
+.B modify
+A file was modified.
+.TP
+.B moved_from
+A file was moved into a monitored directory.
+.TP
+.B moved_to
+A file was moved out from a monitored directory.
+.TP
+.B open
+A file was opened.
+.PP
+When an event has been detected,
+.B dircond
+invokes the handler configured for it.  The handler is invoked in the
+directory where the event occured.  Additional information about the
+event is passed in the following environment variables:
+.TP
+.B DIRCOND_EVENT
+Event symbolic name (see the event table above). 
+.TP
+.B DIRCOND_EVENT_CODE
+Event code as obtained from
+.BR inotify (8).
+.TP
+.B DIRCOND_FILE
+The name of the affected file.
+.PP
+Apart from these variables, the
+handler environment is inherited from the calling process. If you need
+to restrict the environment, start
+.B dircond
+via
+.BR env (1).
+.SH OPTIONS
+.TP
+.B \-d
+Increase debug verbosity level.
+.TP
+.B \-f
+Run in the foreground.
+.TP
+\fB\-F\fR \fIFACILITY\fR
+Log under this syslog facility.  Allowed values for \fIFACILITY\fR are
+a decimal number or any of the following symbolic names:
+.BR auth ,
+.BR authpriv ,
+.BR cron ,
+.BR daemon ,
+.BR ftp ,
+.BR local0 " through " local7 ,
+.BR lpr ,
+.BR mail ,
+.BR news ,
+.BR user ,
+and
+.BR uucp .
+
+The option \fB\-F 0\fR directs logging to the standard error.
+.TP
+\fB\-L\fR \fITAG\fR
+Log with this syslog tag.
+.TP
+\fB\-P\fR \fIFILE\fR
+Write PID to \fIFILE\fR.
+.TP
+\fB\-t\fR
+Check configuration file for errors and exit.
+.TP
+\fB\-u\fR \fIUSER\fR
+Run as this \fIUSER\fR.
+.TP
+\fB\-h\fR
+Output a terse help summary and exit.
+.TP
+\fB\-V\fR
+Print program version and copyright information.
+.SH CONFIGURATION
+The default configuration file is
+.BR /etc/dircond.conf .
+If a file name is supplied as an argument to the program, that file
+will be read instead.
+.PP
+The configuration file has the traditional line-oriented format.  Very
+long lines can be split into several physical lines by ending each of
+them with a backslash immediately followed by a newline character.
+.PP
+Comments are introduced with a sharp sign and extend to the end of
+logical line.
+.PP
+Empty lines are ignored.
+.SS Global settings
+.TP
+\fBforeground\fR [\fBon\fR|\fBoff\fR]
+Remain in foreground (if \fBon\fR or no argument given), or detach
+from the controlling terminal and become a daemon (if \fBoff\fR).
+The latter is the default.  See also the \fB\-f\fR option.
+.TP
+\fBdebug\fR \fIN\fR
+Set debugging level.  See also the \fB\-d\fR option.
+.TP
+\fBpidfile\fR \fIFILE\fR
+Store PID of the started process in \fIFILE\fR.  See also the
+\fB\-P\fR option.
+.TP
+\fBuser\fR \fINAME\fR
+Run as user \fINAME\fR.  See also the \fB\-u\fR option.
+.SS Logging
+The \fBsyslog\fR statement configures where the log output goes.  By
+default, the program logs to standard error until it finishes parsing
+the configuration file and processing command line options.  From then
+on it begins logging to syslog with the facility \fBdaemon\fR.  The
+syslog settings can be altered using this statement.
+.TP
+.B syslog off
+Disable syslog output, log everything to standard error instead.  This
+setting has effect only when running in the foreground.
+.TP
+\fBsyslog facility\fR \fIFNAME\fR
+Log to syslog facility \fIFNAME\fR.  The latter can be either 
+a decimal number or any of the following symbolic names:
+.BR auth ,
+.BR authpriv ,
+.BR cron ,
+.BR daemon ,
+.BR ftp ,
+.BR local0 " through " local7 ,
+.BR lpr ,
+.BR mail ,
+.BR news ,
+.BR user ,
+and
+.BR uucp .
+.TP
+\fBsyslog tag\fR \fISTRING\fR
+Log with the given syslog tag.
+.SS Handler options
+Handler options affect all event handlers defined in the \fBonevent\fR
+statements appearing below them.
+.TP 
+\fBoption capture\fR \fIstream\fR [\fIenable\fR]
+Capture the output stream of a handler.  The \fIstream\fR parameter
+specifies which stream to capture.  Its possible values are:
+\fBstdout\fR for the standard output, \fBstderr\fR for the standard
+error, or \fBboth\fR for both streams.  Optional \fIenable\fR
+parameter can be \fBon\fR to enable capturing and \fBoff\fR to disable
+it.
+
+When logging to syslog, the data read from the captured
+.B stdout
+will be logged with the priority
+.BR LOG_INFO ,
+and
+.B stderr
+will be logged with the priority
+.BR LOG_ERROR .
+.TP
+\fBoption wait\fR
+Wait for the handler to terminate before handling subsequent events.
+This is the default.
+.TP
+\fBoption nowait\fR
+Do not wait for the handler to terminate.  Start it in the background
+and continue processing requests.
+.TP
+\fBoption timeout\fR \fIN\fR
+Sets timeout in seconds for handler runtime.  The default value is 5
+seconds.  Note, that the timeout setting affects both \fBwait\fR and
+\fBnowait\fR handlers, i.e. any handler that runs longer
+than \fIN\fR seconds will be terminated by
+.B SIGKILL.
+.SS Event handling
+.TP
+\fBevent\fR \fINAME\fR \fIEVENT-ID\fR [\fIEVENT-ID\fR...]
+Add listed events to the event set \fINAME\fR, creating it if it does
+not exist.  Each \fIEVENT-ID\fR is either a predefined event name (see
+the \fBDESCRIPTION\fR section) or a \fINAME\fR of an event 
+set defined in a previous
+.B event
+statement.
+.TP
+\fBpath\fR \fINAME\fR \fIDIR\fR [\fBrecursive\fR [\fIN\fR]]
+Add directory \fIDIR\fR to the pathset \fINAME\fR.  If \fBrecursive\fR
+is specified, all directories below \fIDIR\fR are also added to the
+pathset.  If \fBrecursive\fR is followed by a decimal number \fIN\fR,
+recursive inclusion is limited to directories located no deeper than
+\fIN\fR levels of nesting.
+.TP
+\fBonevent\fR \fIEVENT-ID\fR \fBin\fR \fIPATH-NAME\fR \fBrun\fR \fICOMMAND\fR\
+ [\fBas\fR \fIUSER\fR]
+Configures the handler for events occurring in the given pathset.
+\fICOMMAND\fR is the full pathname of an external program.  This
+program will be started when one of the events from \fIEVENT-ID\fR
+occur for any file in directories comprising the pathset \fIPATH-NAME\fR.
+If the optional \fBas\fR \fIUSER\fR clause is supplied, the program
+will be run with the UID and (main and supplementary) GIDs of \fIUSER\fR.
+The latter must be either a valid user name or a numeric UID of an
+existing user.
+.SH EXAMPLE
+.sp
+.nf
+.in +2
+# Store the PID of the master process in this file:
+pidfile /var/run/dircond.pid
+
+# Log using syslog facility \fBlocal0\fR.
+syslog facility local0
+
+# Define event set \fBupdate\fR to match any modifications
+# of file contents.
+event update modify close_write moved_to
+
+# Define event set \fBremove\fR to cover removal of a file
+# from the watched directory.
+event remove delete moved_from
+
+# Add \fB/etc\fR and its subdirectories to pathset \fBconfigs\fR.
+path configs /etc recursive
+
+# Don't allow event handler to run longer than 10 seconds.
+option timeout 10
+# Capture both standard output and error and divert them
+# to the log file.
+option capture both
+
+# If any file gets updated in \fB/etc\fR or any of its
+# subdirectories, call the program \fB/usr/bin/confchange\fR.
+onevent update in configs run /usr/bin/confchange as daemon
+
+# Another handler, for removals in the configuration directory.
+onevent delete in configs run /usr/bin/confdel
+.in
+.fi
+.SH "EXIT CODE"
+.IP 0
+Successful termination.
+.IP 1
+Command line usage error.
+.IP 2
+Another error occurred.
+.SH "SEE ALSO"
+.BR inotify (8).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+dircond@gnu.org.ua>.
+.SH COPYRIGHT
+Copyright \(co 2012, 2013 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+