Relevant BUGIDs:

Purpose of commit: new feature

Commit summary:
---------------

Convert manual page to XML and make it look like the other ones

5 files changed, 337 insertions, 52 deletions

diff --git a/modules/pam_localuser/Makefile.am b/modules/pam_localuser/Makefile.am
index bd5b29ce..ae331755 100644
--- a/modules/pam_localuser/Makefile.am
+++ b/modules/pam_localuser/Makefile.am
@@ -4,11 +4,12 @@
 
 CLEANFILES = *~
 
-EXTRA_DIST = README ${MANS} tst-pam_localuser
+EXTRA_DIST = README ${MANS} $(XMLS) tst-pam_localuser
 
 TESTS = tst-pam_localuser
 
 man_MANS = pam_localuser.8
+XMLS = README.xml pam_localuser.8.xml
 
 securelibdir = $(SECUREDIR)
 secureconfdir = $(SCONFIGDIR)
@@ -21,3 +22,10 @@ if HAVE_VERSIONING
 endif
 
 securelib_LTLIBRARIES = pam_localuser.la
+
+if ENABLE_REGENERATE_MAN
+noinst_DATA = README
+README: pam_localuser.8.xml
+-include $(top_srcdir)/Make.xml.rules
+endif
+
diff --git a/modules/pam_localuser/README b/modules/pam_localuser/README
index b8cdf524..50663ead 100644
--- a/modules/pam_localuser/README
+++ b/modules/pam_localuser/README
@@ -1,17 +1,38 @@
-pam_localuser:
-	Succeeds iff the PAM_USER is listed in /etc/passwd.  This seems to be a
-	common policy need (allowing only a subset of network-wide users, and
-	any locally-defined users, to access services).  Simpler than using
-	awk to generate a file for use with pam_listfile (-F: '{print $1}'),
-	I guess.
-
-RECOGNIZED ARGUMENTS:
-	debug		write debugging messages to syslog
-	file=FILE	scan FILE instead of /etc/passwd
-
-MODULE SERVICES PROVIDED:
-	auth,account	scan the FILE (/etc/passwd by default) and return
-			a success code if an entry is found for the user
-
-AUTHOR:
-	Nalin Dahyabhai <nalin@redhat.com>
+pam_localuser — require users to be listed in /etc/passwd
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DESCRIPTION
+
+pam_localuser is a PAM module to help implementing site-wide login policies,
+where they typically include a subset of the network's users and a few accounts
+that are local to a particular workstation. Using pam_localuser and pam_wheel
+or pam_listfile is an effective way to restrict access to either local users
+and/or a subset of the network's users.
+
+This could also be implemented using pam_listfile.so and a very short awk
+script invoked by cron, but it's common enough to have been separated out.
+
+OPTIONS
+
+debug
+
+    Print debug information.
+
+file=/path/passwd
+
+    Use a file other than /etc/passwd.
+
+EXAMPLES
+
+Add the following line to /etc/pam.d/su to allow only local users in group
+wheel to use su.
+
+account sufficient pam_localuser.so
+account required pam_wheel.so
+
+
+AUTHOR
+
+pam_localuser was written by Nalin Dahyabhai <nalin@redhat.com>.
+
diff --git a/modules/pam_localuser/README.xml b/modules/pam_localuser/README.xml
new file mode 100644
index 00000000..4ab56d9d
--- /dev/null
+++ b/modules/pam_localuser/README.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.docbook.org/xml/4.3/docbookx.dtd"
+[
+<!--
+<!ENTITY pamaccess SYSTEM "pam_localuser.8.xml">
+-->
+]>
+
+<article>
+
+  <articleinfo>
+
+    <title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_localuser.8.xml" xpointer='xpointer(//refnamediv[@id = "pam_localuser-name"]/*)'/>
+    </title>
+
+  </articleinfo>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_localuser.8.xml" xpointer='xpointer(//refsect1[@id = "pam_localuser-description"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_localuser.8.xml" xpointer='xpointer(//refsect1[@id = "pam_localuser-options"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_localuser.8.xml" xpointer='xpointer(//refsect1[@id = "pam_localuser-examples"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_localuser.8.xml" xpointer='xpointer(//refsect1[@id = "pam_localuser-author"]/*)'/>
+  </section>
+
+</article>
diff --git a/modules/pam_localuser/pam_localuser.8 b/modules/pam_localuser/pam_localuser.8
index ce0a9465..eafe981f 100644
--- a/modules/pam_localuser/pam_localuser.8
+++ b/modules/pam_localuser/pam_localuser.8
@@ -1,36 +1,76 @@
-.\" Copyright 2000 Red Hat, Inc.
-.TH pam_localuser 8 2000/7/21 "Red Hat" "System Administrator's Manual"
-
-.SH NAME
+.\"     Title: pam_localuser
+.\"    Author: 
+.\" Generator: DocBook XSL Stylesheets v1.70.1 <http://docbook.sf.net/>
+.\"      Date: 06/02/2006
+.\"    Manual: Linux\-PAM Manual
+.\"    Source: Linux\-PAM Manual
+.\"
+.TH "PAM_LOCALUSER" "8" "06/02/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
 pam_localuser \- require users to be listed in /etc/passwd
+.SH "SYNOPSIS"
+.HP 17
+\fBpam_localuser.so\fR [debug] [file=\fI/path/passwd\fR]
+.SH "DESCRIPTION"
+.PP
+pam_localuser is a PAM module to help implementing site\-wide login policies, where they typically include a subset of the network's users and a few accounts that are local to a particular workstation. Using pam_localuser and pam_wheel or pam_listfile is an effective way to restrict access to either local users and/or a subset of the network's users.
+.PP
+This could also be implemented using pam_listfile.so and a very short awk script invoked by cron, but it's common enough to have been separated out.
+.SH "OPTIONS"
+.PP
+.TP 3n
+\fBdebug\fR
+Print debug information.
+.TP 3n
+\fBfile=\fR\fB\fI/path/passwd\fR\fR
+Use a file other than
+\fI/etc/passwd\fR.
+.SH "MODULE SERVICES PROVIDED"
+.PP
+The
+\fBauth\fR
+and
+\fBaccount\fR
+services are supported.
+.SH "RETURN VALUES"
+.PP
+.TP 3n
+PAM_SUCCESS
+The new localuser was set successfull.
+.TP 3n
+PAM_SERVICE_ERR
+No username was given.
+.TP 3n
+PAM_USER_UNKNOWN
+User not known.
+.SH "EXAMPLES"
+.PP
+Add the following line to
+\fI/etc/pam.d/su\fR
+to allow only local users in group wheel to use su.
+.sp
+.RS 3n
+.nf
+account sufficient pam_localuser.so
+account required pam_wheel.so
+      
+.fi
+.RE
+.sp
+.SH "FILES"
+.TP 3n
+\fI/etc/passwd\fR
+Local user account information.
+.SH "SEE ALSO"
+.PP
 
-.SH SYNOPSIS
-.B account sufficient /lib/security/pam_localuser.so \fIargs\fP
-.br
-.B account required /lib/security/pam_wheel.so group=devel
-
-.SH DESCRIPTION
-pam_localuser.so exists to help implement site-wide login policies, where
-they typically include a subset of the network's users and a few accounts
-that are local to a particular workstation.  Using pam_localuser.so and
-pam_wheel.so or pam_listfile.so is an effective way to restrict access to
-either local users and/or a subset of the network's users.
-
-This could also be implemented using pam_listfile.so and a very short awk
-script invoked by cron, but it's common enough to have been separated out.
-
-.SH ARGUMENTS
-.IP debug
-turns on debugging
-.IP file=\fBFILE\fP
-uses a file other than \fB/etc/passwd\fP.
-
-.SH FILES
-/etc/passwd
-
-.SH BUGS
-Let's hope not, but if you find any, please report them via the "Bug Track"
-link at http://bugzilla.redhat.com/bugzilla/
-
-.SH AUTHOR
-Nalin Dahyabhai <nalin@redhat.com>
+\fBpam.conf\fR(5),
+\fBpam.d\fR(8),
+\fBpam\fR(8)
+.SH "AUTHOR"
+.PP
+pam_localuser was written by Nalin Dahyabhai <nalin@redhat.com>.
diff --git a/modules/pam_localuser/pam_localuser.8.xml b/modules/pam_localuser/pam_localuser.8.xml
new file mode 100644
index 00000000..f48c041d
--- /dev/null
+++ b/modules/pam_localuser/pam_localuser.8.xml
@@ -0,0 +1,175 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
+<refentry id="pam_localuser">
+
+  <refmeta>
+    <refentrytitle>pam_localuser</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class="sectdesc">Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id="pam_localuser-name">
+    <refname>pam_localuser</refname>
+    <refpurpose>require users to be listed in /etc/passwd</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_localuser-cmdsynopsis">
+      <command>pam_localuser.so</command>
+      <arg choice="opt">
+	debug
+      </arg>
+      <arg choice="opt">
+        file=<replaceable>/path/passwd</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id="pam_localuser-description">
+
+    <title>DESCRIPTION</title>
+
+    <para>
+      pam_localuser is a PAM module to help implementing site-wide login
+      policies, where they typically include a subset of the network's
+      users and a few accounts that are local to a particular workstation.
+      Using pam_localuser and pam_wheel or pam_listfile is an effective
+      way to restrict access to either local users and/or a subset of the
+      network's users.
+    </para>
+    <para>
+      This could also be implemented using pam_listfile.so and a very
+      short awk script invoked by cron, but it's common enough to have
+      been separated out.
+    </para>
+
+  </refsect1>
+
+  <refsect1 id="pam_localuser-options">
+
+    <title>OPTIONS</title>
+    <para>
+      <variablelist>
+
+        <varlistentry>
+          <term>
+            <option>debug</option>
+          </term>
+          <listitem>
+            <para>
+	      Print debug information.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>
+            <option>file=<replaceable>/path/passwd</replaceable></option>
+          </term>
+          <listitem>
+            <para>
+              Use a file other than <filename>/etc/passwd</filename>.
+            </para>
+          </listitem>
+	</varlistentry>
+
+      </variablelist>
+
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_localuser-services">
+    <title>MODULE SERVICES PROVIDED</title>
+    <para>
+      The <emphasis remap='B'>auth</emphasis> and
+      <emphasis remap='B'>account</emphasis> services are supported.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_localuser-return_values'>
+    <title>RETURN VALUES</title>
+    <para>
+      <variablelist>
+
+        <varlistentry>
+          <term>PAM_SUCCESS</term>
+          <listitem>
+            <para>
+              The new localuser was set successfull.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>PAM_SERVICE_ERR</term>
+          <listitem>
+            <para>
+	      No username was given.
+            </para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>PAM_USER_UNKNOWN</term>
+          <listitem>
+            <para>
+	      User not known.
+            </para>
+          </listitem>
+        </varlistentry>
+
+      </variablelist>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_localuser-examples'>
+    <title>EXAMPLES</title>
+    <para>
+      Add the following line to <filename>/etc/pam.d/su</filename> to
+      allow only local users in group wheel to use su.
+      <programlisting>
+account sufficient pam_localuser.so
+account required pam_wheel.so
+      </programlisting>
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_lastlog-files">
+    <title>FILES</title>
+    <variablelist>
+      <varlistentry>
+        <term><filename>/etc/passwd</filename></term>
+        <listitem>
+          <para>Local user account information.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_localuser-see_also'>
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+	<refentrytitle>pam.conf</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam.d</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+	<refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_localuser-author'>
+    <title>AUTHOR</title>
+      <para>
+        pam_localuser was written by Nalin Dahyabhai &lt;nalin@redhat.com&gt;.
+      </para>
+  </refsect1>
+
+</refentry>
+<!-- vim: sw=2
+-->