Update documentation and CLI UI with hint info

Goal is to explain what hints are, and how the `--hints` option
changes behavior of `dcpomatic2_cli` command

diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml
index dd59facfaaea35df14b7a3b39ddf0586f3090010..81321a83d4954e20918266c7145b7a13d107338e 100644 (file)
--- a/doc/manual/dcpomatic.xml
+++ b/doc/manual/dcpomatic.xml
@@ -320,7 +320,20 @@ making the DCP.</para>
 
 <para>
 Choose <guilabel>Make DCP</guilabel> from the
 
 <para>
 Choose <guilabel>Make DCP</guilabel> from the

-<guilabel>Jobs</guilabel> menu.  DCP-o-matic will encode your DCP.
+<guilabel>Jobs</guilabel> menu.  Before encoding your DCP, DCP-o-matic
+will run a series of checks on your film to look for various conditions
+that might cause problems when playing back the DCP.  If any potential
+problems are found, DCP-o-matic will show you a list of hints.
+Each hint describes the condition that was found and gives
+advice on how to resolve it.  If hints are found and reported, you can
+either <guilabel>Make DCP</guilabel> anyway (without adjusting any
+settings), or <guilabel>Go back</guilabel> in order to make
+adjustments before encoding the DCP.
+</para>
+
+<para>
+If no hints were found (or you pressed <guilabel>Make DCP</guilabel>
+after hints were displayed), DCP-o-matic will encode your DCP.

 This may take some time (many hours in some cases).  While the job is
 in progress, DCP-o-matic will update you on how it is getting on with
 the progress bar in the bottom of its window, as shown in <xref
 This may take some time (many hours in some cases).  While the job is
 in progress, DCP-o-matic will update you on how it is getting on with
 the progress bar in the bottom of its window, as shown in <xref

diff --git a/src/tools/dcpomatic_cli.cc b/src/tools/dcpomatic_cli.cc
index f4359ce86ddb3248b10782bee531608bd3bb7393..40461b7949d338300a07dee27ac9a5b0f9b5f90a 100644 (file)
--- a/src/tools/dcpomatic_cli.cc
+++ b/src/tools/dcpomatic_cli.cc
@@ -78,7 +78,7 @@ help (string n)
             << "      --no-check                    don't check project's content files for changes before making the DCP\n"
             << "      --export-format <format>      export project to a file, rather than making a DCP: specify mov or mp4\n"
             << "      --export-filename <filename>  filename to export to with --export-format\n"
             << "      --no-check                    don't check project's content files for changes before making the DCP\n"
             << "      --export-format <format>      export project to a file, rather than making a DCP: specify mov or mp4\n"
             << "      --export-filename <filename>  filename to export to with --export-format\n"

-            << "      --hints                       show hints and stop if any are given\n"
+            << "      --hints                       analyze film for hints before encoding and abort if any are found\n"

             << "\n"
             << "<FILM> is the film directory.\n";
 }
             << "\n"
             << "<FILM> is the film directory.\n";
 }


@@ -488,6 +488,9 @@ main (int argc, char* argv[])
                        for (auto hint: hints) {
                                std::cout << word_wrap("* " + hint, 70) << "\n";
                        }
                        for (auto hint: hints) {
                                std::cout << word_wrap("* " + hint, 70) << "\n";
                        }

+                       std::cout << "*** Encoding aborted because hints were found ***\n\n";
+                       std::cout << "Modify your settings and run the command again, or run without\n";
+                       std::cout << "the `--hints' option to ignore these hints and encode anyway.\n";

                        exit(EXIT_FAILURE);
                }
        }
                        exit(EXIT_FAILURE);
                }
        }