Some manual tidying.

[dcpomatic.git] / doc / manual / dcpomatic.xml

diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml
index 22d566af8596b0ab1da958dff0e6fcd5820ee23f..0354d6b550aef8d871414cc38cef7036652e9a4c 100644 (file)
--- a/doc/manual/dcpomatic.xml
+++ b/doc/manual/dcpomatic.xml
@@ -96,12 +96,8 @@ DCP-o-matic will be installed onto your machine.
 </para>
 
 <para>
 </para>
 
 <para>

-If you are using a 32-bit version of Windows, you will need the 32-bit
-installer.  For 64-bit Windows, either installer will work, but I
-suggest you use the 64-bit version as it will allow DCP-o-matic to
-use more memory.  You may find that DCP-o-matic crashes if you run
-many parallel encoding threads (more than 4) on the 32-bit
-version.
+Use the 64-bit installer unless you are using a 32-bit version of Windows.
+You may find that DCP-o-matic crashes if run the 32-bit version on a CPU with more than 4 cores.

 </para>
 
 </section>
 </para>
 
 </section>


@@ -112,8 +108,8 @@ version.
 <title>macOS</title>
 
 <para>
 <title>macOS</title>
 
 <para>

-DCP-o-matic will run on macOS version 10.10 (Yosemite) and
-higher.  DCP-o-matic is split into seven separate applications, each of
+DCP-o-matic versions 2.16.0 and higher will run on macOS version 10.10 (Yosemite) and
+higher.  DCP-o-matic is split into eight separate applications, each of

 which can be installed by downloading the <code>.dmg</code>,
 double-clicking to open and then dragging the icon to your
 <guilabel>Applications</guilabel> folder.
 which can be installed by downloading the <code>.dmg</code>,
 double-clicking to open and then dragging the icon to your
 <guilabel>Applications</guilabel> folder.


@@ -124,6 +120,10 @@ If you don't know which parts of DCP-o-matic to install, start
 with the first (main) part.
 </para>
 
 with the first (main) part.
 </para>
 

+<para>
+If you are using macOS 10.9 (Mavericks) or older you will need to install the latest 2.14.x version of DCP-o-matic.
+</para>
+

 </section>
 
 <!-- ============================================================== -->
 </section>
 
 <!-- ============================================================== -->


@@ -158,14 +158,11 @@ thanks to Stefan Karner.
 </section>
 
 <section>
 </section>
 
 <section>

-        <title>
-                Building from source
-        </title>
-        <para>
-                Since DCP-o-matic is open-source you can also build it yourself, though this can be quite a difficult process (especially on Windows and macOS).  There are instructions for how to do it on
-        <ulink url="https://dcpomatic.com/development">
-                https://dcpomatic.com/
-        </ulink>
+<title>Building from source</title>
+<para>
+Since DCP-o-matic is open-source you can also build it yourself,
+though this can be quite a difficult process (especially on Windows and macOS).
+There are instructions for how to do it on <ulink url="https://dcpomatic.com/development">https://dcpomatic.com/</ulink>

 </para>
 </section>
 </chapter>
 </para>
 </section>
 </chapter>


@@ -192,15 +189,19 @@ movie <ulink url="http://sintel.org/">Sintel</ulink> from <ulink
 url="https://download.blender.org/durian/trailer/Sintel_Trailer.480p.DivX_Plus_HD.mkv">their
 website</ulink>.  Generally one would want to use the
 highest-resolution material available, but for this test we will use
 url="https://download.blender.org/durian/trailer/Sintel_Trailer.480p.DivX_Plus_HD.mkv">their
 website</ulink>.  Generally one would want to use the
 highest-resolution material available, but for this test we will use

-the low-resolution version to save everyone's bandwidth bills.
+the low-resolution version to save on download time.

 </para>
 
 <para>
 Now, start DCP-o-matic and its window will open.  First, we will
 create a new &lsquo;film&rsquo;.  A &lsquo;film&rsquo; is how DCP-o-matic refers to
 some pieces of content, along with some settings, which we will make into
 </para>
 
 <para>
 Now, start DCP-o-matic and its window will open.  First, we will
 create a new &lsquo;film&rsquo;.  A &lsquo;film&rsquo; is how DCP-o-matic refers to
 some pieces of content, along with some settings, which we will make into

