[ostree] Add an initial man page - ostree(1)

[Colin Walters <walters src gnome org>]

commit 8854ec59be43cc919eb129eda8bdbd520ce66418
Author: Colin Walters <walters verbum org>
Date:   Fri Dec 23 18:46:19 2011 -0500

    Add an initial man page - ostree(1)
    
    Heavily cribbed from systemd - thanks Lennart!

 Makefile-ostree.am |    2 +
 Makefile.am        |   41 ++++++++++
 configure.ac       |    3 +
 doc/ostree.xml     |  210 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 256 insertions(+), 0 deletions(-)
---
diff --git a/Makefile-ostree.am b/Makefile-ostree.am
index 0549810..8c8f8a2 100644
--- a/Makefile-ostree.am
+++ b/Makefile-ostree.am
@@ -54,3 +54,5 @@ ostree_pull_SOURCES = src/ostree/ot-main.h \
 ostree_pull_CFLAGS = $(ostree_bin_shared_cflags) $(OT_DEP_SOUP_CFLAGS)
 ostree_pull_LDADD = $(ostree_bin_shared_ldadd) $(OT_DEP_SOUP_LIBS)
 endif
+
+MANPAGES += doc/ostree.1
diff --git a/Makefile.am b/Makefile.am
index 755e7f5..8869389 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -21,6 +21,7 @@ AM_CFLAGS = $(WARN_CFLAGS)
 
 NULL = 
 BUILT_SOURCES =
+MANPAGES =
 CLEANFILES =
 EXTRA_DIST =
 bin_PROGRAMS =
@@ -37,3 +38,43 @@ include Makefile-libostree.am
 include Makefile-ostree.am
 include Makefile-ostbuild.am
 include Makefile-triggers.am
