Document directory setup statements.

See commits f338532e, dd9d9c12, and af538cc2.

1 files changed, 187 insertions, 4 deletions

diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 1f76e71..6f769d1 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -103,6 +103,7 @@ How to Configure @command{wydawca}.
 * syslog::
 * sql::
 * dictionaries::
+* directory setup::
 * archivation::
 * spool::
 * verification::
@@ -127,12 +128,20 @@ SQL Dictionary
 * project-owner-sql::
 * project-uploader-sql::
 
-Mail Notification
+Notification Mechanism
+
+* modules::
+* event notification::
+* mod_mailutils:: Mail Notification
+* mod_logstat:: Notification to syslog
+
+@command{mod_mailutils}-- Mail Notification
 
 * mailer::                      
 * templates::                   
-* statreports::                 
-* event notification::          
+* statreports::
+* mail-config:: @code{module-config} for @command{mod_mailutils}
+* mod_mailutils example:: Example of @command{mod_mailutils} configuration
 
 @end detailmenu
 @end menu
@@ -523,6 +532,7 @@ directives any time by running @command{wydawca --config-help}.
 * syslog::
 * sql::
 * dictionaries::
+* directory setup::
 * archivation::
 * spool::
 * verification::
@@ -1716,6 +1726,54 @@ dictionary project-owner @{
 As of version @value{VERSION} this dictionary is not yet
 implemented.
 
+@node directory setup
+@section Directory Setup
+
+@command{Wydawca} operates on three kinds of directories: spool source
+directories (@pxref{spool, source}), destination directories
+(@pxref{spool, destination}) and archive directories
+(@pxref{archivation}). By default, @command{wydawca} assumes that all
+directories specified in its configuration file already exist and have
+proper ownership and modes. It will abort if it is not so.
+
+You can configure @command{wydawca} to create these directories as
+needed, and to set up their ownership and modes automatically.
+
+@deffn {Config} create-directories bool
+If set to @samp{yes}, this statement instructs @command{wydawca} to
+create any missing directories.
+@end deffn
+
+@deffn {Config} directory-mode mode
+Specifies the mode for created directories (in octal).  If the
+directory already exists, its mode will be checked and if necessary
+changed to @var{mode}.
+
+This statement is overridden by per-directory statements:
+@code{source-mode} and @code{destination-mode} statements in
+@code{spool} block (@pxref{spool}) and @code{directory-mode} statement
+in @code{archive} block (@pxref{archivation}).
+@end deffn
+
+@deffn {Config} directory-owner uid gid
+Configures owner user and group IDs for source, destination and
+archive directories.
+
+The @var{uid} argument is either a numeric UID prefixed with a plus
+sign, or a symbolic user name, which will be converted to the numeric
+UID using the system user database.  If a number without the @samp{+}
+prefix is supplied, it will first be looked in the password database
+as the user name, and, if no such user is found, it will be used as
+the numeric UID.
+
+The same holds for the @var{gid} argument.
+
+This statement is overridden by per-directory statements:
+@code{source-owner} and @code{destination-owner} statements in
+@code{spool} block (@pxref{spool}) and @code{directory-owner} statement
+in @code{archive} block (@pxref{archivation}).
+@end deffn
+
 @node archivation
 @section Archivation
 @cindex archivation, defined
@@ -1739,8 +1797,17 @@ where it affects only the given spool.
 @deffn {Config} archive type
 @smallexample
 archive @var{type} @{
+  # Name of archive file or directory
   name @var{file-or-dir};
+
+  # Define backup type
   backup @var{type};
+
+  # mode for the archive directory
+  directory-mode @var{mode};
+
+  # owner user and group for the archive directory
+  directory-owner @var{uid} @var{gid};
 @}
 @end smallexample
 
@@ -1858,6 +1925,27 @@ Always make simple backups.
   If no backup method is given, @samp{existing} is assumed
 @end deffn
 
+@deffn {Config: archive} directory-mode mode
+Sets directory mode for creating the directory (octal).  If the
+directory already exists, its mode will be checked and if necessary
+changed to @var{mode}.
+
+This statement overrides the global @code{directory-mode} statement
+(@pxref{directory setup}).
+@end deffn
+
+@deffn {Config} directory-owner uid gid
+Configures owner user and group IDs for created archive directories.
+If the archive directory already exists, its ownership will be checked
+and if necessary reverted to @var{uid}:@var{gid}.
+
+@xref{directory setup, directory-owner}, for a discussion of the
+syntax for @var{uid} and @var{gid}.
+
+This statement overrides the global @code{directory-mode} statement
+(@pxref{directory setup}).
+@end deffn
+
 @cindex implicit signature archivation
 @cindex signature files, archivation
   Signature files (i.e. the ones ending with @samp{.sig}) are usually
@@ -1899,7 +1987,11 @@ spool @var{tag} @{
   alias (@var{aliases});
   inotify @var{bool};
   source @var{dir};
+  source-mode @var{mode};
+  source-owner @var{uid} @var{gid};
   destination @var{dir};
+  destination-mode @var{mode};
+  destination-owner @var{uid} @var{gid};
   file-sweep-time @var{interval};
   dictionary @{ @dots{} @}
   archive @{ @dots{} @}
@@ -1933,6 +2025,27 @@ may be used as @samp{$@{url@}} meta-variable in mail notifications.
 Specifies the location of the source directory.
 @end deffn
 
+@deffn {Config: archive} source-mode mode
+Sets directory mode for creating the source directory (octal).  If the
+directory already exists, its mode will be checked and if necessary
+changed to @var{mode}.
+
+This statement overrides the global @code{directory-mode} statement
+(@pxref{directory setup}).
+@end deffn
+
+@deffn {Config} source-owner uid gid
+Configures owner user and group IDs for the source directory.
+If the directory already exists, its ownership will be checked
+and if necessary reverted to @var{uid}:@var{gid}.
+
+@xref{directory setup, directory-owner}, for a discussion of the
+syntax for @var{uid} and @var{gid}.
+
+This statement overrides the global @code{directory-mode} statement
+(@pxref{directory setup}).
+@end deffn
+
 @deffn {Config: spool} destination dir
 Specifies the type and location of the destination directory. The
 @var{dir} argument must be either an absolute name of a directory on
@@ -1954,6 +2067,30 @@ are useful mainly for diagnostic purposes.
 @end table
 @end deffn
 
+The following two statements apply only if the destination is a local
+directory (@samp{file://} or @samp{dir://} URL scheme):
+
+@deffn {Config: archive} destination-mode mode
+Sets directory mode for creating the destination directory (octal).
+If the directory already exists, its mode will be checked and if
+necessary changed to @var{mode}.
+
+This statement overrides the global @code{directory-mode} statement
+(@pxref{directory setup}).
+@end deffn
+
+@deffn {Config} destination-owner uid gid
+Configures owner user and group IDs for the destination directory.
+If the directory already exists, its ownership will be checked
+and if necessary reverted to @var{uid}:@var{gid}.
+
+@xref{directory setup, directory-owner}, for a discussion of the
+syntax for @var{uid} and @var{gid}.
+
+This statement overrides the global @code{directory-mode} statement
+(@pxref{directory setup}).
+@end deffn
+