Manual tweaks.
[dcpomatic.git] / doc / manual / dcpomatic.xml
index 19551d0086442483c35ad36d15bd4f8081190556..cd2974dcb6c965d011af815d42e5c9499344ad26 100644 (file)
@@ -26,15 +26,15 @@ Hello, and welcome to DCP-o-matic!
 <section>
 <title>What is DCP-o-matic?</title>
 
-<para>DCP-o-matic is a set of programs to allow you to:</para>
+<para>DCP-o-matic is a set of tools to allow you to:</para>
 
 <itemizedlist>
   <listitem>Create <ulink
   url="https://en.wikipedia.org/wiki/Digital_Cinema_Package">Digital
   Cinema Packages</ulink> (DCPs) from video, audio, subtitle and closed-caption files.</listitem>
-  <listitem>Play and verify DCPs.</listitem>
-  <listitem>Create KDMs for DCPs.</listitem>
-  <listitem>Write cinema-format drives containing DCPs.</listitem>
+  <listitem>Play and verify DCPs (see <xref linkend="ch-player"/> and <xref linkend="ch-verifier"/>).</listitem>
+  <listitem>Create KDMs for DCPs (see <xref linkend="ch-encryption"/>).</listitem>
+  <listitem>Write cinema-format drives containing DCPs (see <xref linkend="ch-writer"/>).</listitem>
 </itemizedlist>
 
 </section>
@@ -108,7 +108,7 @@ You may find that DCP-o-matic crashes if run the 32-bit version on a CPU with mo
 <title>macOS</title>
 
 <para>
-DCP-o-matic versions 2.16.0 and higher will run on macOS version 10.10 (Yosemite) and
+DCP-o-matic versions 2.16.0 and higher will run on macOS version 10.8 (Mountain Lion) 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
@@ -121,7 +121,7 @@ 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.
+If you are using macOS 10.7 (Lion) or older you will need to install the latest 2.14.x version of DCP-o-matic.
 </para>
 
 </section>
@@ -162,7 +162,7 @@ thanks to Stefan Karner.
 <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>
+There are instructions for how to do it on <ulink url="https://dcpomatic.com/building">https://dcpomatic.com/</ulink>
 </para>
 </section>
 </chapter>
@@ -422,21 +422,6 @@ to encode a single frame which it can then repeat.
 </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>
@@ -1913,7 +1898,7 @@ into reels:
 The picture, sound and subtitle data of the DCP will be
 split up into more smaller files on disk, rather than fewer larger
 files.  This can be useful if the DCP is to be transferred on storage
-that have file size limits.  The FAT32 filesystem, for example, can
+that has a file size limit.  The FAT32 filesystem, for example, can
 only hold files smaller than 4Gb.  A 6Gb DCP with a single reel could
 not be transferred using a FAT32-formatted disk.  If that DCP were
 split up into two 3Gb reels it could be transferred.
@@ -3302,7 +3287,7 @@ There are two options for the encoding server;
 <code>dcpomatic_server_cli</code>, which runs on the command line, and
 <code>dcpomatic_server</code>, which has a simple GUI.  The command line
 version is well-suited to headless servers, especially on Linux, and
-the GUI version works best on Windows where it will put an icon in the
+the GUI version works best on Windows and macOS where it will put an icon in the
 system tray.
 </para>
 
@@ -3770,7 +3755,7 @@ The full details of OV and VF files are discussed in <xref linkend="sec-overlay"
   <title>Verifying DCPs</title>
 
   <para>
-    The player also offers a DCP verifier.  To check a DCP,
+    The DCP-o-matic Player (see <xref linkend="ch-player"/>) also offers a DCP verifier.  To check a DCP,
     open it and then select <guilabel>Verify DCP</guilabel> from the
     <guilabel>Tools</guilabel> menu.
   </para>
@@ -3807,6 +3792,139 @@ The full details of OV and VF files are discussed in <xref linkend="sec-overlay"
 </chapter>
 
 
