Update the docs.

1 files changed, 97 insertions, 6 deletions

diff --git a/doc/beam-module.5in b/doc/beam-module.5in
index 99e7a63..f65ce52 100644
--- a/doc/beam-module.5in
+++ b/doc/beam-module.5in
@@ -14,7 +14,7 @@
 .\" You should have received a copy of the GNU General Public License
 .\" along with BEAM.  If not, see <http://www.gnu.org/licenses/>.
 .\"
-.TH BEAM-MODULE 5 "July 14, 2012" "BEAM" "BEAM Programmer Reference"
+.TH BEAM-MODULE 5 "July 15, 2012" "BEAM" "BEAM Programmer Reference"
 .SH NAME
 beam-module \- format of 
 .BR beam (1)
@@ -31,13 +31,13 @@ and restore from such backups.  However, there are special kinds of
 data that cannot be reliably backed up using this method.  An example
 of these are SQL databases.  Simply archiving the database files while
 the database engine is running is not likely to produce a reliable
-backup -- such files will most probably be in insconsistent state,
+backup -- such files will most probably be in inconsistent state,
 because of eventual transactions not being finished at the time of the
 backup.  While stopping the database for the duration of the backup
 could produce a consistent backup, it is usually not an option.  The
 obvious solution in this case is to create a database
 .B dump
-using the DBS-specific software, and archive the created file or files.
+using the DBMS-specific software, and archive the created file or files.
 .PP
 To handle such cases,
 .B beam
@@ -87,11 +87,11 @@ stands for the name of the module):
 This function is called once for each backup item before starting
 backup or restore.  Its purpose is to check whether the configuration
 for that particular item is correct (e.g. whether all the mandatory
-configuration keywords are defined and have consistend values, etc.)
+configuration keywords are defined and have consistent values, etc.)
 
 If the configuration is correct, the function shall return
 .BR 0 .
-Otherwise, it shall produce appropiate diagnostic messages using
+Otherwise, it shall produce appropriate diagnostic messages using
 .B error
 or
 .B abend
@@ -171,6 +171,97 @@ fs_backup() {
 .BR \fIname\fB_restore( item )
 This function does the opposite to \fIname\fB_backup\fR: it restores
 the given item from the backup.
+.SH VARIABLES
+Apart from the variables defined in
+.BR beam.conf (5),
+a module can access the following ones:
+.TP
+.B week
+Number of the current week in year, as a two-digit decimal number in
+the range 01 to 53.  Weeks are numbered starting with the first Sunday
+as the first day of week 01. For more details, see
+.BR strftime (3)
+conversion
+.BR %U .
+.TP
+.B round
+Number of this backup round.  See
+.BR beam-backup (1),
+for a detailed discussion.
+.TP
+.B level
+Incremental level of this backup.
+.TP
+.B dry_run
+If the
+.B dry\-run
+module is enabled, the value of this variable is
+.BR echo ,
+otherwise it is empty.  Place this variable in front of a shell
+command to ensure it will be printed, but not executed when in
+.B dry\-run
+mode.  For example:
+.sp
+.nf
+.in +2
+  $dry_run rm $dbdir/*
+.in
+.fi
+.sp
+The
+.B dry\-run
+mode is enabled by the
+.BR \-\-dry\-run " or " \-n
+option to
+.BR beam-backup (1)
+and
+.BR beam-restore (1).
+.TP
+.B verbose
+In verbose mode, the value of this variable is
+.BR \-v ,
+otherwise it is empty.  Most programs use the
+.B \-v
+option to enable the verbose mode, so this variable can be used in
+constructing their command lines, e.g.:
+.sp
+.nf
+.in +2
+  $dry_run tar $verbose -c -f $archive .
+.in
+.fi
+.sp
+.TP
+.B tarerror
+Keeps the number of errors that occurred so far.  Increase this
+variable when an error occurred, that cannot be fixed automatically by
+the module.  See also the
+.B tarcode
+function below.
+.SH FUNCTIONS
+The following functions are available for use in modules:
+.TP
+.B logit
+Writes its arguments to the selected log stream.  The resulting line
+is prefixed with the current date.
+.TP
+.B error
+Write its arguments to the standard error, prefixing the line with the
+current date.
+.TP
+.B abend
+This function takes 2 or more arguments.  The first argument is a
+decimal number, treated as the shell exit code.  The rest of arguments
+supplies a diagnostic message.  The function writes that message to
+the standard error, and returns the supplied code to the shell.
+.TP
+.B tarcode
+The argument is a decimal return code from a
+.BR tar (1)
+invocation.  The function prints a human-readable description of the
+error code and increases
+.B tarerror
+if it is equal to or greater than 2.
 .SH "SEE ALSO"
 .BR beam (1),
 .BR beam.conf (5).
@@ -180,7 +271,7 @@ Sergey Poznyakoff
 Report bugs to <@PACKAGE_BUGREPORT@>.
 .\" Local variables:
 .\" eval: (add-hook 'write-file-hooks 'time-stamp)
-.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" 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