From a71d550860e68be2b177d9016fe0227f1a547269 Mon Sep 17 00:00:00 2001
From: Colin Walters <walters@verbum.org>
Date: Thu, 23 Feb 2017 18:01:28 -0500
Subject: [PATCH] man/repo-config: Document mirrorlist

We should get more strict about docs. Add some text about `contenturl` and
mirrorlists.

Closes: #709
Approved by: jlebon
---
 man/ostree.repo-config.xml | 40 ++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/man/ostree.repo-config.xml b/man/ostree.repo-config.xml
index b4c276df..d187f89f 100644
--- a/man/ostree.repo-config.xml
+++ b/man/ostree.repo-config.xml
@@ -127,10 +127,16 @@ Boston, MA 02111-1307, USA.
     <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>
+        <listitem><para>Must be present; declares URL for accessing metadata and
+        content for remote. See also <literal>contenturl</literal>. The
+        supported schemes are documented below.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>contenturl</varname></term>
+        <listitem><para>Declares URL for accessing content (filez, static delta
+        parts). When specified, <literal>url</literal> is used just for
+        metadata: summary, static delta "superblocks".</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -201,6 +207,32 @@ Boston, MA 02111-1307, USA.
     </para>
   </refsect1>
 
+  <refsect1>
+    <title>Repository url/contenturl</title>
+    <para>
+      Originally, OSTree had just a <literal>url</literal> option
+      for remotes.  Since then, the <literal>contenturl</literal>
+      option was introduced.  Both of these support 
+      <literal>file</literal>, <literal>http</literal>, and
+      <literal>https</literal> schemes.
+    </para>
+    <para>
+      Additionally, both of these can be prefixed with the string
+      <literal>mirrorlist=</literal>, which instructs the client
+      that the target url is a "mirrorlist" format, which is
+      a plain text file of newline-separated URLs.  Earlier
+      URLs will be given precedence.
+    </para>
+    <para>
+      Note that currently, the <literal>tls-ca-path</literal> and
+      <literal>tls-client-cert-path</literal> options apply to every HTTP
+      request, even when <literal>contenturl</literal> and/or
+      <literal>mirrorlist</literal> are in use. This may change in the future to
+      only apply to metadata (i.e. <literal>url</literal>, not
+      <literal>contenturl</literal>) fetches.
+    </para>
+  </refsect1>
+
   <refsect1>
     <title>Per-remote GPG keyrings and verification</title>
     <para>