-a DCP.  DCP-o-matic stores its data in a folder on your disk while it
-creates the DCP.  You can create a new film by selecting
+a DCP.  DCP-o-matic stores its &lsquo;film&rsquo; data in a folder on your disk while it
+creates the DCP.
+</para>
+
+<para>
+You can create a new film by selecting

 <guilabel>New</guilabel> from the <guilabel>File</guilabel> menu, as
 shown in <xref linkend="fig-file-new"/>.
 </para>
 <guilabel>New</guilabel> from the <guilabel>File</guilabel> menu, as
 shown in <xref linkend="fig-file-new"/>.
 </para>


@@ -231,7 +232,7 @@ linkend="fig-video-new-film"/>.
 <para>
 In this dialogue box you can choose a name for the film.  This will be
 used to name the folder to store its data in, and also as the initial
 <para>
 In this dialogue box you can choose a name for the film.  This will be
 used to name the folder to store its data in, and also as the initial

-name for the DCP itself.  You can also choose whereabouts you want to create
+name for the DCP itself.  You can also choose where you want to create

 the film.  In the example from the figure, DCP-o-matic will create a
 folder called &lsquo;DCP Test&rsquo; inside my existing folder <code>DCP</code> into which it
 will write its working files.
 the film.  In the example from the figure, DCP-o-matic will create a
 folder called &lsquo;DCP Test&rsquo; inside my existing folder <code>DCP</code> into which it
 will write its working files.


@@ -331,9 +332,8 @@ linkend="fig-making-dcp"/>.
 </figure>
 
 <para>
 </figure>
 
 <para>

-When it has finished, the DCP will end up on your disk inside the
-film's folder.  You can then copy this to a projector via a USB
-stick, hard-drive or network connection.  See <xref
+When it has finished, the DCP will be written into its own folder inside the film's folder.
+You can copy this to a projector via a USB stick, hard-drive or network connection.  See <xref

 linkend="ch-files"/> for details about the files that DCP-o-matic creates.
 </para>
 
 linkend="ch-files"/> for details about the files that DCP-o-matic creates.
 </para>
 


@@ -422,6 +422,21 @@ to encode a single frame which it can then repeat.
 </chapter>
 
 
 </chapter>
 
 

+<!-- ============================================================== -->
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" id="ch-disk-writer">
+<title>Writing DCP drives</title>
+
+<para>
+Once a DCP has been created it must often be transferred to a cinema for playback.  The most reliable way to do this is to write a specially-formatted drive (in the ext2 format) containing your DCP.
+</para>
+
+<para>
+Writing ext2-formatted drives is difficult from macOS and Windows without custom software.  DCP-o-matic includes a tool called the &lsquo;DCP-o-matic Disk Writer&rsquo; which makes it easy.
+</para>
+
+</chapter>
+
+

 <!-- ============================================================== -->
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" id="ch-manipulating-existing-dcps">
 <title>Manipulating existing DCPs</title>
 <!-- ============================================================== -->
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" id="ch-manipulating-existing-dcps">
 <title>Manipulating existing DCPs</title>


@@ -439,7 +454,7 @@ modify them in various ways.
 The first step in manipulating an existing DCP is to import it.  Click
 <guilabel>Add DCP...</guilabel> and select your DCP's folder.  It will
 be added to the DCP-o-matic project.  If the DCP is unencrypted you
 The first step in manipulating an existing DCP is to import it.  Click
 <guilabel>Add DCP...</guilabel> and select your DCP's folder.  It will
 be added to the DCP-o-matic project.  If the DCP is unencrypted you

-can preview it in the normal way, though playback will be slow as
+can preview it in the normal way, though playback may be slow as

 decoding of DCPs is almost as computationally intensive as encoding
 them.
 </para>
 decoding of DCPs is almost as computationally intensive as encoding
 them.
 </para>


@@ -641,12 +656,14 @@ example, a JPEG, PNG or TIFF file.
 images which should be treated as the frames of a video.
 </listitem>
 
 images which should be treated as the frames of a video.
 </listitem>
 

-<listitem>Subtitle &mdash; a file containing subtitle which will be
+<listitem>Subtitle &mdash; a file containing subtitles which will be

 superimposed on the image of the DCP.  These can be
 <guilabel>.srt</guilabel>, <guilabel>.ssa</guilabel>, <guilabel>.ass</guilabel> or <guilabel>.xml</guilabel>
 superimposed on the image of the DCP.  These can be
 <guilabel>.srt</guilabel>, <guilabel>.ssa</guilabel>, <guilabel>.ass</guilabel> or <guilabel>.xml</guilabel>