+<!-- ============================================================== -->
+<chapter xml:id="ch-writer">
+<title>Writing DCPs to disks</title>
+
+<para>
+Once you have your DCP, you need to get it to the cinema or theater who
+will play it. Sometimes this is possible via the internet, using a
+service such as Filemail. If that's an option: go for it! Network
+transfers avoid a lot of the difficulties that other methods have.
+</para>
+
+<para>
+However, your DCP may be too large to make that practical. In that case,
+the usual approach is to copy the DCP onto a USB hard drive or stick and
+physically take it or send it to the cinema.
+</para>
+
+<section>
+<title>Hard drive formatting</title>
+
+<para>
+In theory, this should be as simple as dragging and dropping the DCP's
+files onto a USB-connected drive. Sadly, though, things are not always
+that simple. This is because not all hard drives are formatted in the
+same way. The most common formats for hard drives are:
+</para>
+
+<itemizedlist>
+<listitem>APFS &mdash; used by macOS 10.13 and later for solid state drives (SSDs).</listitem>
+<listitem>HFS+ (Mac OS Extended) &mdash; used by macOS on 10.12 and earlier, and on all macOS systems for spinning disks.</listitem>
+<listitem>NTFS &mdash; modern format used by Windows.</listitem>
+<listitem>ExFAT &mdash; another modern, but less common (and buggier) format used by Windows.</listitem>
+<listitem>FAT32 &mdash; old format used by Windows.</listitem>
+<listitem>ext2, ext3, ext4 &mdash; often used by Linux.</listitem>
+</itemizedlist>
+
+<para>
+You can format a drive however you want, but a drive set up on macOS will usually use APFS, just as one set up on Windows will probably use NTFS or ExFAT.
+</para>
+
+<para>
+The problem you have as a DCP maker is: the only format that is
+guaranteed to work in all cinemas is ext2. This format is not easy to
+use directly from Windows or macOS: both operating systems need extra
+software to write ext2 drives.
+</para>
+
+<para>
+The &ldquo;DCP-o-matic Disk Writer&rdquo; provides a possible
+solution to this problem.  It allows you to format and copy DCPs onto ext2-formatted disks from Windows, macOS or Linux.
+</para>
+
+</section>
+
+
+<section>
+<title>Caution</title>
+
+<para>
+DCP-o-matic is made by one developer in his spare time. As a project,
+we do not have any quality assurance department, testing team or
+anything like that. Though we try our best to ensure quality using
+automated testing, and by the great efforts of our users to find and report problems,
+bugs do get into the code and things do go wrong.
+</para>
+
+<para>
+Though very undesirable, bugs in most parts of DCP-o-matic are usually
+not disastrous; they most often result in an error message, or some
+problem with a DCP. The Disk Writer tool, however, is a bit different.  It obtains
+permission from your operating system to write directly to disks connected to the
+computer.  Though we have done as much as we can to prevent problems, there is a chance
+that a bug in the Disk Writer could cause irretrievable data loss (for example, if
+the writer wrote to the wrong drive by mistake).
+</para>
+
+<para>
+No such problems have been reported, nor found by us during testing, but I would
+like to warn you that they are possible.  As always, make sure that you have backups
+(somewhere that is not directly connected to your computer) of anything that you do not want
+to lose.
+</para>
+
+</section>
+
+
+<section>
+<title>Writing a DCP to a disk</title>
+
+<para>
+Starting up the Disk Writer will give open a confirmation window to make sure that you understand the risks involved, as shown in <xref linkend="fig-disk-writer-notice"/>.
+</para>
+
+<figure id="fig-disk-writer-notice">
+  <title>Starting the Disk Writer</title>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="screenshots/disk-writer-notice&scs;"/>
+    </imageobject>
+  </mediaobject>
+</figure>
+
+<para>
+If you are sure you want to continue, type <code>I am sure</code> into the text box and click <guilabel>OK</guilabel>.  This will open the window shown in <xref linkend="fig-disk-writer"/>.
+</para>
+
+<figure id="fig-disk-writer">
+  <title>Starting the Disk Writer</title>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="screenshots/disk-writer&scs;"/>
+    </imageobject>
+  </mediaobject>
+</figure>
+
+<para>Next, click <guilabel>Open...</guilabel> and choose the DCP that you want to write.</para>
+
+<para>
+Now we need to choose the drive that the DCP will be written to from the drop-down menu.
+<emphasis>Whichever drive you choose will be irretrievably wiped!</emphasis>
+If the drive you want is not listed, click <guilabel>Refresh</guilabel> to search the system for drives.
+</para>
+
+<para>
+Finally, click <guilabel>Copy DCP</guilabel>.  After a confirmation window, the drive will be formatted,
+and the DCP copied and then read back to check that it was written correctly.
+</para>
+
+</section>
+
+</chapter>
+
+
 <!-- ============================================================== -->
 <chapter>
 <title>Keyboard shortcuts</title>