From a88987fc65e006a8e5cbc983252302784136c39c Mon Sep 17 00:00:00 2001
From: Carl Hetherington <cth@carlh.net>
Date: Mon, 22 Aug 2016 15:44:13 +0100
Subject: [PATCH] Add some stuff about KDM types to the manual.

---
 doc/manual/dcpomatic-html.xsl | 14 ++++++++++++++
 doc/manual/dcpomatic-pdf.xsl  | 14 ++++++++++++++
 doc/manual/dcpomatic.css      | 16 +++++++++++++++-
 doc/manual/dcpomatic.xml      | 29 +++++++++++++++++++++++++++++
 4 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/doc/manual/dcpomatic-html.xsl b/doc/manual/dcpomatic-html.xsl
index 144675d47..72863d7db 100644
--- a/doc/manual/dcpomatic-html.xsl
+++ b/doc/manual/dcpomatic-html.xsl
@@ -9,4 +9,18 @@
 <!-- I can't fathom xmlto's logic with image scaling, so I've turned it off -->
 <xsl:param name="ignore.image.scaling" select="1"/>
 
+<!-- <note> in a div with no heading -->
+<xsl:template name="note.frobozz">
+  <xsl:param name="content">
+    <xsl:apply-templates/>
+  </xsl:param>
+  <xsl:text disable-output-escaping="yes">&lt;div class="note"&gt;</xsl:text>
+  <xsl:copy-of select="$content"/>
+  <xsl:text disable-output-escaping="yes">&lt;/div&gt;</xsl:text>
+</xsl:template>
+
+<xsl:template match="note">
+  <xsl:call-template name="note.frobozz"/>
+</xsl:template>
+
 </xsl:stylesheet>
diff --git a/doc/manual/dcpomatic-pdf.xsl b/doc/manual/dcpomatic-pdf.xsl
index a2a950f0a..06f083866 100644
--- a/doc/manual/dcpomatic-pdf.xsl
+++ b/doc/manual/dcpomatic-pdf.xsl
@@ -28,4 +28,18 @@
   <xsl:call-template name="inline.frobozz"/>
 </xsl:template>
 
+<!-- <note> in a box with \dbend -->
+<xsl:template name="note.frobozz">
+  <xsl:param name="content">
+    <xsl:apply-templates/>
+  </xsl:param>
+  <xsl:text>\begin{center}\fbox{\begin{minipage}{0.8\textwidth}\raisebox{10pt}{\dbend}\quad</xsl:text>
+  <xsl:copy-of select="$content"/>
+  <xsl:text>\end{minipage}}\end{center}\par</xsl:text>
+</xsl:template>
+
+<xsl:template match="note">
+  <xsl:call-template name="note.frobozz"/>
+</xsl:template>
+
 </xsl:stylesheet>
diff --git a/doc/manual/dcpomatic.css b/doc/manual/dcpomatic.css
index 566f09e63..ad003e33c 100644
--- a/doc/manual/dcpomatic.css
+++ b/doc/manual/dcpomatic.css
@@ -26,4 +26,18 @@ span.guilabel {
     padding-bottom: 1px;
     padding-left: 3px;
     padding-right: 3px;
-}
\ No newline at end of file
+}
+
+div.note {
+    border-width: 1px;
+    border-style: solid;
+    background-color: #FFEBCF;
+    padding-top: 12pt;
+    padding-bottom: 12pt;
+    padding-left: 12pt;
+    padding-right: 12pt;
+    margin-left: 24pt;
+    margin-right: 24pt;
+    margin-top: 18pt;
+    margin-bottom: 18pt;
+}
diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml
index aa31b47cd..56200c6ed 100644
--- a/doc/manual/dcpomatic.xml
+++ b/doc/manual/dcpomatic.xml
@@ -58,6 +58,20 @@ GPL</ulink>.
 This manual uses icons from the <ulink url="http://tango.freedesktop.org/">Tango Desktop Project</ulink>, with thanks.
 </para>
 
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>This manual</title>
+
+<para>
+This manual presents bits of DCP-o-matic's user interface (such as menu items or buttons) <guilabel>like this</guilabel>.
+</para>
+
+<note>
+Notes of an advanced nature are presented like this.  Ignore them unless you want to know the gory details.
+</note>
+
 </section>
 </chapter>
 
@@ -2048,6 +2062,21 @@ You must also select the type of KDM that you want to generate.  If in
 doubt, use <guilabel>Modified Transitional 1</guilabel>.
 </para>
 
+<note>
+The differences between the three KDM types are fairly subtle.
+<guilabel>DCI Specific</guilabel> and <guilabel>DCI Any</guilabel> add
+a <code>&lt;ContentAuthenticator&gt;</code> tag to the KDM which
+allows the exhibitor to check that the DCP and KDM have come from a
+bona-fide source.  In addition, <guilabel>DCI Specific</guilabel> adds
+information on trusted devices to the KDM.  This allows the KDM
+creator to specify devices (such as sound processors) that are allowed
+to use keys delivered by the KDM.  At present it is not clear how
+widely the <guilabel>DCI Specific</guilabel> and <guilabel>DCI
+Any</guilabel> features are supported (or even tolerated) by servers
+so you are advised to use <guilabel>Modified Transitional
+1</guilabel>.
+</note>
+
 <para>
 Finally, choose what you want to do with the KDMs.  They can be
 written to disk, to a location that you can specify by clicking
-- 
2.30.2