From 154be392632ffb5a95cce71a824ede728f32dd09 Mon Sep 17 00:00:00 2001 From: Carl Hetherington Date: Mon, 28 Jan 2019 22:25:07 +0000 Subject: [PATCH] Manual updates. --- doc/manual/.gitignore | 3 + doc/manual/Makefile | 15 +++- doc/manual/cli.py | 49 +++++++++++++ doc/manual/config.py | 6 +- doc/manual/dcpomatic.xml | 115 ++++++++++++++---------------- doc/manual/diagrams/dcp-refer.svg | 87 +++++++++++----------- 6 files changed, 162 insertions(+), 113 deletions(-) create mode 100644 doc/manual/.gitignore create mode 100644 doc/manual/cli.py diff --git a/doc/manual/.gitignore b/doc/manual/.gitignore new file mode 100644 index 000000000..8b8714fbf --- /dev/null +++ b/doc/manual/.gitignore @@ -0,0 +1,3 @@ +dcpomatic_create.xml +dcpomatic_kdm_cli.xml +dcpomatic_cli.xml \ No newline at end of file diff --git a/doc/manual/Makefile b/doc/manual/Makefile index cb8c9bc01..8d9ee9149 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -66,13 +66,22 @@ diagrams/%.pdf: diagrams/%.svg inkscape -z -f $< --export-pdf $@ --export-area-drawing config.xml: ../../src/lib/config.cc config.py - python config.py ../../src/lib/config.cc > config.xml + python3 config.py ../../src/lib/config.cc > config.xml + +dcpomatic_create.xml: ../../src/tools/dcpomatic_create.cc cli.py + python3 cli.py dcpomatic_create > dcpomatic_create.xml + +dcpomatic_cli.xml: ../../src/tools/dcpomatic_cli.cc cli.py + python3 cli.py dcpomatic_cli > dcpomatic_cli.xml + +dcpomatic_kdm_cli.xml: ../../src/tools/dcpomatic_kdm_cli.cc cli.py + python3 cli.py dcpomatic_kdm_cli > dcpomatic_kdm_cli.xml # # HTML # -html: $(XML) config.xml dcpomatic-html.xsl extensions-html.ent dcpomatic.css \ +html: $(XML) config.xml dcpomatic-html.xsl extensions-html.ent dcpomatic.css dcpomatic_create.xml dcpomatic_cli.xml dcpomatic_kdm_cli.xml \ $(addprefix html/screenshots/,$(SCREENSHOTS)) \ $(subst .svg,.png,$(addprefix diagrams/,$(DIAGRAMS))) \ @@ -92,7 +101,7 @@ html: $(XML) config.xml dcpomatic-html.xsl extensions-html.ent dcpomatic.css \ # PDF # -pdf: $(XML) config.xml dcpomatic-pdf.xsl extensions-pdf.ent \ +pdf: $(XML) config.xml dcpomatic-pdf.xsl extensions-pdf.ent dcpomatic_create.xml dcpomatic_cli.xml dcpomatic_kdm_cli.xml \ $(addprefix screenshots/,$(SCREENSHOTS)) \ $(subst .svg,.pdf,$(addprefix diagrams/,$(DIAGRAMS))) diff --git a/doc/manual/cli.py b/doc/manual/cli.py new file mode 100644 index 000000000..3a2493b4d --- /dev/null +++ b/doc/manual/cli.py @@ -0,0 +1,49 @@ +#!/usr/bin/python3 +import subprocess +import os +import sys + +print('') +print('') + +os.chdir('../..') +for l in subprocess.run(['run/%s' % sys.argv[1], '--help'], stderr=subprocess.PIPE).stderr.splitlines(): + l = l.strip().decode('UTF-8') + if not l.startswith('-'): + continue + + s = l.split() + print('', end='') + + e = 0 + n = 0 + if l.startswith('-') and not l.startswith('--'): + print('%s, ' % s[0][:-1], end='') + n = 1 + e = len(s[0]) + 2 + + if l.find('<') != -1: + print('%s %s' % (s[n], s[n+1].replace('<', '<').replace('>', '>')), end='') + e += len(s[n]) + len(s[n+1]) + 1 + else: + print('%s' % s[n], end='') + e += len(s[n]) + + desc = l[e:].strip() + fixed_desc = '' + t = False + for i in desc: + if i == '"' and t == False: + fixed_desc += '“' + t = True + elif i == '"' and t == True: + fixed_desc += '”' + t = False + else: + fixed_desc += i + + print(' — %s' % fixed_desc) + +print('') +print('', end='') +os.chdir('doc/manual') diff --git a/doc/manual/config.py b/doc/manual/config.py index 673174bf2..9b3c8e20f 100644 --- a/doc/manual/config.py +++ b/doc/manual/config.py @@ -2,7 +2,7 @@ import sys current_tag = None current_doc = None current_opt = False -print '' +print('') with open(sys.argv[1]) as f: for line in f: line = line.strip(); @@ -19,6 +19,6 @@ with open(sys.argv[1]) as f: optional = ' (optional)' else: optional = '' - print '<%s>%s — %s' % (current_tag, optional, current_doc.strip()) + print('<%s>%s — %s' % (current_tag, optional, current_doc.strip())) current_tag = None -print '' +print('') diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml index 1ee817b5d..72bbedb56 100644 --- a/doc/manual/dcpomatic.xml +++ b/doc/manual/dcpomatic.xml @@ -107,7 +107,8 @@ version. If you are still using Windows XP, download the specific XP version as it should be more stable on your machine than the ‘normal’ -Windows version. +Windows version. Be aware, though, that support for Windows XP will +not last forever and you should plan to upgrade if at all possible. @@ -224,7 +225,7 @@ directory: -./waf configure +./waf configure --disable-tests ./waf build sudo ./waf install @@ -240,11 +241,40 @@ dcpomatic2 in a shell. + + + +
+‘Simple’ and ‘Full’ modes + +When you start DCP-o-matic for the first time it will ask you if +you want to use ‘simple’ or ‘full’ mode. + + +The difference between these two is that some of DCP-o-matic's +more complex or less-used controls are hidden from view in +‘Simple’ mode. This makes the interface simpler to +navigate. You may wish to choose this mode if you do not have much +experience with video processing. + + +Even if you choose ‘Simple’ mode you can always go +back to ‘Full’ mode by changing the Interface +complexity setting in the General tab +of Preferences. + + + +All the screenshots in this manual are from a copy of DCP-o-matic in ‘Full’ mode. +
+ + + Creating a DCP from a video @@ -500,21 +530,21 @@ to encode a single frame which it can then repeat. Manipulating existing DCPs -Frequently DCP-o-matic is used to take content in formats such as MP4 -and convert it to JPEG2000 for a DCP. It can also be used -to take existing DCPs and modify them in various ways. +DCP-o-matic is often used to take content in formats such as MP4 and +make it into a DCP. It can also be used to take existing DCPs and +modify them in various ways.
Importing a DCP into DCP-o-matic -If you want to do something to an existing DCP the first step is to -import it. Click Add DCP... 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 very slow as decoding of DCPs is almost as -computationally intensive as encoding them. +The first step in manipulating an existing DCP is to import it. Click +Add DCP... 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 +decoding of DCPs is almost as computationally intensive as encoding +them. @@ -602,8 +632,8 @@ the following content settings: -If you do change any of these settings on a piece of DCP content -DCP-o-matic will decode and then re-encode the JPEG2000 data. +DCP-o-matic will be forced to decode and re-encode your JPEG2000 data +if you change any of these settings on a piece of DCP content.
@@ -989,7 +1019,7 @@ linkend="tab-colour-conversion"/>. -sRGBStill images in RGB, e.g. photographs. +sRGBStill images in RGB, e.g. photographs. Rec. 601Standard-definition content (fewer than about 1000 pixels across) including DVD rips. @@ -2177,7 +2207,7 @@ linkend="fig-kdm"/>. KDM dialog - + @@ -2317,7 +2347,7 @@ DCP-o-matic. Its window is shown in . The KDM creator - + @@ -3137,8 +3167,8 @@ The Frame Rate control in the DCP tab sets the video frame rate that the DCP will use. Clicking Use best sets the rate to what DCP-o-matic thinks is the best for your content. With this -button, DCP-o-matic assumes that the whole range of frame rates (24, -25, 30 and 48fps) are allowable. +button, DCP-o-matic assumes that the most commonly-working frame rates (24, +25 and 30fps) are allowed. @@ -3362,7 +3392,7 @@ to the cinema which is showing your DCP. - dcpomatic2_create [OPTION] [CONTENT] [<CONTENT> ...] + dcpomatic2_create [OPTION] <CONTENT> [[OPTION] <CONTENT> ...] @@ -3380,20 +3410,7 @@ to the cinema which is showing your DCP. The options are: - - -v, --version — show DCP-o-matic version - -h, --help — show this help - -n, --name — <name> film name - -t, --template <name> — template name - -c, --dcp-content-type <type> — FTR, SHR, TLR, TST, XSN, RTG, TSR, POL, PSA or ADV - --container-ratio <ratio> — 119, 133, 137, 138, 166, 178, 185 or 239 - --content-ratio <ratio> — 119, 133, 137, 138, 166, 178, 185 or 239 - -s, --still-length <n> — number of seconds that still content should last - --standard <standard> — SMPTE or interop (default SMPTE) - --no-use-isdcf-name> — do not use an ISDCF name; use the specified name unmodified - --no-sign— do not sign the DCP - -o, --output <dir> — output directory - + For example, to setup a film using a MP4 file you might do: @@ -3423,21 +3440,7 @@ to the cinema which is showing your DCP. dcpomatic2_cli [OPTION] [FILM] - - - -v, --version — show DCP-o-matic version - -h, --help — show this help - -f, --flags — show flags passed to C++ compiler on build - -n, --no-progress — do not print progress to stdout - -r, --no-remote — do not use any remote servers - -t, --threads — specify number of local encoding threads (overriding configuration) - -j, --json <port> — run a JSON server on the specified port - -k, --keep-going — keep running even when the job is complete - -s, --servers — just display a list of encoding servers that DCP-o-matic is configured to use; don't encode - -d, --dcp-path — echo DCP's path to stdout on successful completion (implies -n) - --dump — just dump a summary of the film's settings; don't encode - - + For example, to encode a film called my_film you might do: @@ -3459,21 +3462,7 @@ to the cinema which is showing your DCP. dcpomatic2_kdm_cli [OPTION] <FILM|CPL-ID> - - - -o, --output — output file or directory - -f, --valid-from — valid from time (in local time zone of the cinema) (e.g. "2013-09-28 01:41:51") or "now" - -t, --valid-to — valid to time (in local time zone of the cinema) (e.g. "2014-09-28 01:41:51") - -d, --valid-duration — valid duration (e.g. "1 day", "4 hours", "2 weeks") - --formulation — modified-transitional-1, dci-any or dci-specific [default modified-transitional-1] - -z, --zip — ZIP each cinema's KDMs into its own file - -v, --verbose — be verbose - -c, --cinema — specify a cinema, either by name or email address - --certificate — file containing projector certificate - --cinemas — list known cinemas from the DCP-o-matic settings - --dkdm-cpls — list CPLs for which DCP-o-matic has DKDMs - - + diff --git a/doc/manual/diagrams/dcp-refer.svg b/doc/manual/diagrams/dcp-refer.svg index d9a6024a7..6fb5a0c35 100644 --- a/doc/manual/diagrams/dcp-refer.svg +++ b/doc/manual/diagrams/dcp-refer.svg @@ -14,7 +14,7 @@ height="1052.3622047" id="svg2" version="1.1" - inkscape:version="0.48.4 r9939" + inkscape:version="0.92.3 (2405546, 2018-03-11)" sodipodi:docname="dcp-refer.svg"> Picture + y="100.85927" + style="font-size:14px;line-height:1.25">Picture Sound + y="153.35434" + style="font-size:14px;line-height:1.25">Sound Subtitle + x="89.917862" + y="181.92085" + style="font-size:14px;line-height:1.25">Subtitle #1 Content DCP + y="38.171349" + style="font-size:16px;line-height:1.25">Content DCP Subtitle + x="354.96677" + y="112.09619" + style="font-size:14px;line-height:1.25">Subtitle #2 New DCP + y="38.171349" + style="font-size:16px;line-height:1.25">New DCP Refer to picture + y="61.941441" + style="font-size:16px;line-height:1.25">Refer to picture Refer to sound + style="color:#000000;font-size:16px;line-height:1.25;font-family:'latin modern roman';-inkscape-font-specification:'latin modern roman';display:inline;overflow:visible;visibility:visible;fill:#00aad4;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;marker:none;enable-background:accumulate">Refer to sound Make DCP + y="109.97685" + style="font-size:16px;line-height:1.25">Make DCP -- 2.30.2