Fix the docs

1 files changed, 32 insertions, 27 deletions

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.