[alacarte] Add a man page

[Matthias Clasen <matthiasc src gnome org>]

commit 1ea9a43902882dc726923f343e9f4da7f5bb3311
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 7 11:04:37 2014 -0500

    Add a man page
    
    Because - why not ?
    
    https://bugzilla.gnome.org/show_bug.cgi?id=723860

 Makefile.am      |    4 ++
 configure.ac     |   13 ++++++++
 man/Makefile.am  |   18 +++++++++++
 man/alacarte.xml |   89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 124 insertions(+), 0 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index f0ed001..6d987a2 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -2,6 +2,10 @@
 
 SUBDIRS = data po Alacarte
 
+if BUILD_DOCUMENTATION
+SUBDIRS += man
+endif
+
 CLEANFILES=
 
 bin_SCRIPTS = alacarte
diff --git a/configure.ac b/configure.ac
index 223cc50..0a39d86 100644
--- a/configure.ac
+++ b/configure.ac
@@ -22,6 +22,18 @@ AM_PATH_PYTHON_VERSION(2.7, 2.7.0, 2.6, 2.6.0, 2.5, 2.5.0, 2.4, 2.4.0)
 
 PKG_CHECK_MODULES(ALACARTE, libgnome-menu-3.0 >= 3.5.3 pygobject-3.0)
 
+AC_ARG_ENABLE(documentation,
+              AS_HELP_STRING([--enable-documentation],
+                             [build documentation]),,
+              enable_documentation=yes)
+if test x$enable_documentation = xyes; then
+   AC_PATH_PROG([XSLTPROC], [xsltproc])
+   if test x$XSLTPROC = x; then
+      AC_MSG_ERROR([xsltproc is required to build documentation])
+   fi
+fi
+AM_CONDITIONAL(BUILD_DOCUMENTATION, test x$enable_documentation = xyes)
+
 AC_CONFIG_FILES([
         Makefile
         po/Makefile.in
@@ -29,6 +41,7 @@ AC_CONFIG_FILES([
         data/alacarte.desktop.in
        data/Makefile
        data/icons/Makefile
+       man/Makefile
         ])
 
 AC_OUTPUT
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 0000000..675d246
--- /dev/null
+++ b/man/Makefile.am
@@ -0,0 +1,18 @@
+XSLTPROC_FLAGS = \
+       --nonet \
+       --stringparam man.output.quietly 1 \
+       --stringparam funcsynopsis.style ansi \
+       --stringparam man.th.extra1.suppress 1 \
+       --stringparam man.authors.section.enabled 0 \
+       --stringparam man.copyright.section.enabled 0
+
+%.1: %.xml
+       $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) 
http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+man_MANS = alacarte.1
+
+xml_files = ${patsubst %.1,%.xml,${patsubst %.7,%.xml,$(man_MANS)}}
+
+EXTRA_DIST = $(xml_files)
+
+CLEANFILES = $(man_MANS)
diff --git a/man/alacarte.xml b/man/alacarte.xml
new file mode 100644
index 0000000..5d6f874
--- /dev/null
+++ b/man/alacarte.xml
@@ -0,0 +1,89 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>
+
+<refentry id="alacarte">
+
+        <refentryinfo>
+                <title>alacarte</title>
+                <productname>GNOME</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>Trevor</firstname>
+                                <surname>Watkins</surname>
+                        </author>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>Jasper</firstname>
+                                <surname>St. Pierre</surname>
+                        </author>
+                </authorgroup>
+
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>alacarte</refentrytitle>
+                <manvolnum>1</manvolnum>
+                <refmiscinfo class="manual">User Commands</refmiscinfo>
+        </refmeta>
+
+        <refnamediv>
+                <refname>alacarte</refname>
+                <refpurpose>Edit freedesktop.org menus</refpurpose>
+        </refnamediv>
+
+        <refsynopsisdiv>
+                <cmdsynopsis>
+                        <command>alacarte</command>
+                </cmdsynopsis>
+        </refsynopsisdiv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para><application>alacarte</application> is a graphical
+                editor for the freedesktop.org menus that are used by
+                many desktop environments. It can also edit and create
+                application desktop files.</para>
+
+        </refsect1>
+
+        <refsect1>
+                <title>Options</title>
+
+                <para><command>alacarte</command> does not accept any
+                commandline options.</para>
+        </refsect1>
+
+       <refsect1>
+               <title>Environment</title>
+
+               <variablelist>
+                       <varlistentry>
+                               <term><envar>XDG_CONFIG_DIRS</envar></term>
+                               <listitem><para><command>alacarte</command> looks in the 
<filename>menus</filename> subdirectory of these directories for menu files. The default location for menu 
files is <filename>/etc/xdg/menus</filename>.</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><envar>XDG_DATA_DIRS</envar></term>
+                               <listitem><para><command>alacarte</command> looks in the 
<filename>applications</filename> subdirectory of these directories for desktop files. The default location 
for desktop files is <filename>/usr/share/applications</filename>.</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><envar>XDG_CONFIG_HOME</envar></term>
+                               <listitem><para>The <filename>menus</filename> subdirectory of this directory 
is where <command>alacarte</command> stores modified menu files. The default location for modified menu files 
is <filename><envar>$HOME</envar>/.config/menus</filename>.</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><envar>XDG_DATA_HOME</envar></term>
+                               <listitem><para>The <filename>applications</filename> subdirectory of this 
directory is where <command>alacarte</command> stores modified and newly created desktop files. The default 
location for these is <filename><envar>$HOME</envar>/.local/share/applications</filename>.</para></listitem>
+                       </varlistentry>
+                       <varlistentry>
+                               <term><envar>XDG_MENU_PREFIX</envar></term>
+                               <listitem><para><command>alacarte</command> is editing the
+                               menus defined by the file 
<filename><envar>$XDG_MENU_PREFIX</envar>applications.menu</filename>. GNOME uses the menu file 
<filename>gnome-applications.menu</filename>.</para></listitem>
+                       </varlistentry>
+
+               </variablelist>
+       </refsect1>
+
+</refentry>