Documentation checking framework:

* doc/macros.texi, doc/check-docs.sh, doc/mastermenu.el,
doc/untabify.el, doc/rendition.texi: New files.
* pam_regex/pam_regex.c: Remove useless use_authtok option.
* pam_sql/pam_mysql.c, pam_sql/pam_pgsql.c,
pam_sql/pam_sql.c: Pacify `make check-sql-config' in doc.
* doc/Makefile.am: Add check-* rules.
* doc/pam-modules.texi: Update.




git-svn-id: file:///svnroot/pam-modules/trunk@92 56984be4-0537-0410-a56c-fcb268c96130

7 files changed, 879 insertions, 224 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index a1382b6..5dee6cf 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -15,13 +15,110 @@
 # with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 info_TEXINFOS=pam-modules.texi
-pam_modules_TEXINFOS=fdl.texi
+pam_modules_TEXINFOS=fdl.texi macros.texi rendition.texi
 
-EXTRA_DIST = gendocs_template
+EXTRA_DIST = \
+ check-docs.sh\
+ gendocs_template\
+ mastermenu.el\
+ untabify.el
 
 clean-local:
 	rm -rf manual
 
+# Checking
+check-format:
+	@if test -n "`cat $(info_TEXINFOS) $(pam_modules_TEXINFOS) | tr -d -c '\t'`"; then \
+		echo "Sources contain tabs; run make untabify"; \
+		false; \
+	fi
+
+check-refs:
+	@for file in $(info_TEXINFOS) $(mailfromd_TEXINFOS); \
+	do \
+	  sed -e = $$file | \
+           sed -n 'N;/@FIXME-.*ref/{s/\(^[0-9][0-9]*\).*@FIXME-.*ref{\([^}]*\)}.*/'$$file':\1: \2/gp}'; \
+	done > $@-t; \
+	if [ -s $@-t ]; then \
+	  echo "Unresolved cross-references:"; \
+	  cat $@-t;\
+	  rm $@-t; \
+	else \
+	  rm -f $@-t; \
+	fi
+
+check-fixmes:
+	@for file in $(info_TEXINFOS); \
+	do \
+	  sed -e = $$file | \
+           sed -n 'N;/@FIXME{/{s/\(^[0-9][0-9]*\).*@FIXME{\([^}]*\).*/'$$file':\1: \2/gp}'; \
+	done > $@-t; \
+	if [ -s $@-t ]; then \
+	  echo "Unresolved FIXMEs:"; \
+	  cat $@-t; \
+	  rm $@-t; \
+	  false; \
+	else \
+          rm -f $@-t; \
+	fi
+
+check-unrevised:
+	@grep -Hn @UNREVISED $(info_TEXINFOS) > $@-t; \
+	if [ -s $@-t ]; then \
+	  echo "Unrevised nodes:"; \
+	  cat $@-t; \
+	  rm $@-t; \
+	  false;\
+	else \
+          rm $@-t; \
+	fi
+
+check-log-options:
+	@check-docs.sh "pam_log options" \
+	   '/struct pam_opt .*\[\] = /,/^}/s/[ \t]*{ *PAM_OPTSTR(\([^,)]*\)).*/\1/p' \
+	   '/@set MODULE pam_log/,/@set MODULE/{s/@value{MODULE}/pam_log/g;there;:here;s/@opindex *\([^@,]*\),.*@command{pam_log}.*/\1/;t lab;b;: lab;{s/^-//;s/^no//;p;}}' \
+	   $(top_srcdir)/pam_log/*.c -- \
+	   $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
+		$(info_TEXINFOS) ; 
+
+
+check-all-options:
+	@for mod in fshadow regex sql; \
+	do \
+	  check-docs.sh "pam_$$mod options" \
+	   '/struct pam_opt .*\[\] = /,/^}/s/[ \t]*{ *PAM_OPTSTR(\([^,)]*\)).*/\1/;t lab;b;: lab {/audit/d;/debug/d;/waitdebug/d;p}' \
+	   '/@set MODULE pam_'$$mod'/,/@set MODULE/{s/@value{MODULE}/pam_'$$mod'/g;there;:here;s/@opindex *\([^@,]*\),.*@command{pam_'$$mod'}.*/\1/;t lab;b;: lab;{s/^-//;s/^no//;p;}}' \
+	   $(top_srcdir)/pam_$$mod/*.c -- \
+	   $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
+		$(info_TEXINFOS) ; \
+        done
+
+check-sql-config:
+	@check-docs.sh 'SQL configuration keywords' \
+	   's/.*check_boolean_config *("\([^"]*\)".*/\1/p;s/.*find_config *("\([^"]*\)".*/\1/p' \
+	   's/@kwindex *\([^@,]*\).*/\1/p' \
+	   $(top_srcdir)/pam_sql/*.c -- \
+	   $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
+		$(info_TEXINFOS) 
+
+check-options: check-all-options check-log-options
+
+all-check-docs: check-format check-refs check-fixmes check-unrevised check-options check-sql-config
+
+check-docs: 
+	$(MAKE) -k all-check-docs
+#
+
+master-menu:
+	emacs -batch -l mastermenu.el -f make-master-menu $(info_TEXINFOS)
+
+untabify:
+	emacs -batch -l untabify.el $(info_TEXINFOS) $(pam_modules_TEXINFOS)
+
+final: untabify master-menu
+
+#
+
 # The rendering level is one of PUBLISH, DISTRIB or PROOF.
 # Just call `make RENDITION=PROOF [target]' if you want PROOF rendition.
 RENDITION = DISTRIB
