Adjust some form for clarity and readability

7 files changed, 74 insertions, 83 deletions

diff --git a/specs/storing-trust-c.xml b/specs/storing-trust-c.xml
index be71d79..eb6e106 100644
--- a/specs/storing-trust-c.xml
+++ b/specs/storing-trust-c.xml
@@ -8,12 +8,15 @@
 		is callable from C, there is likely a need for a simpler C API and ABI to
 		access the trust information.</para>
 
-	<para><emphasis>Work item: </emphasis> At the present time no C caller for
+	<note>
+		<title>Work item</title>
+		<para>At the present time no C caller for
 		such an API exists. Most crypto libraries already use PKCS#11 to access
 		keys and certificates, and thus they are not the consumer for this C API.
 		It is also undesirable to design an API in a vacuum. Therefore if you are
 		such an interested caller, please contact
 		<ulink url="http://lists.freedesktop.org/mailman/listinfo/p11-glue">p11-glue@lists.freedesktop.org</ulink>
 		for discussion.</para>
+	</note>
 
 </article>
diff --git a/specs/storing-trust-dbus.xml b/specs/storing-trust-dbus.xml
index f9a17f7..60018db 100644
--- a/specs/storing-trust-dbus.xml
+++ b/specs/storing-trust-dbus.xml
@@ -9,11 +9,14 @@
 		privilege escalation (polkit prompting) to modify the system
 		wide trust stores.</para>
 
-	<para><emphasis>Work item: </emphasis> We need to look at the interested DBus
+	<note>
+		<title>Work item</title>
+		<para>We need to look at the interested DBus
 		callers and discuss the desired form.  It is undesirable to design an
 		API in a vacuum. Therefore if you are such an interested caller,
 		please contact
 		<ulink url="http://lists.freedesktop.org/mailman/listinfo/p11-glue">p11-glue@lists.freedesktop.org</ulink>
 		for discussion.</para>
+	</note>
 
 </article>
diff --git a/specs/storing-trust-existing.xml b/specs/storing-trust-existing.xml
index 0cd2b1e..9629bea 100644
--- a/specs/storing-trust-existing.xml
+++ b/specs/storing-trust-existing.xml
@@ -2,27 +2,7 @@
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 ]>
 <article id="storing-trust-existing">
-<title>Existing Trust Storage Implementations</title>
-
-<articleinfo>
-	<releaseinfo>Take two draft</releaseinfo>
-	<date>June 2013</date>
-	<authorgroup>
-		<author>
-			<firstname>Stef</firstname>
-			<surname>Walter</surname>
-			<affiliation>
-				<orgname>Red Hat Inc.</orgname>
-				<address>
-					<email>stefw@redhat.com</email>
-				</address>
-			</affiliation>
-		</author>
-	</authorgroup>
-</articleinfo>
-
-<sect1 id="existing">
-	<title>Existing Representations of Trust Policy</title>
+	<title>Existing Trust Storage Implementations</title>
 
 	<para>Obviously if a comprehensive, future-proof and realistic standard
 		representation of out-of-band trust policy exists, we should not define a
@@ -30,7 +10,7 @@
 		examine	the various representations in use, and why they are insufficient
 		to provide such a comprehensive standard.</para>
 
-	<sect2 id="nss-trust-objects">
+	<sect1 id="nss-trust-objects">
 		<title>NSS Trust Objects</title>
 
 		<para>Internally NSS represents out-of-band trust policy using PKCS#11
@@ -148,7 +128,7 @@
 		</varlistentry>
 		</variablelist>
 
-		<sect3 id="nss-trust-problems">
+		<sect2 id="nss-trust-problems">
 			<title>Deficiencies</title>
 			<para>NSS trust objects have been around for nearly two decades. They may
 				have been sufficient in the past but are showing their age.</para>
@@ -175,10 +155,10 @@
 				acceptable object model for representing out-of-band trust policy,
 				for a standard representation it cannot be the only one.</para></listitem>
 			</itemizedlist>
-		</sect3>
-	</sect2>
+		</sect2>
+	</sect1>
 
-	<sect2 id="openssl-trusted">
+	<sect1 id="openssl-trusted">
 		<title>OpenSSL Trusted Certificates</title>
 		<para>OpenSSL contains a representation of out-of-band trust policy in its 
 			<literal>TRUSTED CERTIFICATE</literal> PEM blocks aka. CertAux.
