Manpage generation

Provides a set of make rules for generating UNIX manual pages from
DocBook 4.5 source  as well as sample manpage for sss_useradd.
Automatic generation of manual pages during "make" process is
tunable with config parameter "--with-manpages". To rebuild the man
pages separately, use the "make doc" target. Before building, the
manpages are validated using a DTD schema.

7 files changed, 240 insertions, 3 deletions

diff --git a/server/Makefile.in b/server/Makefile.in
index 292b6085..07208df2 100644
--- a/server/Makefile.in
+++ b/server/Makefile.in
@@ -17,6 +17,8 @@ srcdir = @srcdir@
 builddir = @builddir@
 sharedbuilddir = @sharedbuilddir@
 INSTALLCMD = @INSTALL@
+XSLTPROC = @XSLTPROC@
+XMLLINT = @XMLLINT@
 EXTRA_OBJ=@EXTRA_OBJ@
 SSSD_CONF_DIR = @sysconfdir@/sssd
 SSSD_LIBEXEC_PATH = @libexecdir@/@PACKAGE_NAME@
@@ -25,10 +27,12 @@ LDB_LIBDIR = @libdir@/ldb
 SSSD_INTROSPECT_PATH=@datarootdir@/@PACKAGE_NAME@/introspect
 PACKAGE_VERSION = @PACKAGE_VERSION@
 srvdir = @srcdir@
+mansrcdir = @srcdir@/man
 SSSD_PIPE_PATH = @pipepath@
 SSSD_DB_PATH = @dbpath@
 SSSD_PID_PATH = @pidpath@
 SHADOW_UTILS_PATH = @shadow_utils_path@
+SGML_CATALOG_FILES = @SGML_CATALOG_FILES@
 
 TALLOC_LIBS = @TALLOC_LIBS@
 TALLOC_CFLAGS = @TALLOC_CFLAGS@
@@ -94,9 +98,14 @@ CFLAGS := -I$(srcdir)/include -Iinclude -I$(srcdir) -I$(srcdir)/.. \
 MDLD = @MDLD@
 MDLD_FLAGS = @MDLD_FLAGS@
 
+export SGML_CATALOG_FILES
+XMLLINT_FLAGS = --catalogs --postvalid --nonet --xinclude --noout
+XSLTPROC_FLAGS = --catalogs --xinclude --nonet
+
 HAVE_INFOPIPE = @HAVE_INFOPIPE@
 HAVE_POLICYKIT = @HAVE_POLICYKIT@
 HAVE_TESTS = @HAVE_TESTS@
+HAVE_MANPAGES = @HAVE_MANPAGES@
 
 MEMBEROF_SOBASE=memberof.$(SHLIBEXT)
 MEMBEROF_SONAME=$(MEMBEROF_SOBASE).0
@@ -122,6 +131,13 @@ headers =
 DBUS_SYSBUS_POLICY_DIR = @sysconfdir@/dbus-1/system.d
 SSSD_CONF_FILE = etc/sssd.conf
 
+DOCBOOK_XSLT = http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
+MANPAGES = man/sss_useradd.8
+
+ifneq (x$(HAVE_MANPAGES), x)
+    GENDOC = $(MANPAGES)
+endif
+
 LIBEXECBINS =  sbin/sssd_nss sbin/sssd_dp sbin/sssd_be sbin/sssd_pam
 ifneq (x$(HAVE_INFOPIPE), x)
     LIBEXECBINS += sbin/sssd_info
@@ -146,7 +162,7 @@ SOBASELIBS = lib/$(PROXY_BE_SOBASE) lib/$(MEMBEROF_SOBASE) lib/$(LDAP_BE_SOBASE)
 
 DIRS = sbin lib
 
-all: showflags dirs $(OBJS) $(BINS) $(SOBASELIBS)
+all: showflags dirs $(OBJS) $(BINS) $(SOBASELIBS) $(GENDOC)
 
 shared-build: all
 
