From e7e6215ae3531534fc6b2d1cf5fe871a9137197f Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Sun, 30 Mar 2014 19:32:50 -0400
Subject: [PATCH] doc: Add ostree.repo and ostree.repo-config manual pages

In particular I wanted to document gpg-verify.
---
 doc/Makefile.am            |   4 +-
 doc/ostree.repo-config.xml | 123 +++++++++++++++++++++++++++++++++++++
 doc/ostree.repo.xml        |  94 ++++++++++++++++++++++++++++
 3 files changed, 220 insertions(+), 1 deletion(-)
 create mode 100644 doc/ostree.repo-config.xml
 create mode 100644 doc/ostree.repo.xml

diff --git a/doc/Makefile.am b/doc/Makefile.am
index edb04843..40fa5620 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -108,7 +108,7 @@ include $(top_srcdir)/gtk-doc.make
 man1_MANS =
 
 if ENABLE_GTK_DOC
-man1_MANS += ostree.1
+man1_MANS += ostree.1 ostree.repo.5 ostree.repo-config.5
 
 XSLTPROC_FLAGS = \
         --nonet \
@@ -123,6 +123,8 @@ XSLTPROC_MAN = \
 
 .xml.1:
 	$(AM_V_GEN) $(XSLTPROC_MAN) $<
+.xml.5:
+	$(AM_V_GEN) $(XSLTPROC_MAN) $<
 
 endif # ENABLE_GTK_DOC
 
diff --git a/doc/ostree.repo-config.xml b/doc/ostree.repo-config.xml
new file mode 100644
index 00000000..07244d03
--- /dev/null
+++ b/doc/ostree.repo-config.xml
@@ -0,0 +1,123 @@
+<?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 2014 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.repo-config">
+
+  <refentryinfo>
+    <title>ostree.repo-config</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.repo-config</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>ostree.repo-config</refname>
+    <refpurpose>OSTree repository configuration</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>
+      The <filename>config</filename> file in an OSTree
+      repository is a "keyfile" in the <ulink
+      url="http://standards.freedesktop.org/desktop-entry-spec/latest/">XDG
+      Desktop Entry Specification</ulink> format.  It has
+      several global flags, as well as zero or more remote
+      entries which describe how to access remote
+      repositories.
+    </para>
+    
+    <para>
+      See <citerefentry><refentrytitle>ostree.repo</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information
+      about OSTree repositories.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>[core] Section Options</title>
+
+    <para>
+      Repository-global options.  The following entries are defined:
+    </para>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>mode</varname></term>
+        <listitem><para>One of <literal>bare</literal> or <literal>archive-z2</literal>.  </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>repo_version</varname></term>
+        <listitem><para>Currently, this must be set to <literal>1</literal>.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>[remote "name"] Section Options</title>
+    
+    <para>
+      Describes a remote repository location.
+    </para>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>url</varname></term>
+        <listitem><para>Must be present; declares URL for accessing
+        this remote.  The only supported schemes are the moment are
+        <literal>file</literal>, <literal>http</literal>, and
+        <literal>https</literal>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>gpg-verify</varname></term>
+        <listitem><para>A boolean value, defaults to <tt>true</tt>.
+        Controls whether or not OSTree will require commits to be
+        signed by a known GPG key.  For more information, see the
+        <citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        manual under GPG.</para></listitem>
+      </varlistentry>
+    </variablelist>
+
+  </refsect1>
+  
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>ostree.repo</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+</refentry>
diff --git a/doc/ostree.repo.xml b/doc/ostree.repo.xml
new file mode 100644
index 00000000..eb9e3292
--- /dev/null
+++ b/doc/ostree.repo.xml
@@ -0,0 +1,94 @@
+<?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 2014 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.repo">
+
+        <refentryinfo>
+                <title>ostree.repo</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.repo</refentrytitle>
+                <manvolnum>5</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>ostree.repo</refname>
+                <refpurpose>OSTree repository configuration and layout</refpurpose>
+        </refnamediv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>
+		  An OSTree repository is structurally similar to a
+		  git repository; it is a content-addressed object
+		  store containing filesystem trees.  However, unlike
+		  git, ostree is designed to store operating system
+		  binaries.  It records the Unix uid and gid,
+		  permissions, as well as extended attributes.
+		</para>
+		
+		<para>
+		  A repository can be in one of two modes;
+		  <literal>bare</literal>, which is designed as a hard
+		  link source for operating system checkouts, and
+		  <literal>archive-z2</literal>, which is designed for
+		  static HTTP servers.
+		</para>
+
+		<para>
+		  There is a system repository located at
+		  <filename>/ostree/repo</filename>.  If no repository
+		  is specified, the <command>ostree</command> as well
+		  as many API calls will use it by default.
+		</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Components of a repository</title>
+
+		<para>
+		  The only user-editable component is the
+		  <filename>config</filename> file.  For more
+		  information, see <citerefentry><refentrytitle>ostree.repo-config</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+		</para>
+	</refsect1>
+
+        <refsect1>
+                <title>See Also</title>
+                <para>
+                        <citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>ostree.repo-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+		</para>
+	</refsect1>
+</refentry>