summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2009-05-08 12:48:00 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2009-05-08 21:02:44 (GMT)
commit30775f7ce1215423967c681ab9f3cf0a4704b51e (patch) (side-by-side diff)
tree55c74e44570a1d698fb00497a9965b8ec4e3a3e4
parentae42310eae46e763e207a2204d43dbadf20f8390 (diff)
downloadmailfromd-30775f7ce1215423967c681ab9f3cf0a4704b51e.tar.gz
mailfromd-30775f7ce1215423967c681ab9f3cf0a4704b51e.tar.bz2
Fix the docs
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--doc/gacopyz.texi6
-rw-r--r--doc/pies.texi59
-rw-r--r--doc/pmult.texi30
3 files changed, 50 insertions, 45 deletions
diff --git a/doc/gacopyz.texi b/doc/gacopyz.texi
index 7354db6..88348cc 100644
--- a/doc/gacopyz.texi
+++ b/doc/gacopyz.texi
@@ -1,4 +1,4 @@
-@c Copyright (C) 2005, 2006 Sergey Poznyakoff
+@c Copyright (C) 2005, 2006, 2009 Sergey Poznyakoff
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.2 or
@c any later version published by the Free Software Foundation; with no
@@ -35,11 +35,11 @@ new and more flexible @acronym{API}. The old @acronym{API} is
supported for compatibility with @command{libmilter}.
The library name comes from the song @samp{Rozprawa o robokach} by
-@uref{http://gray.gnu.org.ua/grzeskowiak.html, Kazimierz Grzeskowiak}.
+@uref{http://grzeskowiak.art.pl, Kazimierz Grzeskowiak}.
The phrase @samp{A to nie je mysa, ino gacopyz} exactly describes what
the library is: @samp{That is no libmilter, but gacopyz}.
- Future versions of this documentation will include the detailed
+ Future versions of this documentation will include a detailed
description of the library.
diff --git a/doc/pies.texi b/doc/pies.texi
index 599e630..1d9df83 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -1,5 +1,5 @@
@c This file is part of the Mailfromd manual.
-@c Copyright (C) 2008 Sergey Poznyakoff
+@c Copyright (C) 2008, 2009 Sergey Poznyakoff
@c See file mailfromd.texi for copying conditions.
@c *******************************************************************
@cindex component, pies
@@ -7,9 +7,9 @@
@samp{Program Invocation and Execution Supervisor}. This utility
starts and controls execution of external programs, called
@dfn{components}. Each component is a stand-alone program, which is
-executed in foreground. Upon startup, @command{pies} reads the list
+executed in the foreground. Upon startup, @command{pies} reads the list
of components from its configuration file, starts them, and remains in
-background, controlling their execution. When any of the components
+the background, controlling their execution. When any of the components
terminates, @command{pies} restarts it. Its configuration allows to
specify actions other than simple restart, depending on the exit code
of the component.
@@ -48,7 +48,7 @@ components.
startup. Instead, @command{pies} opens a socket for each of them and
listens for connections on these sockets. When a connection arrives,
it decides what component the socket corresponds to, and invokes this
-component to service that connection. In this case, the connection is
+component to handle that connection. In this case, the connection is
bound to component's @samp{stdin} and @samp{stdout} streams. The
@samp{stderr} stream can be redirected to a file or to syslog, as
described above. This mode of operation is similar to that of
@@ -57,7 +57,7 @@ described above. This mode of operation is similar to that of
@anchor{meta1-style}
@cindex meta1-style components
@cindex smtps
- Third type of components, supported by @command{pies} are
+ The third type of components, supported by @command{pies} are
@dfn{meta1-style} components. As the name suggests this type is
designed expressly as a support for MeTA1 components, namely
@command{smtps}. This type can be regarded as a mixture of the above
@@ -78,8 +78,8 @@ starts the component, without waiting for an actual connection.
simultaneously.
Components are started in the order of their appearance in the
-configuration file and terminated in reverse order. When starting or
-stopping component dependencies, the same order is preserved.
+configuration file and terminated in the reverse order. When starting or
+stopping component dependencies, the same ordering is preserved.
This order is reversed for files included by @code{include-meta1}
statement (@pxref{include-meta1}).
@@ -136,6 +136,8 @@ component @var{tag} @{
The component is identified by its @dfn{tag}, which is given as
argument to the @code{component} keyword.
+The following statements are allowed within the @code{component} block:
+
@deffn {Pies Conf} mode @var{mode}
Declare the type (style) of the component. Accepted values for
@var{mode} are:
@@ -230,8 +232,8 @@ component tags.
@node Component Privileges
@subsection Component Privileges
@cindex privileges, pies
- Following statements control the privileges with which the component
-is executed.
+ Following statements control the privileges the component
+is executed with.
@deffn {Pies Conf} user @var{user-name}
Start component with the UID and GID of this user.
@@ -242,8 +244,8 @@ Retain supplementary groups, specified in @var{group-list}.
@end deffn
@deffn {Pies Conf} allgroups @var{bool}
-Retain all supplementary groups of which user, given with
-@command{user} statement, is a member. This is the default for
+Retain all supplementary groups of which the user (as given with
+@command{user} statement) is a member. This is the default for
components specified in @file{meta1.conf} file (@pxref{include-meta1}).
@end deffn
@@ -406,9 +408,10 @@ are:
@deffn {Pies Conf} action @samp{disable | restart}
If @samp{restart} is given, restart the component. This is the
-default. Otherwise, mark the component and as disabled. Component
-dependents are stopped and marked as disabled as well. Disabled
-components are never started, unless requested by the administrator.
+default. Otherwise, mark the component as disabled. Component
+dependents are stopped and marked as disabled as well. Once disabled,
+the components are never restarted, unless their restart is requested
+by the administrator.
@end deffn
@deffn {Pies Conf} notify @var{email-string}
@@ -460,13 +463,13 @@ that their @var{codes} do not intersect.
Such statements can also be used outside of @code{component} block.
In this case, they supply global actions, i.e. actions applicable to
-all components. The @code{return-code} statements appearing within a
+all components. Any @code{return-code} statements appearing within a
@code{component} block override the global ones.
@node Output Redirectors
@subsection Output Redirectors
@cindex repeater
- Output redirectors allow to redirect standard error and/or standard
+ Output redirectors allow to redirect the standard error and/or standard
output of a component to a file or @command{syslog} facility.
@deffn {Pies Conf} stderr @var{type} @var{channel}
@@ -478,7 +481,7 @@ The type of redirection is specified by @var{type} argument:
@table @asis
@item file
-Redirect to file. In this case @var{channel} gives the full name of
+Redirect to the file. In this case @var{channel} gives the full name of
the file. For example:
@smallexample
@@ -529,7 +532,7 @@ component (@pxref{Actions Before Startup, chdir}).
@item local://@var{file}[;@var{args}]
@itemx file://@var{file}[;@var{args}]
@itemx unix://@var{file}[;@var{args}]
-Listen on a @acronym{UNIX} socket file @var{file}, which may be either
+Listen on the @acronym{UNIX} socket file @var{file}, which may be either
absolute or relative file name, as described above. Optional
arguments @var{args} control ownership and file mode of @var{file}. They
are a list of assignments, separated by semicolons. The following
@@ -689,7 +692,7 @@ component @var{tag} @{
@node include-meta1
@section Using MeTA1 Configuration File
@cindex /etc/meta1/meta1.conf
- @command{Pies} is able to take list of components from MeTA1
+ @command{Pies} is able to take a list of components from MeTA1
configuration file:
@deffn {Pies Conf} include-meta1 @var{file}
@@ -705,8 +708,8 @@ Thus, you can use @command{pies} instead of the default MeTA1 program
manager @command{mcp}.
To ensure compatibility with MeTA1, the components read from MeTA1
-configuration are started in reverse order (i.e. from last to first),
-and stopped in order of their appearance in @var{file}. Of course,
+configuration are started in the reverse order (i.e. from last to first),
+and stopped in the order of their appearance in @var{file}. Of course,
this does not affect normal @command{pies} components.
The following @command{pies} statements are silently applied to
@@ -800,7 +803,7 @@ Set file name of the statistics output file. Default is
@end deffn
Normally, @command{pies} must be run with root privileges. If,
-however, you've found an implementation for it, that requires another
+however, you found such an implementation for it, that requires another
privileges, you may change them using the following three statements:
@command{pies} process.
@@ -820,7 +823,7 @@ Retain all supplementary groups of which user, given with
@node Pies Debugging
@section Pies Debugging
The amount of debugging information produced by @command{pies} is configured
-using two configuration statements. First of all, the standard
+by the following two configuration statements. First of all, the standard
@code{debug} block statement controls debugging of the underlying GNU
Mailutils libraries (@pxref{Debug Statement, Mailutils Configuration
File,, mailutils, GNU Mailutils Manual}). Secondly, the @code{debug}
@@ -840,7 +843,7 @@ Log all basic actions: starting and stopping of components, received incoming
limits. Log pre-startup actions (@pxref{Actions Before Startup}).
@item trace2
-Log setting particular limits. Log recomputing alarms.
+Log setting particular limits. Log the recomputed alarms.
@item trace4
Dump execution environments
@@ -868,7 +871,7 @@ configuration files.
@subsection Simplest Case: Using Pies to Run Pmult
The example below runs @command{pmult} (@pxref{pmult}) utility with
the privileges of @samp{meta1} user. Both standard error and standard
-output are redirected to syslog facility @samp{mail}, priorities
+output are redirected to the syslog facility @samp{mail}, priorities
@samp{err} and @samp{info}, correspondingly.
@smallexample
@@ -1025,8 +1028,8 @@ $ pies --stop
@cindex --dump-depmap option, pies
Two options are provided for verifying inter-component
dependencies. The @option{--dump-depmap} option prints on the
-standard output the @dfn{dependency map}. This map is a square table
-where rows represent dependents and columns represent prerequisites.
+standard output the @dfn{dependency map}. This map is a square matrix
+with rows representing dependents and columns representing prerequisites.
An @samp{X} sign is placed on each crossing which corresponds to the
actual dependency. For example:
@@ -1068,6 +1071,8 @@ smtps: smar qmgr
@node Pies Invocation
@section Pies Invocation
+This section summarizes @command{pies} command line options.
+
@table @option
@item --force
Force startup even if another instance may be running.
diff --git a/doc/pmult.texi b/doc/pmult.texi
index 93abec7..42799e1 100644
--- a/doc/pmult.texi
+++ b/doc/pmult.texi
@@ -1,5 +1,5 @@
@c This file is part of the Mailfromd manual.
-@c Copyright (C) 2008 Sergey Poznyakoff
+@c Copyright (C) 2008, 2009 Sergey Poznyakoff
@c See file mailfromd.texi for copying conditions.
@c *******************************************************************
@cindex @command{pmult}, described
@@ -109,7 +109,7 @@ care to invoke right Milter handlers within the single @samp{data}
Pmilter state. Therefore in the discussion that follows we will refer
to Mailfromd handlers, rather than to Pmilter stages.
- Most important standard Milter macros are always provided by
+ The most important standard Milter macros are always provided by
@command{pmult} itself. These are:
@table @asis
@@ -243,8 +243,7 @@ MeTA1 transaction id.
Message-Id of the message.
@item c
-The hop count. Basically, this is a count of the number of
-@samp{Received:} headers.
+The hop count. Basically, this is the number of @samp{Received:} headers.
@end table
Notice the following limitations:
@@ -255,8 +254,9 @@ Notice the following limitations:
@item All @samp{tls_*} macros are valid only after a @code{STARTTLS}
command.
@item The number of MeTA1 macros per stage is limited by
-@code{PM_MAX_MACROS} define in @file{include/sm/pmfdef.h}. In MeTA1
-versions up to and including 1.0.PreAlpha27.0, this number is 8.
+@code{PM_MAX_MACROS} define in @file{include/sm/pmfdef.h}. In MeTA1
+versions up to and including 1.0.PreAlpha28.0, this number is 8. If
+you need more macros, inrease this number and recompile MeTA1.
@end enumerate
@end deffn
@@ -369,7 +369,7 @@ See also the following subsection.
@subsection Debugging Pmult
If needed, @command{pmult} can be instructed to provide additional
debugging information. The amount of this information is configured
-using three configuration statements. First of all, the standard
+by three configuration statements. First of all, the standard
@code{debug} block statement controls debugging of the underlying GNU
Mailutils libraries (@pxref{Debug Statement, Mailutils Configuration
File,, mailutils, GNU Mailutils Manual}). Secondly, the @code{debug}
@@ -377,7 +377,7 @@ statement controls debugging output of the @command{pmult} utility
itself. The @code{pmilter-debug} statement controls debugging output
of the underlying MeTA1 libraries, and, finally, the @code{log-level}
statement, described in the previous subsection, defines debugging
-level for Milter library (@code{libgacopyz}).
+level for the Milter library (@code{libgacopyz}).
@deffn {Pmult Conf} debug @var{spec}
Set debugging level for the @command{pmult} code. @xref{Debug
@@ -419,7 +419,7 @@ and 100 (maximum debugging).
Pmilter debugging information is printed on the standard error. Use
@command{pies} @code{stderr} statement to capture this stream and
-redirect it to syslog or file (@pxref{Output Redirectors}).
+redirect it to the syslog or file (@pxref{Output Redirectors}).
@end deffn
@node pmult example
@@ -427,11 +427,11 @@ redirect it to syslog or file (@pxref{Output Redirectors}).
The following is an example of a working @command{pmult}
configuration. The multiplexer listens on localhost, port
@samp{3333}. It prints its diagnostics using syslog facility
-@code{local2}. A single Mailfromd client is declared. This client
+@code{local2}. A single Mailfromd client is declared, which
listens on @acronym{UNIX} socket
-@file{/usr/local/var/mailfromd/mailfrom}. Log verbosity level
-for this client is set to @samp{info}, @samp{warn}, @samp{err} and
-@samp{fatal}.
+@file{/usr/local/var/mailfromd/mailfrom}. The log verbosity level
+for this client is set to @samp{info} and higher, i.e.: @samp{info},
+@samp{warn}, @samp{err} and @samp{fatal}.
@smallexample
listen inet://127.0.0.1:3333;
@@ -481,13 +481,13 @@ Disable signal handling in the main thread. This is for debugging
purposes.
@item --syslog
-Log to syslog. This is the default. @xref{Logging Statement, Logging
+Log to the syslog. This is the default. @xref{Logging Statement, Logging
Statement, , mailutils, GNU Mailutils Manual}, for information on how
to configure syslog logging.
@item -s
@itemx --stderr
-Log to standard error stream.
+Log to the standard error stream.
@item --url=@var{url}
Listen on the given @var{url}. This overrides the @code{url}

Return to:

Send suggestions and report system problems to the System administrator.