@@ -161,6 +177,7 @@ clean:: testclean
 	rm -f *.o */*.o */*/*.o
 	rm -f $(BINS)
 	rm -f $(SOBASELIBS) $(SONAMELIBS) $(SOLIBS) $(LDBLIBS)
+	rm -f $(MANPAGES)
 
 distclean:: clean
 	rm -rf $(DIRS)
@@ -173,7 +190,7 @@ realdistclean:: distclean
 testclean::
 	rm -f $(TESTS) $(TESTS_DATA)
 
-install:: all installdirs installheaders installlibs installbin installsupport
+install:: all installdirs installheaders installlibs installbin installsupport installdoc
 	${INSTALLCMD} -d $(DESTDIR)$(sbindir)
 	${INSTALLCMD} -m 755 sbin/sssd $(DESTDIR)$(sbindir)
 	${INSTALLCMD} -m 755 $(TOOLSBINS) $(DESTDIR)$(sbindir)
@@ -186,6 +203,7 @@ installdirs::
 	          $(DESTDIR)$(libdir) \
 	          $(DESTDIR)$(sbindir) \
 		  $(DESTDIR)$(initdir) \
+		  $(DESTDIR)$(mandir) \
 		  $(DESTDIR)$(SSSD_LIBDIR) \
 		  $(DESTDIR)$(LDB_LIBDIR) \
 	          $(DESTDIR)$(DBUS_SYSBUS_POLICY_DIR) \
@@ -220,3 +238,16 @@ ifneq (x$(HAVE_INFOPIPE), x)
 	cp $(DBUS_SYSBUS_POLICIES) $(DESTDIR)$(DBUS_SYSBUS_POLICY_DIR)
 	cp $(INFP_INTROSPECT_XML) $(DESTDIR)$(SSSD_INTROSPECT_PATH)/infopipe
 endif
+
+doc:: $(if $(HAVE_MANPAGES),$(MANPAGES), \
+        $(info Please use configure option --with-manpages to enable))
+
+installdoc:: installdirs
+ifneq (x$(HAVE_MANPAGES), x)
+	for mp in $(MANPAGES); do \
+	    FNAME=`basename $${mp}`; \
+	    SECTION=`echo $${mp} | grep -o .$$`; \
+	    SECTION_DIR=man$${SECTION}; \
+	    $(INSTALLCMD) -D -m 644 $${mp} $(DESTDIR)$(mandir)/$${SECTION_DIR}/$${FNAME}; \
+	done ;
+endif
diff --git a/server/conf_macros.m4 b/server/conf_macros.m4
index 27006e6d..d9345079 100644
--- a/server/conf_macros.m4
+++ b/server/conf_macros.m4
@@ -143,3 +143,33 @@ AC_DEFUN(WITH_SHADOW_UTILS_PATH,
     fi
     AC_SUBST(shadow_utils_path)
   ])
+
+AC_DEFUN(WITH_MANPAGES,
+  [ AC_ARG_WITH([manpages],
+                [AC_HELP_STRING([--with-manpages],
+                                [Whether to regenerate man pages from DocBook sources [yes]]
+                               )
+                ],
+                [],
+                with_manpages=yes
+               )
+    if test x"$with_manpages" == xyes; then
+        HAVE_MANPAGES=1
+        AC_SUBST(HAVE_MANPAGES)
+    fi
+  ])
+
+AC_DEFUN([WITH_XML_CATALOG],
+  [ AC_ARG_WITH([xml-catalog-path],
+                [AC_HELP_STRING([--with-xml-catalog-path=PATH],
+                                [Where to look for XML catalog [/etc/xml/catalog]]
+                               )
+                ]
+               )
+    SGML_CATALOG_FILES="/etc/xml/catalog"
+    if test x"$with_xml_catalog_path" != x; then
+        SGML_CATALOG_FILES="$with_xml_catalog_path"
+    fi
+    AC_SUBST([SGML_CATALOG_FILES])
+  ])
+
diff --git a/server/configure.ac b/server/configure.ac
index 79eb7305..a6a611a1 100644
--- a/server/configure.ac
+++ b/server/configure.ac
@@ -40,6 +40,8 @@ WITH_POLICYKIT
 WITH_TESTS
 WITH_INIT_DIR
 WITH_SHADOW_UTILS_PATH
+WITH_MANPAGES
+WITH_XML_CATALOG
 
 m4_include(pkg.m4)
 m4_include(libpopt.m4)
@@ -64,6 +66,12 @@ if test x$HAVE_TESTS != x; then
 fi
 PKG_CHECK_MODULES([NSS],[nss])
 
+if test x$HAVE_MANPAGES != x; then
+    AC_CHECK_FILE($SGML_CATALOG_FILES, [], [AC_MSG_ERROR([could not find XML catalog])])
+    AC_PATH_PROG([XSLTPROC], [xsltproc])
+    AC_PATH_PROG([XMLLINT], [xmllint])
+fi
+
 AC_SUBST(TESTS)
 AC_SUBST(EXTRA_OBJ)
 
diff --git a/server/man/include/param_help.xml b/server/man/include/param_help.xml
new file mode 100644
index 00000000..a2478bf2
--- /dev/null
+++ b/server/man/include/param_help.xml
@@ -0,0 +1,10 @@
+<varlistentry>
+    <term>
+        <option>-h</option>,<option>--help</option>
+    </term>
+    <listitem>
+        <para>
+            Display help message and exit.
+        </para>
+    </listitem>
+</varlistentry>
diff --git a/server/man/include/upstream.xml b/server/man/include/upstream.xml
new file mode 100644
index 00000000..b6f633cc
--- /dev/null
+++ b/server/man/include/upstream.xml
@@ -0,0 +1,4 @@
+<refentryinfo>
+    <productname>SSSD</productname>
+    <orgname>The SSSD upstream - http://fedorahosted.org/sssd</orgname>
+</refentryinfo>
diff --git a/server/man/sss_useradd.8.xml b/server/man/sss_useradd.8.xml
new file mode 100644
index 00000000..98bd7272
--- /dev/null
+++ b/server/man/sss_useradd.8.xml
@@ -0,0 +1,138 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<reference>
+<title>SSSD Manual pages</title>
+<refentry>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/upstream.xml" />
+
+    <refmeta>
+        <refentrytitle>sss_useradd</refentrytitle>
+        <manvolnum>8</manvolnum>
+    </refmeta>
+
+    <refnamediv id='name'>
+        <refname>sss_useradd</refname>
+        <refpurpose>create a new user</refpurpose>
+    </refnamediv>
+
+    <refsynopsisdiv id='synopsis'>
+        <cmdsynopsis>
+            <command>sss_useradd</command>
+            <arg choice='opt'>
+                <replaceable>options</replaceable>
+            </arg>
+            <arg choice='plain'><replaceable>LOGIN</replaceable></arg>
+        </cmdsynopsis>
+    </refsynopsisdiv>
+
+    <refsect1 id='description'>
+        <title>DESCRIPTION</title>
+        <para>
+            <command>sss_useradd</command> command creates a new user account using
+            the values specified on the command line plus the default values from
+            the system.
+        </para>
+    </refsect1>
+
+    <refsect1 id='options'>
+        <title>OPTIONS</title>
+        <variablelist remap='IP'>
+            <varlistentry>
+                <term>
+                    <option>-u</option>,<option>--uid</option>
+                    <replaceable>UID</replaceable>
+                </term>
+                <listitem>
+                    <para>
+                        Set the UID of the user to the value of <replaceable>UID</replaceable>.
+                        If not given, it is chosen automatically.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>
+                    <option>-g</option>,<option>--gid</option>
+                    <replaceable>GID</replaceable>
+                </term>
+                <listitem>
+                    <para>
+                        Set the GID or group membership of the user to the value
+                        of <replaceable>GID</replaceable>. If not given, it is
+                        chosen automatically.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>
+                    <option>-c</option>,<option>--gecos</option>
+                    <replaceable>COMMENT</replaceable>
+                </term>
+                <listitem>
+                    <para>
+                        Any text string describing the user. Often used as
+                        the field for the user's full name.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>
+                    <option>-h</option>,<option>--home</option>
+                    <replaceable>HOME_DIR</replaceable>
+                </term>
+                <listitem>
+                    <para>
+                        The home directory of the user account.
+                        The default is to append the <replaceable>LOGIN</replaceable> name
+                        to <filename>/home</filename> and use that as the login directory name.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>
+                    <option>-s</option>,<option>--shell</option>
+                    <replaceable>SHELL</replaceable>
+                </term>
+                <listitem>
+                    <para>
+                        The user's login shell. The default is currently <filename>/bin/bash</filename>.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>
+                    <option>-G</option>,<option>--groups</option>
+                    <replaceable>GROUPS</replaceable>
+                </term>
+                <listitem>
+                    <para>
+                        A list of existing groups this user is also a member of.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="include/param_help.xml" />
+        </variablelist>
+    </refsect1>
+
+    <refsect1 id='see_also'>
+        <title>SEE ALSO</title>
+        <para>
+            <citerefentry>
+                <refentrytitle>groupadd</refentrytitle><manvolnum>8</manvolnum>
+            </citerefentry>,
+            <citerefentry>
+                <refentrytitle>groupdel</refentrytitle><manvolnum>8</manvolnum>
+            </citerefentry>,
+            <citerefentry>
+                <refentrytitle>groupmod</refentrytitle><manvolnum>8</manvolnum>
+            </citerefentry>,
+            <citerefentry>
+                <refentrytitle>userdel</refentrytitle><manvolnum>8</manvolnum>
+            </citerefentry>,
+            <citerefentry>
+                <refentrytitle>usermod</refentrytitle><manvolnum>8</manvolnum>
+            </citerefentry>.
+        </para>
+    </refsect1>
+</refentry>
+</reference>
diff --git a/server/rules.mk b/server/rules.mk
index 8ef3676a..69f3c45a 100644
--- a/server/rules.mk
+++ b/server/rules.mk
@@ -4,7 +4,7 @@ etags:
 ctags:
 	ctags `find $(srcdir) -name "*.[ch]"`
 
-.SUFFIXES: .c .o
+.SUFFIXES: .c .o .xml .1.xml .3.xml .5.xml .8.xml .1 .3 .5 .8
 
 .c.o:
 	@echo Compiling $*.c
@@ -16,6 +16,22 @@ ctags:
 	@mkdir -p `dirname $@`
 	@$(CC) -fPIC $(CFLAGS) -c $< -o $@
 
+.1.xml.1:
+	$(XMLLINT) $(XMLLINT_FLAGS) $<
+	$(XSLTPROC) -o $@  $(XSLTPROC_FLAGS) $(DOCBOOK_XSLT) $<
+
+.3.xml.3:
+	$(XMLLINT) $(XMLLINT_FLAGS) $<
+	$(XSLTPROC) -o $@  $(XSLTPROC_FLAGS) $(DOCBOOK_XSLT) $<
+
+.5.xml.5:
+	$(XMLLINT) $(XMLLINT_FLAGS) $<
+	$(XSLTPROC) -o $@  $(XSLTPROC_FLAGS) $(DOCBOOK_XSLT) $<
+
+.8.xml.8:
+	$(XMLLINT) $(XMLLINT_FLAGS) $<
+	$(XSLTPROC) -o $@  $(XSLTPROC_FLAGS) $(DOCBOOK_XSLT) $<
+
 showflags::
 	@echo 'server will be compiled with flags:'
 	@echo '  CFLAGS = $(CFLAGS)'