diff --git a/doc/check-docs.sh b/doc/check-docs.sh
new file mode 100755
index 0000000..c0b0487
--- /dev/null
+++ b/doc/check-docs.sh
@@ -0,0 +1,74 @@
+#! /bin/sh
+# This file is part of mailfrom filter.
+# Copyright (C) 2006, 2007 Sergey Poznyakoff
+#
+# This program 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, or (at your option)
+# any later version.
+#
+# This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+
+usage() {
+  cat <<EOT
+usage: $0 item code-sed doc-sed sources -- args...
+EOT
+}
+
+if [ $# -le 4 ]; then
+  usage
+  exit 2
+fi
+
+item=$1
+shift
+codesexp="$1"
+shift
+docsexp=$1
+shift
+
+source=
+while [ $# -ne 0 ]
+do
+	if [ "$1" = "--" ]; then
+		shift
+		break;
+	fi
+	source="$source $1"
+	shift
+done	
+
+TEMPDIR=/tmp/mfck.$$
+mkdir $TEMPDIR || exit 1
+trap 'rm -rf $TEMPDIR' 1 2 13 15
+
+sed -n "$codesexp" $source | sort | uniq > $TEMPDIR/src
+$* | \
+ sed -n '/^@macro/,/^@end macro/d;'"$docsexp" \
+  | sort | uniq > $TEMPDIR/doc
+
+join -v1 $TEMPDIR/src $TEMPDIR/doc > $TEMPDIR/src-doc
+join -v2 $TEMPDIR/src $TEMPDIR/doc > $TEMPDIR/doc-src
+(if [ -s $TEMPDIR/src-doc ]; then
+   echo "Not documented $item:"
+   cat $TEMPDIR/src-doc 
+ fi
+ if [ -s $TEMPDIR/doc-src ]; then
+   echo "Non-existing $item:"
+   cat $TEMPDIR/doc-src
+ fi) > $TEMPDIR/report
+
+if [ -s $TEMPDIR/report ]; then 
+  cat $TEMPDIR/report
+  rm -rf $TEMPDIR
+  exit 1
+else
+  rm -rf $TEMPDIR
+  exit 0
+fi
diff --git a/doc/macros.texi b/doc/macros.texi
new file mode 100644
index 0000000..34a719d
--- /dev/null
+++ b/doc/macros.texi
@@ -0,0 +1,24 @@
+@macro xopindex{option,text}
+@opindex \option\, @r{@command{@value{MODULE}} option, \text\}
+@end macro
+
+@macro opsummary{option}
+@ifclear ANCHOR-@value{MODULE}-\option\
+@set ANCHOR-@value{MODULE}-\option\ 1
+@anchor{\option\-@value{MODULE}}
+@end ifclear
+@xopindex{\option\, summary}
+@end macro
+
+@macro xkwindex{keyword,text}
+@kwindex \keyword\, @r{@command{@value{MODULE}} configuration keyword, \text\}
+@end macro
+
+@macro kwsummary{keyword}
+@ifclear ANCHOR-kw-@value{MODULE}-\keyword\
+@set ANCHOR-kw-@value{MODULE}-\keyword\ 1
+@anchor{\keyword\-kw-@value{MODULE}}
+@end ifclear
+@xkwindex{\keyword\, summary}
+@end macro
+
diff --git a/doc/mastermenu.el b/doc/mastermenu.el
new file mode 100644
index 0000000..3ab3341
--- /dev/null
+++ b/doc/mastermenu.el
@@ -0,0 +1,90 @@
+;;; mastermenu.el --- Redefinition of texinfo-master-menu-list
+
+;; Copyright (C) 2006, 2007 Free Software Foundation, Inc.
+
+;; Author: Sergey Poznyakoff
+;; Maintainer: bug-tar@gnu.org
+;; Keywords: maint, tex, docs
+
+;; This file is part of GNU tar documentation suite
+
+;; This program 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, or (at your option)
+;; any later version.
+
+;; This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This file redefines texinfo-master-menu-list so that it takes into
+;; account included files.
+
+;; Known bugs: @menu without previous sectioning command will inherit 
+;; documentation string from the previous menu. However, since such a
+;; menu is illegal in a texinfo file, we can live with it.
+
+(require 'texinfo)  
+(require 'texnfo-upd)
+
+(defun texinfo-master-menu-list-recursive (title)
+  "Auxiliary function used by `texinfo-master-menu-list'."
+  (save-excursion
+    (let (master-menu-list)
+      (while (re-search-forward "\\(^@menu\\|^@include\\)" nil t)
+	(cond
+	 ((string= (match-string 0) "@include")
+	  (skip-chars-forward " \t")
+	  (let ((included-name (let ((start (point)))
+				 (end-of-line)
+				 (skip-chars-backward " \t")
+				 (buffer-substring start (point)))))
+	    (end-of-line)
+	    (let ((prev-title (texinfo-copy-menu-title)))
+	      (save-excursion
+		(set-buffer (find-file-noselect included-name))
+		(setq master-menu-list
+		      (append (texinfo-master-menu-list-recursive prev-title)
+			      master-menu-list))))))
+	 (t
+	  (setq master-menu-list
+		(cons (list
+		       (texinfo-copy-menu)
+		       (let ((menu-title (texinfo-copy-menu-title)))
+			 (if (string= menu-title "")
+			     title
+			   menu-title)))
+		      master-menu-list)))))
+      master-menu-list)))
+
+(defun texinfo-master-menu-list ()
+  "Return a list of menu entries and header lines for the master menu,
+recursing into included files.
+
+Start with the menu for chapters and indices and then find each
+following menu and the title of the node preceding that menu.
+
+The master menu list has this form:
+
+    \(\(\(... \"entry-1-2\"  \"entry-1\"\) \"title-1\"\)
+      \(\(... \"entry-2-2\"  \"entry-2-1\"\) \"title-2\"\)
+      ...\)
+
+However, there does not need to be a title field."
+
+  (reverse (texinfo-master-menu-list-recursive "")))
+
+(defun make-master-menu ()
+  "Create master menu in the first Emacs argument."
+  (find-file (car command-line-args-left))
+  (texinfo-master-menu nil)
+  (save-buffer))
+
+
+;;; mastermenu.el ends here
diff --git a/doc/pam-modules.texi b/doc/pam-modules.texi
index b678814..b41f695 100644
--- a/doc/pam-modules.texi
+++ b/doc/pam-modules.texi
@@ -8,10 +8,14 @@
 
 @defcodeindex pr
 @defcodeindex op
+@defcodeindex kw
 @syncodeindex pr cp
 @syncodeindex op cp
+@syncodeindex kw cp
 
 @include version.texi
+@include macros.texi
+@include rendition.texi
 
 @ifinfo
 @dircategory System Utilities
@@ -79,18 +83,43 @@ Appendices
 * Copying This Manual:: The GNU Free Documentation License.
 * Concept Index::       Index of Concepts.
 
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Authentication against an alternative shadow file.
+
+* plain mode::
+* virtual domain mode::
+* summary of pam_fshadow options::
+
+Authentication using regular expressions.
+
+* access control::           Using pam_regex as access control module.
+* user name transformation:: Using pam_regex to alter user names.
+* summary of pam_regex options::
+
+SQL authentication.
+
+* config::      Configuration file.
+* sql auth::    Using @acronym{SQL} modules in authentication stack.
+* sql setenv::  Setting @acronym{PAM} environment from an
+                @acronym{SQL} database.
+* sql session:: Using @acronym{SQL} modules for session management.
+* sql summary:: Summary of configuration statements.
+
+@end detailmenu
 @end menu
 
 @node Intro, fshadow, Top, Top
 @chapter Introduction to PAM-modules
-
-     PAM-modules is a collection of @acronym{PAM
-modules} for user authentication and logging.  This manual describes
-each module in detail.  The reader is expected to be sufficiently
-proficient with general @acronym{UNIX} administration issues and with
-Pluggable Authentication Modules (@acronym{PAM}) in particular.
-
-     All modules from the package support the following command line
+   
+   PAM-modules is a collection of @acronym{PAM modules} for user
+authentication and logging.  This manual describes each module in
+detail.  The reader is expected to be sufficiently proficient with
+general @acronym{UNIX} administration issues and with Pluggable
+Authentication Modules (@acronym{PAM}) in particular. 
+
+   All modules from the package support the following command line
 arguments:
 
 @anchor{common options}
@@ -98,7 +127,7 @@ arguments:
 @opindex debug, common option
 @cindex debugging hints
 @item debug[=@var{level}]
-     Change debugging level (0 <= @var{level} <= 100).  The debugging
+   Change debugging level (0 <= @var{level} <= 100).  The debugging
 information will be logged via @code{syslog} channel
 @code{auth.debug}.  Notice, that debugging output can reveal
 authentication credentials (user password, in particular). 
@@ -106,14 +135,14 @@ authentication credentials (user password, in particular).
 @opindex waitdebug, common option
 @opindex enable-debug, @option{--enable-debug}, @command{configure} option
 @item waitdebug[=@var{interval}]
-     Wait for @var{interval} seconds before starting the operation.
+   Wait for @var{interval} seconds before starting the operation.
 This option is intended for the package developers and is not enabled,
 unless you configure the package with @option{--enable-debug} option.
 Most probably you will not need this option.  The following
 description is provided in case you decide to participate in
 @command{PAM-modules} development: 
 
-     When this option is present, the module displays the
+   When this option is present, the module displays the
 following diagnostics in @command{syslog} @code{auth.crit} channel:
 
 @smallexample
@@ -127,39 +156,55 @@ process with a debugger, set the @code{interval} variable to 0 and to
 continue execution of the module in the debugging mode. 
 @end table
 
-@cindex variable expansion
-@cindex expansion, variable
-@anchor{variable expansion}
-     Some modules perform @dfn{variable expansion} on their
-arguments.  During variable expansion, any occurrence of
-@code{$@var{variable}} in a string is replaced by the value of
-@var{variable}.  If the @var{variable} is not defined, emtpy string is
-substituted instead.  A limited support for the shell-style default
-values is available: namely, the notation
-@code{$@{@var{variable}:-@var{value}@}} expands to the value of
-@var{variable} if it is set, and to @var{value} otherwise. 
-
-     The followig table list supported variables:
-
-@multitable @columnfractions .30 .50
-@headitem Variable name @tab @acronym{PAM} variable
-@item service @tab PAM_SERVICE 
-@item user    @tab PAM_USER 
-@item tty     @tab PAM_TTY 
-@item rhost   @tab PAM_RHOST 
-@item ruser   @tab PAM_RUSER 
-@item prompt  @tab PAM_USER_PROMPT
-@item password @tab PAM_AUTHTOK
+@cindex PAM item expansion
+@cindex expansion, PAM item
+@anchor{item expansion}
+   Some modules perform @acronym{PAM} @dfn{item expansion} on their
+arguments.  It is a feature similar to shell's variable expansion.
+During item expansion, any occurrence of @code{$@var{name}} in a
+string is replaced by the value of the @acronym{PAM} item @var{name}.
+If the item in question is not defined, an emtpy string is substituted
+instead.  A limited support for the shell-style default values is
+available: namely, the notation @code{$@{@var{item}:-@var{value}@}}
+expands to the value of @var{item} if it is set, and to @var{value}
+otherwise.  Notice, that @var{value} must be a literal value (string
+or numeric).
+
+   The followig table lists @acronym{PAM} item names:
+
+@multitable @columnfractions .15 .25 .60
+@headitem Item name @tab @acronym{PAM} item @tab Meaning
+@item service @tab PAM_SERVICE @tab The service name (which identifies
+the @acronym{PAM} stack that will be used).
+@item user    @tab PAM_USER @tab The username of the entity under
+whose identity service will be given. 
+@item tty     @tab PAM_TTY @tab The terminal name: prefixed by
+@samp{/dev/} if it is a device file; for graphical, X-based,
+applications the value for this item is usually the @env{$DISPLAY}
+environment variable.
+@item rhost   @tab PAM_RHOST @tab The requesting hostname (the
+hostname of the machine from which the @code{PAM_RUSER} entity is
+requesting service). That is @samp{@code{PAM_RUSER}@@@code{PAM_RHOST}}
+identifies the requesting user. In some applications, @code{PAM_RHOST}
+may be @samp{NULL}. 
+@item ruser   @tab PAM_RUSER @tab The requesting entity: user's
+username for a locally requesting user or a remote requesting user. In
+some cases, @code{PAM_RUSER} may be @samp{NULL}.
+@item prompt  @tab PAM_USER_PROMPT @tab The string used when prompting
+for a user's name. The default value for this string is @samp{Please
+enter username: }. 
+@item password @tab PAM_AUTHTOK @tab The authentication token (often a
+password).
 @end multitable
 
-     Variable expansion is used by @command{pam_log},
-@command{pam_mysql} and @command{pam_pgsql}.
+   Item expansion is used by @command{pam_log}, @command{pam_mysql}
+and @command{pam_pgsql}. 
 
 @node fshadow, regex, Intro, Top
 @chapter Authentication against an alternative shadow file.
-
+@set MODULE pam_fshadow
 @prindex pam_fshadow
-     This module provides authentication against an alternative
+   This module provides authentication against an alternative
 @file{shadow} file, or @file{passwd} / @file{shadow} pair (or pairs).
 There are two main operation modes: @dfn{plain} mode, in which
 @command{pam_fshadow} uses only one @file{passwd}/@file{shadow} pair,
@@ -167,81 +212,92 @@ and @dfn{virtual domain} mode, which allows to select the pair to use
 based on the authentication token (the user name).  First, let's
 describe the plain mode. 
 
+@menu
+* plain mode::
+* virtual domain mode::
+* summary of pam_fshadow options::
+@end menu
+
+@node plain mode
+@section Using @command{pam_fshadow} in plain mode.
+
 @cindex plain mode, pam_fshadow
 @cindex pam_fshadow, plain
-     Plain mode is the default operation mode for
-@command{pam_fshadow}.  In this mode, the module uses the
-authentication token as the user name and verifies it against the
-@file{passwd}/@file{shadow} pair located in the system configuration 
-directory (which is set when configuring the package and
-defaults to @file{@var{prefix}/etc}).  This default location can be
-changed using the @option{sysconfdir} option (see below).  The
-authentication is performed as follows:
-
-     First, the user name is looked up in @file{passwd} file and the
+   Plain mode is the default operation mode for @command{pam_fshadow}.
+In this mode, the module checks the supplied user name and
+authentication token against the @file{passwd}/@file{shadow} pair
+located in the system configuration directory (which is set when
+configuring the package and defaults to @file{@var{prefix}/etc}).
+This default location can be changed using the @option{sysconfdir}
+option (see below).  The authentication is performed as follows:
+
+   First, the user name is looked up in @file{passwd} file and the
 corresponding record is fetched.  If this record contains a valid
 password hash (i.e. its second field is at least 2 characters long),
-the system @code{crypt} function is called on the supplied password
-with the retrieved hash as its second argument (the @code{seed}) and
-its result is compared with the hash.  If the two strings are the
-same, the user is authenticated successfully.
+the system @code{crypt} function is called on the supplied
+authentication token with the retrieved hash as its second argument
+(the @code{seed}) and its result is compared with the hash.  If the
+two strings are the same, the user is authenticated successfully.
 
-     Otherwise, if @file{passwd} contains no password, the shadow file is
+   Otherwise, if @file{passwd} contains no password, the shadow file is
 examined and the hash retrieved from there is used.  If the record
 retrieved from the shadow file has not expired, and if its password
-hash field matches the supplied password (using the algorithm
+hash field matches the authentication token (using the algorithm
 described above), the user is authenticated successfully.
 
-     Several options are provided to alter the default behavior.  All
+   Several options are provided to alter the default behavior.  All
 of them, except @command{sysconfdir}, have the same effect in the
 virtual domain mode as well.  The table below summarizes these options.
 
+@anchor{pam_fshadow common options}
 @table @option
-@opindex nopasswd, @command{pam_fshadow} option
+@xopindex{nopasswd, introduced}
 @item nopasswd
-     Do not require @file{passwd} file to be present.  Only
+   Do not require @file{passwd} file to be present.  Only
 @file{shadow} is used for authentication.
 
-@opindex sysconfdir, @command{pam_fshadow} option
+@xopindex{sysconfdir, introduced}
 @item sysconfdir=@var{dir}
-     Set full name of the directory where @file{shadow} and
+   Set full name of the directory where @file{shadow} and
 @file{passwd} are located.  By default the system configuration
 directory will be used.
 
-@opindex use_authtok, @command{pam_fshadow} option
-@item use_authtok	
-     Do not prompt the user for password, take it from the saved
+@xopindex{use_authtok, introduced}
+@item use_authtok       
+   Do not prompt the user for password, take it from the saved
 authentication tokens.  This option is useful when @command{pam_fshadow}
 is used as a non-first module in a stack of authentication modules.
 @end table
 
-     The following example illustrates the use of
-@command{pam_fshadow} in plain mode in @file{pam.conf} file:
+   The following example illustrates use of @command{pam_fshadow} in
+plain mode in @file{pam.conf} file: 
 
 @smallexample
 tuhs auth  required   pam_fshadow.so \
                       sysconfdir=/home/tuhs/tuhs/etc nopasswd use_authtok
 @end smallexample
 
+@node virtual domain mode
+@section Using @command{pam_fshadow} in virtual domain mode.
 @cindex virtual domain mode, pam_fshadow
 @cindex pam_fshadow, virtual domain
 
-     In @dfn{virtual domain} mode, @command{pam_fshadow} uses the
-authentication token to determine where to look for the
-@file{passwd}/@file{shadow} file pair.  The token is split into
+   In @dfn{virtual domain} mode, @command{pam_fshadow} uses the
+user name to determine where to look for the
+@file{passwd}/@file{shadow} file pair.  The name is split into 
 the @dfn{user name proper} and the @dfn{authentication domain}.  The
 configuration directory name is then obtained by concatenating the
 system configuration directory, a directory separator character (@samp{/}),
 and the name of the authentication domain.  Then, the authentication
-proceeds as described above for the plain mode.  If the supplied
-authentication token does not match the regular expression,
-@command{pam_fshadow} proceeds as in plain mode.
+proceeds as described above for the plain mode.  If the supplied user name
+does not match the regular expression, @command{pam_fshadow} proceeds
+as in plain mode. 
 
-@opindex regex, @command{pam_fshadow} option
+@xopindex{regex, introduced}
 @cindex enabling virtual domain mode, @command{pam_fshadow}
 @cindex virtual domain mode, enabling (@command{pam_fshadow})
-     This mode is enabled by the option @option{regex}, which supplies
-a regular expression used to split the authentication token.  This
+   This mode is enabled by the option @option{regex}, which supplies
+a regular expression used to split the user name.  This
 regular expression must contain two parenthesized @dfn{groups}.  First of
 them is used to extract the user name, and the second one is used
 to extract the authentication domain.  For example, the following option:
@@ -255,31 +311,35 @@ instructs @command{pam_fshadow} to use any characters before the
 @samp{@@} as the user name, and anything following it as the
 authentication domain.
 
-     Several options are provided, that control the flavor of the
+   Several options are provided, that control the flavor of the
 regular expression and the way of retrieving the authentication data
-from the token.  These options are: 
+from the user name.  These options are: 
 
 @table @option
-@opindex basic, @command{pam_fshadow} option
+@xopindex{basic, introduced}
 @item basic
-     Use basic regular expression. 
+   Use basic regular expression. 
 
-@opindex extended, @command{pam_fshadow} option      
+@xopindex{extended, introduced}
 @item extended
-     Use extended regular expression.  This is the default.
+   Use extended regular expression.  This is the default.
 
-@opindex ignore-case, @command{pam_fshadow} option
-@opindex icase, @command{pam_fshadow} option     
+@xopindex{ignore-case, introduced}
+@xopindex{icase, introduced}
 @item ignore-case
 @itemx icase
-     Use case-insensitive regular expression.
+   Use case-insensitive regular expression.
+
+@xopindex{case, introduced}     
+@item case
+   Use case-sensitive regular expressions (default).
 
-@opindex revert-index, @command{pam_fshadow} option     
+@xopindex{revert-index, introduced}
 @item revert-index
-     Use group 2 as the user name and group 1 as the authentication domain.
+   Use group #2 as the user name and group #1 as the authentication domain.
 @end table
 
-     To summarize, consider the following @file{pam.conf} entry:
+   As an example, consider the following @file{pam.conf} entry:
 
 @smallexample     
 check auth required pam_fshadow.so \
@@ -290,55 +350,129 @@ check auth required pam_fshadow.so \
 It instructs @command{pam_fshadow} to use @samp{@@} as the
 username/domain separator and to look up for the password databases
 under the @file{/etc/auth} directory.  For example, if the supplied
-authentication token was @samp{smith@@ftp}, then the module will look
-for the user name @samp{smith} in the files
+user name was @samp{smith@@ftp}, then the module will look
+for the user name @samp{smith} in files
 @file{/etc/auth/ftp/passwd} and @file{/etc/auth/ftp/shadow}.
 
+@node summary of pam_fshadow options
+@section summary of pam_fshadow options
+
+This section summarizes all @command{pam_fshadow} command line options:
+
+@table @option
+@opsummary{basic}
+@item basic
+   Use basic regular expressions.  @xref{virtual domain mode}.
+
+@opsummary{extended}
+@item extended
+   Use extended regular expression (default).  @xref{virtual domain mode}.
+
+@opsummary{ignore-case}
+@opsummary{icase}
+@item ignore-case
+@itemx icase
+   Use case-insensitive regular expressions.  @xref{virtual domain mode}.
+
+@opsummary{nopasswd}
+@item nopasswd
+   Use only @file{shadow} for authentication. @xref{pam_fshadow common
+options, nopasswd}.
+
+@opsummary{regex}
+@item regex=@var{expr}
+   Define a regular expression for splitting user name into the proper
+name and authentication domain.
+
+@opsummary{revert-index}
+@item revert-index
+   In the regular expression introduced by @code{regex}, group #1
+selects authentication domain, and group #2 selects user name.
+@xref{virtual domain mode, revert-index}.
+
+@opsummary{sysconfdir}
+@item sysconfdir=@var{dir}
+   Assume @var{dir} as the system configuration directory.
+@xref{pam_fshadow common options, sysconfdir}.
+
+@opsummary{use_authtok}
+@item use_authtok
+   Do not prompt the user for password, take it from the saved
+authentication tokens.
+
+@xref{pam_fshadow common options, use_authtok}.
+
+@end table
+
 @node regex, log, fshadow, Top
 @chapter Authentication using regular expressions.
+@set MODULE pam_regex
 
 @prindex pam_regex
-     The module @command{pam_regex} allows to control user access by
-matching their login name against a regular expression and to alter
-user names.  It may be useful, for example, in authentication stacks
-for such services as @acronym{FTP} or @acronym{HTTP}. 
+   The module @command{pam_regex} is a general-purpose tool for 
+authentication using regular expressions.  You can use it, for
+example, to allow or deny access depending on whether user name
+matches a given regular expression.  Another possible use is to
+modify user names following a predefined pattern (as in
+@command{sed}), to supply modules that follow it in the @acronym{PAM}
+stack with a normalized user name.
 
-     The following table describes command line options for this module:
+  As a quick start, the following @file{pam.conf} entry forbids access
+for any user names that look like email addresses:
 
-@table @code
-@opindex basic, @command{pam_regex} option
-@item basic
-     Use basic regular expression.
+@smallexample
+httpd auth  required  pam_regex.so sense=deny regex=.*@@.*
+@end smallexample
 
-@opindex case, @command{pam_regex} option     
-@item case
-     Use case-insensitive regular expression.
+@menu
+* access control::           Using pam_regex as access control module.
+* user name transformation:: Using pam_regex to alter user names.
+* summary of pam_regex options::
+@end menu
 
-@opindex extended, @command{pam_regex} option     
-@item extended
-     Use extended regular expression.
+@node access control
+@section Using @command{pam_regex} to control access.
 
-@opindex icase, @command{pam_regex} option
-@opindex ignore-case, @command{pam_regex} option
-@item ignore-case
-@itemx icase
-     Use case-insensitive regular expression.
+@xopindex{regex, described}
+   To control access depending on the supplied user name, two options
+are provided.  The option @option{regex} introduces a regular
+expression with which to compare a user name:
 
-@opindex regex, @command{pam_regex} option     
-@item regex=@var{string}
-     The user name must match the given regular expression.
-The default expression flavor is ``extended, case-sensitive'', but
-this can be changed using other options (see above).
+@table @option
+@item regex=@var{expression}
+   Compare user name with @var{expression}.  By default, extended
+regular expressions with case-sensitive matching are used, but 
+this can be changed using other options (see below).
+@end table
+
+   When this option is used, @command{pam_regex} allow only login
+attempts with user names that match @var{expression}.  The
+@option{sense} command line option is provided to control that
+behavior:
 
-@opindex sense, @command{pam_regex} option
+@table @option
+@xopindex{sense, described}
 @item sense=@{allow|deny@}
-     What to do if user name matches the regexp.  Default is @samp{allow}.
+   What to do if user name matches the @var{expression}.  The value
+@samp{allow} means to return @code{PAM_SUCCESS}, @samp{deny} means to
+return @code{PAM_AUTH_ERR}.  Default is @samp{allow}.
+@end table
 
-@opindex transform, @command{pam_regex} option
+@node user name transformation
+@section Using @command{pam_regex} to alter user names.
+
+  Another common use for @command{pam_regex} is to alter user names.
+This mode is enabled when the @option{transfer} option is used in the
+command line:
+
+@table @option
+@xopindex{transform, described}
 @item transform=@var{expression}
-     Transform the user name using given expression.  The argument
-@var{expression} is a @command{sed}-like replace expression of the 
-form:
+   Transform the user name using given regular expression.
+@end table
+
+   Its argument, @var{expression}, is a @command{sed}-like replace
+expression of the form:
 
 @smallexample
 s/@var{regexp}/@var{replace}/[@var{flags}]
@@ -356,13 +490,16 @@ separated by a semicolon.
 Supported @var{flags} are:
 
 @table @samp
+@cindex g, @option{transform} flag, @command{@value{MODULE}}
 @item g
 Apply the replacement to @emph{all} matches to the @var{regexp}, not
 just the first.
 
+@cindex i, @option{transform} flag, @command{@value{MODULE}}
 @item i
 Use case-insensitive matching
 
+@cindex x, @option{transform} flag, @command{@value{MODULE}}
 @item x
 @var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
 regexps, Extended regular expressions, Extended regular expressions,
@@ -391,80 +528,113 @@ s,one,two,
 @end group
 @end smallexample
 
-Changing delimiters is often useful when the @var{regex} contains
+  Changing delimiters is often useful when the @var{regex} contains
 slashes.  For instance, it is more convenient to write @code{s,/,-,} than
 @code{s/\//-/}.
 
-The following example converts the user name to
-lower case and removes anything after the @samp{@@} symbol.  It allows
-allows only user names @samp{anoncvs} and @samp{anonymous}.  As a
-result, the following user names will pass the module: @samp{anoncvs},
-@samp{Anoncvs}, @samp{AnonCVS@@user.org}.
+  The following example converts the user name to
+lower case and removes anything after the @samp{@@} symbol:
 
 @smallexample
 @group
-pam_refex.so extended transform=s/.*/\L&/g;s/@.*/ \
-             regex=^(anoncvs|anonymous)$ sense=allow 
+pam_refex.so extended transform=s/.*/\L&/g;s/@.*/ 
 @end group
 @end smallexample
-     
-@opindex use_authtok, @command{pam_regex} option     
-@item use_authtok	
-     Do not prompt the user for password, take it from the saved
-authentication tokens instead.  This option is useful when
-@command{pam_fshadow} is used as a non-first module in a stack of
-authentication modules. 
 
-@item user=@var{string}
-     Upon successful matching, set @acronym{PAM} user name to @var{string}.
+  Both @option{transform} and @option{regex} can be used
+simultaneously.  For example, the following command line first
+converts the user name to lower case and removes anything after the
+@samp{@@} symbol, and then compares it to the given regular
+expression.  The login is denied if the resulting user name matches
+the expression.  
 
-@end table
-
-     Here's an example of using this module:
-     
 @smallexample
-httpd auth  required  pam_regex.so sense=deny regex=.*@@.*
+@group
+pam_refex.so extended transform=s/.*/\L&/g;s/@.*/ \
+             regex=^(anoncvs|anonymous)$ sense=deny
+@end group
 @end smallexample
 
-This example denies login for users whose login names contain the
-@samp{@@} character.
+As a result, access with the following user names will be denied:
+@samp{anoncvs},  @samp{Anoncvs}, @samp{AnonCVS@@user.org}.
+
+@node summary of pam_regex options
+@section Summary of @command{pam_regex} options:
+
+@table @option
+@opsummary{basic}
+@item basic
+   Use basic regular expressions.
+
+@opsummary{case}     
+@item case
+   Use case-sensitive regular expressions (default).
+
+@opsummary{extended}     
+@item extended
+   Use extended regular expressions (default).
+
+@opsummary{icase}
+@opsummary{ignore-case}
+@item ignore-case
+@itemx icase
+   Use case-insensitive regular expressions.
+
+@opsummary{regex}
+@item regex=@var{expression}
+   Compare user name with @var{expression}.  
+
+@opsummary{sense}
+@item sense=@{allow|deny@}
+   What to do if user name matches the @var{expression}.  The value
+@samp{allow} means to return @code{PAM_SUCCESS}, @samp{deny} means to
+return @code{PAM_AUTH_ERR}.  Default is @samp{allow}.
+
+@opsummary{user}
+@item user=@var{string}
+   Upon successful matching, set @acronym{PAM} user name to @var{string}.
+
+@end table
 
 @node log, sql, regex, Top
 @chapter Log arbitrary messages to syslog.
+@set MODULE pam_log
 
 @prindex pam_log
-     The @command{pam_log} module is a diagnostic tool.  It works
+   The @command{pam_log} module is a diagnostic tool.