@@ -215,7 +195,7 @@ CertAux ::= SEQUENCE {
 			ExtendedKeyUsage certificate extension. The other fields are
 			not related to trust policy.</para>
 
-		<sect3 id="openssl-trusted-problems">
+		<sect2 id="openssl-trusted-problems">
 			<title>Deficiencies</title>
 
 			<para>This representation seems to be designed to solve a specific use
@@ -236,18 +216,18 @@ CertAux ::= SEQUENCE {
 				is awkward to parse especially when using other and/or strict
 				DER parsers.</para></listitem>
 			</itemizedlist>
-		</sect3>
-	</sect2>
+		</sect2>
+	</sect1>
 
 
-	<sect2 id="trust-assertions">
+	<sect1 id="trust-assertions">
 		<title>Trust Assertions</title>
 
 		<para>Trust Assertions are the author's previous attempt to solve the problem of sharing
 			trust policy information. Details about this are available online
 				<footnote><para><ulink url="http://p11-glue.freedesktop.org/doc/pkcs11-trust-assertions/">Storing Trust Assertions in PKCS#11 Modules</ulink></para></footnote>.</para>
 
-		<sect3 id="trust-assertion-problems">
+		<sect2 id="trust-assertion-problems">
 			<title>Deficiencies</title>
 
 			<para>Although claiming to solve the problem of out-of-band trust policy
@@ -270,10 +250,10 @@ CertAux ::= SEQUENCE {
 			<para>In addition claims of extensibility and generality proved hard
 				to implement in the real world, and trust assertions ended up
 				as a far more constrained concept that initially envisioned.</para>
-		</sect3>
-	</sect2>
+		</sect2>
+	</sect1>
 
-	<sect2 id="ca-bundles">
+	<sect1 id="ca-bundles">
 		<title>Certificate Authority Bundles</title>
 
 		<para>A bundle is either a file or directory containing one or more X.509
@@ -283,7 +263,7 @@ CertAux ::= SEQUENCE {
 		<para>They are usually stored in the OpenSSL PEM format, but may also be
 			seen in the Java Keystore format, and others.</para>
 
-		<sect3 id="ca-bundle-problems">
+		<sect2 id="ca-bundle-problems">
 			<title>Deficiencies</title>
 
 			<para>Although widely used today certificate authority bundles have
@@ -303,8 +283,7 @@ CertAux ::= SEQUENCE {
 				rather than as an anchor, the certificate validation will
 				not respect such a removal.</para></listitem>
 			</itemizedlist>
-		</sect3>
-	</sect2>
-</sect1>
+		</sect2>
+	</sect1>
 
 </article>
diff --git a/specs/storing-trust-json.xml b/specs/storing-trust-json.xml
index 31bdef5..272b363 100644
--- a/specs/storing-trust-json.xml
+++ b/specs/storing-trust-json.xml
@@ -8,11 +8,14 @@
 		there is likely a need to have a standard JSON form for the the models
 		described in these documents.</para>
 
-	<para><emphasis>Work item: </emphasis> We need to look at the interested JSON
+	<note>
+		<title>Work Item</title>
+		<para>We need to look at the interested JSON
 		callers and discuss the desired form.  It is undesirable to design an
 		API in a vacuum. Therefore if you are such an interested caller,
 		please contact
 		<ulink url="http://lists.freedesktop.org/mailman/listinfo/p11-glue">p11-glue@lists.freedesktop.org</ulink>
 		for discussion.</para>
+	</note>
 
 </article>
diff --git a/specs/storing-trust-model.xml b/specs/storing-trust-model.xml
index 2aa218c..d958832 100644
--- a/specs/storing-trust-model.xml
+++ b/specs/storing-trust-model.xml
@@ -4,23 +4,6 @@
 <article id="storing-trust-model">
 <title>Model: Anchors and Blacklists</title>
 
-<articleinfo>
-	<releaseinfo>Take two draft</releaseinfo>
-	<date>June 2013</date>
-	<authorgroup>
-		<author>
-			<firstname>Stef</firstname>
-			<surname>Walter</surname>
-			<affiliation>
-				<orgname>Red Hat Inc.</orgname>
-				<address>
-					<email>stefw@redhat.com</email>
-				</address>
-			</affiliation>
-		</author>
-	</authorgroup>
-</articleinfo>
-
 <sect1 id="introduction">
 	<title>Introduction</title>
 
diff --git a/specs/storing-trust-pkcs11.xml b/specs/storing-trust-pkcs11.xml
index c104ac4..843cf07 100644
--- a/specs/storing-trust-pkcs11.xml
+++ b/specs/storing-trust-pkcs11.xml
@@ -2,7 +2,7 @@
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 ]>
 <article id="storing-trust-pkcs11">
-<title>Representation: PKCS#11</title>
+	<title>Representation: PKCS#11</title>
 
 	<para><ulink url="http://www.cryptsoft.com/pkcs11doc/">PKCS#11</ulink> is a useful
 		and widely supported standard for storage and use of keys and certificates.
@@ -11,8 +11,8 @@
 	<para>Here we outline how to use PKCS#11 as a store for trust policy, containing sets
 		for anchors, blacklist, and stapled extensions.</para>
 
-<sect1 id="pkcs11-store">
-	<title>Stores</title>
+<simplesect id="pkcs11-store">
+	<title>Store representation</title>
 
 	<para>We define a trust store using the stardard PKCS#11 object model, with a few
 		new attributes.</para>
@@ -116,9 +116,9 @@
 		</varlistentry>
 	</variablelist>
 
-</sect1>
+</simplesect>
 
-<sect1 id="pkcs11-anchors">
+<simplesect id="pkcs11-anchors">
 	<title>Set: Anchors</title>
 
 	<para>The standard <literal>CKA_TRUSTED</literal> boolean attribute is used
@@ -168,9 +168,9 @@
 	<para>Note that the presence of a BasicConstraints extension marks it as a
 		certificate authority anchor, capable of anchoring a certificate chain,
 		and not just itself.</para>
-</sect1>
+</simplesect>
 
-<sect1 id="pkcs11-blacklist">
+<simplesect id="pkcs11-blacklist">
 	<title>Set: Blacklist</title>
 
 	<para>We define a new boolean attribute CKA_X_DISTRUSTED to indicate
@@ -217,9 +217,9 @@
 
 	<para>Other standard PKCS#11 fields should be present on the objects as per
 		the <literal>CKA_CLASS</literal> attribute.</para>
-</sect1>
+</simplesect>
 
-<sect1>
+<simplesect>
 	<title>Set: Stapled Extensions</title>
 
 	<para>A new object class is defined of type <literal>CKO_X_CERTIFICATE_EXTENSION</literal>. Each 
@@ -245,7 +245,7 @@
 			X.509.</para></listitem>
 		</varlistentry>
 		<varlistentry>
-			<term>CKA_VALUE</term>
+			<term><literal>CKA_VALUE</literal></term>
 			<listitem><para>The DER encoded value of the Extension sequence as
 				defined in X.509</para></listitem>
 		</varlistentry>
@@ -254,15 +254,19 @@
 	<para>In addition the PKCS#11 <emphasis>Common Storage Object Attributes</emphasis> may
 	be present, as well as the <literal>CKA_ID</literal> attribute.</para>
 
-</sect1>
+</simplesect>
 
-<sect1 id="pkcs11-constants">
+<simplesect id="pkcs11-constants">
 	<title>Constants</title>
 
-	<para><emphasis>Work item:</emphasis> Define vendor extension constants for the above
+	<note>
+		<title>Work Item</title>
+		<para>Define vendor extension constants for the above
 		new attributes. One of the attributes CKA_PUBLIC_KEY_INFO may be standardized
 		by the PKCS#11 TC within the next short while, thus not rushing to do this. Will
 		timeout if not done shortly.</para>
-</sect1>
+	</note>
+
+</simplesect>
 
 </article>
diff --git a/specs/storing-trust-policy.xml b/specs/storing-trust-policy.xml
index 3b22553..82252cb 100644
--- a/specs/storing-trust-policy.xml
+++ b/specs/storing-trust-policy.xml
@@ -5,7 +5,7 @@
 	<title>Storing Trust Policy</title>
 
 	<bookinfo>
-		<releaseinfo>Take two draft</releaseinfo>
+		<releaseinfo>Revision: Take two</releaseinfo>
 		<date>June 2013</date>
 		<authorgroup>
 			<author>
@@ -18,17 +18,20 @@
 					</address>
 				</affiliation>
 			</author>
+			<author>
+				<othername>... with a lot of insight from others</othername>
+			</author>
 		</authorgroup>
 	</bookinfo>
 
 	<preface id="status">
 		<title>Status of this document</title>
-	
+
 		<para>This document is in a state of construction. I applaud those who wish to join
 			in and participate. Many things like footnotes, clarifications are missing.
 			There is some editorializing that should not be in the final.
 			Comments, including nit picking, are welcome.</para>
-	
+
 		<para>The 
 			<ulink url="http://lists.freedesktop.org/mailman/listinfo/p11-glue">p11-glue@lists.freedesktop.org</ulink>
 			mailing list is the preferred venue for discussion.</para>
@@ -36,14 +39,27 @@
 
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 		href="storing-trust-model.xml"/>
-	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
-		href="storing-trust-pkcs11.xml"/>
-	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
-		href="storing-trust-c.xml"/>
-	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
-		href="storing-trust-json.xml"/>
-	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
-		href="storing-trust-dbus.xml"/>
+
+	<part>
+		<title>Concrete Representations</title>
+
+		<partintro>
+			<para>In order to make sense of the following concrete representations
+			it's helpful to be familiar with the
+			<link linkend="storing-trust-model">abstract model</link> being implicitly
+			referenced here.</para>
+		</partintro>
+
+		<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+			href="storing-trust-pkcs11.xml"/>
+		<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+			href="storing-trust-c.xml"/>
+		<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+			href="storing-trust-json.xml"/>
+		<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+			href="storing-trust-dbus.xml"/>
+	</part>
+
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 		href="storing-trust-retrofit.xml"/>
 	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"