+
+#  Docbook generation copied from systemd/Makefile.am
+#
+#  Copyright 2010 Lennart Poettering
+#
+#  systemd 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 2 of the License, or
+#  (at your option) any later version.
+#
+#  systemd 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 systemd; If not, see <http://www.gnu.org/licenses/>.
+
+XML_FILES = \
+	${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,${patsubst %.8,%.xml,$(MANPAGES)}}}}}
+EXTRA_DIST += $(XML_FILES)
+
+if HAVE_XSLTPROC
+
+dist_man_MANS = $(MANPAGES)
+
+XSLTPROC_FLAGS = \
+	--nonet \
+	--param funcsynopsis.style "'ansi'"
+
+XSLTPROC_PROCESS_MAN = \
+	$(AM_V_GEN)$(MKDIR_P) $(dir $@) && \
+	$(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+doc/%.1: doc/%.xml
+	$(XSLTPROC_PROCESS_MAN)
+
+endif
+
+
diff --git a/configure.ac b/configure.ac
index b47e105..b9f1ed7 100644
--- a/configure.ac
+++ b/configure.ac
@@ -65,6 +65,9 @@ AM_CONDITIONAL(USE_LIBARCHIVE, test $with_libarchive != no)
 
 AM_PATH_PYTHON([2.7])
 
+AC_PATH_PROG([XSLTPROC], [xsltproc])
+AM_CONDITIONAL(HAVE_XSLTPROC, test x"$XSLTPROC" != x)
+
 AC_CONFIG_FILES([
 Makefile
 ])
diff --git a/doc/ostree.xml b/doc/ostree.xml
new file mode 100644
index 0000000..c785229
--- /dev/null
+++ b/doc/ostree.xml
@@ -0,0 +1,210 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>
+
+<!--
+  Copyright 2011 Colin Walters <walters verbum org>
+
+  This library is free software; you can redistribute it and/or
+  modify it under the terms of the GNU Lesser General Public
+  License as published by the Free Software Foundation; either
+  version 2 of the License, or (at your option) any later version.
+ 
+  This library 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
+  Lesser General Public License for more details.
+ 
+  You should have received a copy of the GNU Lesser General Public
+  License along with this library; if not, write to the
+  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+  Boston, MA 02111-1307, USA.
+-->
+
+<refentry id="ostree">
+
+        <refentryinfo>
+                <title>ostree</title>
+                <productname>OSTree</productname>
+
+                <authorgroup>
+                        <author>
+                                <contrib>Developer</contrib>
+                                <firstname>Colin</firstname>
+                                <surname>Walters</surname>
+                                <email>walters verbum org</email>
+                        </author>
+                </authorgroup>
+        </refentryinfo>
+
+        <refmeta>
+                <refentrytitle>ostree</refentrytitle>
+                <manvolnum>1</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>ostree</refname>
+                <refpurpose>Operating system build, deployment, and development tool</refpurpose>
+        </refnamediv>
+
+        <refsynopsisdiv>
+                <cmdsynopsis>
+                        <command>ostree <arg choice="req">--repo=REPO</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">OPTIONS</arg></command>
+                </cmdsynopsis>
+        </refsynopsisdiv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>OSTree is a system for building, deploying, and
+                developing Linux-based operating systems.  For many
+                cases, it can fill the role of "package managers" such
+                as RPM and .deb.</para>
+		<para>At its heart, OSTree is very similar to git -
+		but it is designed explicitly for managing files like
+		ELF binaries.  Unlike a typical version control
+		system, OSTree is capable of tracking file UID and
+		GIDs, as well as all extended attributes such as ACLs
+		and SELinux security contexts. You should think of
+		OSTree as a flexible but specialized userspace
+		filesystem.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Options</title>
+
+                <para>The following options are understood:</para>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><option>--repo</option></term>
+
+                                <listitem><para>For most commands,
+                                when run as non-root, repository is
+                                required.  If
+                                <command>ostree</command> is run as
+                                root, it is assumed operations will be
+                                performed on the
+                                <filename>/sysroot/ostree/repo</filename>
+                                repository.
+                                </para></listitem>
+                        </varlistentry>
+
+		</variablelist>
+
+                <para>The following commands are understood:</para>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><command>checkout</command></term>
+
+                                <listitem><para>Extract a given branch into the filesystem.</para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>checksum</command></term>
+
+                                <listitem><para>Compute the OSTree checksum of the given files.</para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>diff</command></term>
+
+                                <listitem><para>Concisely list differences between the given branch revisions,
+				without checking them out into the filesystem.</para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>init</command></term>
+
+                                <listitem><para>Initialize a repository.</para></listitem>
+
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>commit</command></term>
+
+                                <listitem><para>Given one or more
+                                trees (from the local filesystem, a
+                                tarball, or a specified revision for
+                                example), create a new commit using those contents.
+                                </para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>compose</command></term>
+
+                                <listitem><para>A specialized type of
+                                commit, intended for merging together
+                                many separate filesystem trees such as
+                                build artifacts.</para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>local-clone</command></term>
+
+                                <listitem><para>Efficiently copy
+                                objects and references from one local
+                                repository into another.
+                                </para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>log</command></term>
+
+                                <listitem><para>Show revision log.</para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>ls</command></term>
+
+                                <listitem><para>List the contents of a given commit.</para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>fsck</command></term>
+
+                                <listitem><para>Check a repository for consistency.</para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>remote</command></term>
+
+                                <listitem><para>Manipulate remote archive configuration.</para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>rev-parse</command></term>
+
+                                <listitem><para>Show the SHA256 corresponding to a given rev.</para></listitem>
+                        </varlistentry>
+                        <varlistentry>
+                                <term><command>run-triggers</command></term>
+
+                                <listitem><para>Regenerate cache files in the given operating system tree.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><command>show</command></term>
+
+                                <listitem><para>Given an OSTree SHA256 checksum, display its contents.</para></listitem>
+                        </varlistentry>
+                </variablelist>
+
+        </refsect1>
+
+        <refsect1>
+                <title>Exit status</title>
+
+                <para>On success 0 is returned, a non-zero failure
+                code otherwise.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Environment</title>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>$PAGER</varname></term>
+				<listitem><para><command>ostree</command> respects the traditional pager envrionment variable.</para></listitem>
+                        </varlistentry>
+                </variablelist>
+        </refsect1>
+
+        <refsect1>
+                <title>See Also</title>
+                <para>
+                        <citerefentry><refentrytitle>ostbuild</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                </para>
+        </refsect1>
+
+</refentry>