-files.</listitem>
+files.  Subtitle files can also be used to make closed captions.</listitem> 

 
 <listitem>DCP &mdash; an existing DCP.</listitem>
 
 <listitem>DCP &mdash; an existing DCP.</listitem>

+
+<listitem>ATMOS MXFs &mdash; if you have Dolby ATMOS content in MXF format (created using Dolby's tools) you can add it to a DCP just like any other content.</listitem>

 </itemizedlist>
 
 <para>
 </itemizedlist>
 
 <para>


@@ -749,7 +766,7 @@ linkend="sec-prefs-keys"/>).
 
 <!-- ============================================================== -->
 <section>
 
 <!-- ============================================================== -->
 <section>

-<title>Content Properties</title>
+<title>Content properties</title>

 
 <para>
 Below the content list are the controls to set content properties.  To
 
 <para>
 Below the content list are the controls to set content properties.  To


@@ -2168,7 +2185,7 @@ methods to understand it.
 
 <para>
 We suppose that we are trying to send a DCP to
 
 <para>
 We suppose that we are trying to send a DCP to

-Alice's cinema without an attacker called Mallory being able to
+Alice's cinema without a third party called Mallory being able to

 watch it himself.
 </para>
 
 watch it himself.
 </para>
 


@@ -2224,7 +2241,7 @@ certificate so that others can make encrypted DCPs for DCP-o-matic.
 We take our DCP's symmetric key and encrypt it using the public key of
 Alice's projector.  We send the result to Alice over email (using a
 format called a Key Delivery Message, or KDM).  Her projector then
 We take our DCP's symmetric key and encrypt it using the public key of
 Alice's projector.  We send the result to Alice over email (using a
 format called a Key Delivery Message, or KDM).  Her projector then

-decrypts our message using its private key, yielding the magic
+decrypts our message using its private key, giving the

 symmetric key which can decrypt the DCP.
 </para>
 
 symmetric key which can decrypt the DCP.
 </para>
 


@@ -3736,7 +3753,7 @@ The full details of OV and VF files are discussed in <xref linkend="sec-overlay"
 </chapter>
 
 <chapter xml:id="ch-player" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
 </chapter>
 
 <chapter xml:id="ch-player" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">

-  <title>Playing and verifying DCPs</title>
+  <title>Playing DCPs</title>

 
   <para>DCP-o-matic includes a DCP player, and although it requires a
   very high-speed CPU to play DCPs in full resolution, it can also
 
   <para>DCP-o-matic includes a DCP player, and although it requires a
   very high-speed CPU to play DCPs in full resolution, it can also


@@ -3762,14 +3779,53 @@ The full details of OV and VF files are discussed in <xref linkend="sec-overlay"
   resolution.
   </para>
 
   resolution.
   </para>
 

+</chapter>
+
+
+<chapter xml:id="ch-verifier" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+  <title>Verifying DCPs</title>
+

   <para>
   <para>

-    The player also offers a simple DCP validator.  To check a DCP,
+    The player also offers a DCP checker.  To check a DCP,

     open it and then select <guilabel>Verify DCP</guilabel> from the
     open it and then select <guilabel>Verify DCP</guilabel> from the

-    <guilabel>Tools</guilabel> menu.  This will run some basic checks to see if the DCP meets the required standards.
+    <guilabel>Tools</guilabel> menu.
+  </para>
+
+  <para>
+    The validator will report three kinds of problems:

   </para>
 
   </para>
 

+  <itemizedlist>
+  <listitem>Errors &mdash; serious problems with the DCP that are likely to cause problems on playback.</listitem>
+  <listitem>Bv2.1 errors &mdash; errors described by the <ulink url="https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=9161348">SMPTE Bv2.1 standard</ulink>.</listitem>
+  <listitem>Warnings &mdash; small problems that may not matter.</listitem>
+  </itemizedlist>
+
+  <section>
+  <title>Errors</title>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="verify_errors.xml"/>
+  </section>
+
+  <section>
+  <title>Bv2.1 errors</title>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="verify_bv21_errors.xml"/>
+  </section>
+
+  <section>
+  <title>Warnings</title>
+  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="verify_warnings.xml"/>
+  </section>
+

 </chapter>
 
 </chapter>
 

+
+<!-- ============================================================== -->
+<chapter>
+<title>Keyboard shortcuts</title>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="shortcuts.xml"/>
+</chapter>
+
+

 <!-- ============================================================== -->
 <chapter xml:id="ch-config" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
 <title>Configuration files</title>
 <!-- ============================================================== -->
 <chapter xml:id="ch-config" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
 <title>Configuration files</title>