From: ancient-skyscraper <bwb+dcpomaticcom@gibibyte.com>
Date: Thu, 9 Mar 2023 19:16:56 +0000 (-0500)
Subject: Update documentation and CLI UI with hint info
X-Git-Tag: v2.16.48~14
X-Git-Url: https://git.carlh.net/gitweb/?p=dcpomatic.git;a=commitdiff_plain;h=b4ab9f4adc9dd10d0f1a33286d78821da580a4d1

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 dd59facfa..81321a83d 100644
--- 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
-<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
diff --git a/src/tools/dcpomatic_cli.cc b/src/tools/dcpomatic_cli.cc
index f4359ce86..40461b794 100644
--- 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"
-	     << "      --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";
 }
@@ -488,6 +488,9 @@ main (int argc, char* argv[])
 			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);
 		}
 	}