Incorporate editorial changes from m-holger

Jay Berkenbilt
1 parent 7dd5f312
Showing 5 changed files with 154 additions and 136 deletions
generate_auto_job
job.sums
libqpdf/qpdf/auto_job_help.hh
manual/cli.rst
manual/qdf.rst
@@ -159,8 +159,11 @@ class Main:
                 if long_text == '':
                     raise Exception(f'missing long text for {topic}')
                 long_text += '\n'
-                for i in re.finditer(r'--help=([^\.\s]+)', long_text):
-                    self.referenced_topics.add(i.group(1))
+                if topic != '--help':
+                    # Help for --help itself has --help=... not
+                    # referring to specific options.
+                    for i in re.finditer(r'--help=([^\.\s]+)', long_text):
+                        self.referenced_topics.add(i.group(1))
                 return True
             return False
 # Generated by generate_auto_job
-generate_auto_job 8efd9e2fa9d517ceb80404f1779f37de194df32a422f0beca30a2b47cc64d816
+generate_auto_job bc2f0e8cecebe8b11950cf37714a646fd5a1d294839b748d1c499353226dd642
 include/qpdf/auto_job_c_att.hh 7ad43bb374c1370ef32ebdcdcb7b73a61d281f7f4e3f12755585872ab30fb60e
 include/qpdf/auto_job_c_copy_att.hh 32275d03cdc69b703dd7e02ba0bbe15756e714e9ad185484773a6178dc09e1ee
 include/qpdf/auto_job_c_enc.hh 72e138c7b96ed5aacdce78c1dec04b1c20d361faec4f8faf52f64c1d6be99265
@@ -8,8 +8,8 @@ include/qpdf/auto_job_c_pages.hh 931840b329a36ca0e41401190e04537b47f2867671a6643
 include/qpdf/auto_job_c_uo.hh 0585b7de459fa479d9e51a45fa92de0ff6dee748efc9ec1cedd0dde6cee1ad50
 job.yml 1590fd16fd17ed40db9aa56b6713c844cfd61b3a6d0441a3ccd122b7371c68e9
 libqpdf/qpdf/auto_job_decl.hh 9f79396ec459f191be4c5fe34cf88c265cf47355a1a945fa39169d1c94cf04f6
-libqpdf/qpdf/auto_job_help.hh 524e8123152df496794954d16a556d5fee9c76ec6a7f5a6b8f9d2b59c1719e10
+libqpdf/qpdf/auto_job_help.hh 05cddfb81ed7fb58a8249b912890e560cb76bd51389d64eae6c662ca552c87d9
 libqpdf/qpdf/auto_job_init.hh 3b6323189480a7d782563c9d2b5bc29b8dcd19c6dcc89840b207e38cb503d3f1
 libqpdf/qpdf/auto_job_schema.hh 1c3b4b5488270f8d200ed345573e3a241f15baff6fb7e97ec3d044103b2546d9
 manual/_ext/qpdf.py e9ac9d6c70642a3d29281ee5ad92ae2422dee8be9306fb8a0bc9dba0ed5e28f3
-manual/cli.rst 06785f88a28703da0f6d81b6983ae6c09aa1dd8cd958fb5058d56177da431c6c
+manual/cli.rst 9aecd2905844fbda5cd528afd7fedef693ac0958bcb20e235f1c8e10a1896abe
@@ -54,8 +54,11 @@ ap.addOptionHelp(&quot;--completion-zsh&quot;, &quot;completion&quot;, &quot;enable zsh completion&quot;, R&quot;(O
 ap.addHelpTopic("help", "information about qpdf", R"(Help options provide some information about qpdf itself. Help
 options are only valid as the first and only command-line argument.
 )");
-ap.addOptionHelp("--help", "help", "provide help", R"(Display help information. Run qpdf --help for information about
-how to get help on various topics.
+ap.addOptionHelp("--help", "help", "provide help", R"(--help[=--option|topic]
+
+--help: provide general information and a list of topics
+--help=--option: provide help on a specific option
+--help=topic: provide help on a topic
 )");
 ap.addOptionHelp("--version", "help", "show qpdf version", R"(Display the version of qpdf.
 )");
@@ -70,7 +73,7 @@ directly related to the operation it is performing.
 ap.addOptionHelp("--password", "general", "specify password", R"(--password=password
 Specify a password for an encrypted, password-protected file.
-Not needed for encrypted files with no password.
+Not needed for encrypted files without a password.
 )");
 ap.addOptionHelp("--password-file", "general", "read password from a file", R"(--password-file=filename
@@ -119,9 +122,9 @@ ap.addOptionHelp(&quot;--password-is-hex-key&quot;, &quot;advanced-control&quot;, &quot;provide hex-encod
 string rather than supplying a password. This is an expert
 option.
 )");
-ap.addOptionHelp("--suppress-password-recovery", "advanced-control", "don't try different password encodings", R"(Suppress qpdf's behavior of attempting different encodings of a
-password that contains non-ASCII Unicode characters if the first
-attempt doesn't succeed.
+ap.addOptionHelp("--suppress-password-recovery", "advanced-control", "don't try different password encodings", R"(Suppress qpdf's usual behavior of attempting different encodings
+of a password that contains non-ASCII Unicode characters if the
+first attempt doesn't succeed.
 )");
 ap.addOptionHelp("--password-mode", "advanced-control", "tweak how qpdf encodes passwords", R"(--password-mode=mode
@@ -139,7 +142,7 @@ the structure without changing the content.
 )");
 ap.addOptionHelp("--linearize", "transformation", "linearize (web-optimize) output", R"(Create linearized (web-optimized) output files.
 )");
-ap.addOptionHelp("--encrypt", "transformation", "start encryption options", R"(--encrypt user-password owner-password key-length [ options ] --
+ap.addOptionHelp("--encrypt", "transformation", "start encryption options", R"(--encrypt user-password owner-password key-length [options] --
 Run qpdf --help=encryption for details.
 )");
@@ -159,12 +162,12 @@ If the file named in --copy-encryption requires a password, use
 this option to supply the password.
 )");
 ap.addOptionHelp("--qdf", "transformation", "enable viewing PDF code in a text editor", R"(Create a PDF file suitable for viewing in a text editor and even
-editing. This is to edit the PDF code, not the page contents.
+editing. This is for editing the PDF code, not the page contents.
 All streams that can be uncompressed are uncompressed, and
 content streams are normalized, among other changes. The
 companion tool "fix-qdf" can be used to repair hand-edited QDF
-files. QDF is a feature specific to the qpdf tool. There is a
-chapter about it in the manual.
+files. QDF is a feature specific to the qpdf tool. Please see
+the "QDF Mode" chapter in the manual.
 )");
 ap.addOptionHelp("--no-original-object-ids", "transformation", "omit original object IDs in qdf", R"(Omit comments in a QDF file indicating the object ID an object
 had in the original file.
@@ -256,8 +259,11 @@ default is 1,024. Use 0 for no minimum.
 )");
 ap.addOptionHelp("--min-version", "transformation", "set minimum PDF version", R"(--min-version=version
-Force the PDF version of the output to be at least the
-specified version.
+Force the PDF version of the output to be at least the specified
+version. The version number format is
+"major.minor[.extension-level]", which sets the version header
+to "major.minor" and the extension level, if specified, to
+"extension-level".
 )");
 ap.addOptionHelp("--force-version", "transformation", "set output PDF version", R"(--force-version=version
@@ -281,7 +287,7 @@ from the resulting set, not based on the original page numbers.
 ap.addHelpTopic("modification", "change parts of the PDF", R"(Modification options make systematic changes to certain parts of
 the PDF, causing the PDF to render differently from the original.
 )");
-ap.addOptionHelp("--pages", "modification", "begin page selection", R"(--pages file [ --password=password ] [ page-range ] [ ... ] --
+ap.addOptionHelp("--pages", "modification", "begin page selection", R"(--pages file [--password=password] [page-range] [...] --
 Run qpdf --help=page-selection for details.
 )");
@@ -312,12 +318,12 @@ File names are generated from the specified output file as follows:
 Page ranges are single page numbers for single-page groups or first-last
 for multi-page groups.
 )");
-ap.addOptionHelp("--overlay", "modification", "begin overlay options", R"(--overlay file [ options ] --
+ap.addOptionHelp("--overlay", "modification", "begin overlay options", R"(--overlay file [options] --
 Overlay pages from another file on the output.
 Run qpdf --help=overlay-underlay for details.
 )");
-ap.addOptionHelp("--underlay", "modification", "begin underlay options", R"(--underlay file [ options ] --
+ap.addOptionHelp("--underlay", "modification", "begin underlay options", R"(--underlay file [options] --
 Underlay pages from another file on the output.
 Run qpdf --help=overlay-underlay for details.
@@ -375,7 +381,7 @@ ap.addOptionHelp(&quot;--remove-page-labels&quot;, &quot;modification&quot;, &quot;remove explicit page n
 )");
 ap.addHelpTopic("encryption", "create encrypted files", R"(Create encrypted files. Usage:
---encrypt user-password owner-password key-length [ options ] --
+--encrypt user-password owner-password key-length [options] --
 Either or both of user-password and owner-password may be empty
 strings. key-length may be 40, 128, or 256. Encryption options are
@@ -523,13 +529,13 @@ should not be used except for compatibility testing.
 )");
 ap.addHelpTopic("page-selection", "select pages from one or more files", R"(Use the --pages option to select pages from multiple files. Usage:
-qpdf in.pdf --pages input-file [ --password=password ] [ page-range ] \
-    [ ... ] -- out.pdf
+qpdf in.pdf --pages input-file [--password=password] [page-range] \
+    [...] -- out.pdf
 Between --pages and the -- that terminates pages option, repeat
 the following:
-filename [ --password=password ] [ page-range ]
+filename [--password=password] [page-range]
 Document-level information, such as outlines, tags, etc., is taken
 from in.pdf and is preserved in out.pdf. You can use --empty in place
@@ -571,10 +577,10 @@ the destination page and may obscure the page. Underlaid pages are
 drawn below the destination page. Usage:
 {--overlay | --underlay } file
-      [ --password=password ]
-      [ --to=page-range ]
-      [ --from=[page-range] ]
-      [ --repeat=page-range ]
+      [--password=password]
+      [--to=page-range]
+      [--from=[page-range]]
+      [--repeat=page-range]
       --
 Note the use of "--" by itself to terminate overlay/underlay options.
@@ -84,7 +84,7 @@ Basic Invocation
 ::
-   Usage: qpdf infile [ options ] [ outfile ]
+   Usage: qpdf infile [options] [outfile]
 The :command:`qpdf` command reads the PDF file :samp:`{infile}`,
 applies various transformations or modifications to the file in
@@ -294,14 +294,17 @@ are only valid as the first and only command-line argument.
 Related Options
 ~~~~~~~~~~~~~~~
-.. qpdf:option:: --help
+.. qpdf:option:: --help[=--option|topic]
    .. help: provide help
-      Display help information. Run qpdf --help for information about
-      how to get help on various topics.
+      --help: provide general information and a list of topics
+      --help=--option: provide help on a specific option
+      --help=topic: provide help on a topic
-   Display command-line invocation help.
+   Display command-line invocation help. Use :samp:`--help={--option}`
+   for help on a specific option and :samp:`--help={topic}` for help
+   on a help topic and also provides a list of available help topics.
 .. qpdf:option:: --version
@@ -357,7 +360,7 @@ Related Options
    .. help: specify password
       Specify a password for an encrypted, password-protected file.
-      Not needed for encrypted files with no password.
+      Not needed for encrypted files without a password.
    Specifies a password for accessing encrypted, password-protected
    files. To read the password from a file or standard input, you can
@@ -385,7 +388,8 @@ Related Options
    password for accessing encrypted files. :samp:`{filename}` may be
    ``-`` to read the password from standard input, but if you do that
    the password is echoed and there is no prompt, so use ``-`` with
-   caution.
+   caution. Note that leading and trailing spaces are not stripped
+   from the password.
 .. qpdf:option:: --verbose
@@ -407,9 +411,9 @@ Related Options
       Indicate progress when writing files.
    Indicate progress while writing output files. Progress indication
-   does not start until writing starts, so if complicated
-   transformations are being applied before the write process begins,
-   there may be a delay before progress indicators are seen.
+   does not start until writing starts, so there may be a delay before
+   progress indicators are seen if complicated transformations are
+   being applied before the write process begins.
 .. qpdf:option:: --no-warn
@@ -435,23 +439,25 @@ Related Options
       information, such as the page contents. Does not use the file's
       name or attributes or the current time.
-   Generate of a secure, random document ID using deterministic
-   values. This prevents use of timestamp and output file name
-   information in the ID generation. Instead, at some slight
-   additional runtime cost, the ID field is generated to include a
-   digest of the significant parts of the content of the output PDF
-   file. This means that a given qpdf operation should generate the
-   same ID each time it is run, which can be useful when caching
-   results or for generation of some test data. Use of this flag is
-   not compatible with creation of encrypted files.
-
-   Note that there is *no guarantee* that different versions of qpdf
-   will generate the same deterministic ID given the same generation
-   code and input. While care is taken to avoid gratuitous changes,
-   new versions of qpdf may include changes that affect the output.
-   This option can be useful for testing. See also
+   Generate a secure, random document ID using deterministic values.
+   This prevents use of timestamp and output file name information in
+   the ID generation. Instead, at some slight additional runtime cost,
+   the ID field is generated to include a digest of the significant
+   parts of the content of the output PDF file. This means that a
+   given qpdf operation should generate the same ID each time it is
+   run, which can be useful when caching results or for generation of
+   some test data. Use of this flag is not compatible with creation of
+   encrypted files. This option can be useful for testing. See also
    :qpdf:ref:`--static-id`.
+   While qpdf will generate the same deterministic ID given the same
+   output PDF, there is no guarantee that different versions of qpdf
+   will generate exactly the same PDF output for the same input and
+   options. While care is taken to avoid gratuitous changes to qpdf's
+   PDF generation, new versions of qpdf may include changes or bug
+   fixes that cause slightly different PDF code to be generated. Such
+   changes are noted in the release notes.
+
 .. qpdf:option:: --allow-weak-crypto
    .. help: allow insecure cryptographic algorithms
@@ -561,9 +567,9 @@ Related Options
    .. help: don't try different password encodings
-      Suppress qpdf's behavior of attempting different encodings of a
-      password that contains non-ASCII Unicode characters if the first
-      attempt doesn't succeed.
+      Suppress qpdf's usual behavior of attempting different encodings
+      of a password that contains non-ASCII Unicode characters if the
+      first attempt doesn't succeed.
    Ordinarily, qpdf attempts to automatically compensate for passwords
    encoded with the wrong character encoding. This option suppresses
@@ -666,8 +672,8 @@ The options discussed in this section tell qpdf to apply
 transformations that change the structure of a PDF file without
 changing its content. Examples include creating linearized
 (web-optimized) files, adding or removing encryption, restructuring
-files for older viewers, and rewriting files for human inspection,
-among others. See also :ref:`modification-options`.
+files for older viewers, and rewriting files for human inspection. See
+also :ref:`modification-options`.
 Related Options
 ~~~~~~~~~~~~~~~
@@ -685,17 +691,14 @@ Related Options
    important cross-reference information typically appears at the end
    of the file.
-.. qpdf:option:: --encrypt user-password owner-password key-length [ options ] --
+.. qpdf:option:: --encrypt user-password owner-password key-length [options] --
    .. help: start encryption options
       Run qpdf --help=encryption for details.
    This flag starts encryption options, used to create encrypted
-   files.
-
-   Please see :ref:`encryption-options` for details about creating
-   encrypted files.
+   files. Please see :ref:`encryption-options` for details.
 .. qpdf:option:: --decrypt
@@ -720,19 +723,19 @@ Related Options
       preserving the input file's encryption. Use --encryption-file-password
       to specify the encryption file's password.
-   Copy encryption parameters, including the user password, the owner
-   password, and all security restrictions, from the specified file
-   instead of preserving encryption details from the input file. This
-   works even if only one of the user password or owner password is
-   known. If the encryption file requires a password, use the
-   :qpdf:ref:`--encryption-file-password` option to set it. Note that
-   copying the encryption parameters from a file also copies the first
-   half of ``/ID`` from the file since this is part of the encryption
-   parameters. This option can be useful if you need to decrypt a file
-   to make manual changes to it or to change it outside of qpdf, and
-   then want to restore the original encryption on the file
-   without having to manual specify all the individual settings. See
-   also :qpdf:ref:`--decrypt`.
+   Copy all encryption parameters, including the user password, the
+   owner password, and all security restrictions, from the specified
+   file instead of preserving the encryption details from the input
+   file. This works even if only one of the user password or owner
+   password is known. If the encryption file requires a password, use
+   the :qpdf:ref:`--encryption-file-password` option to set it. Note
+   that copying the encryption parameters from a file also copies the
+   first half of ``/ID`` from the file since this is part of the
+   encryption parameters. This option can be useful if you need to
+   decrypt a file to make manual changes to it or to change it outside
+   of qpdf, and then want to restore the original encryption on the
+   file without having to manual specify all the individual settings.
+   See also :qpdf:ref:`--decrypt`.
 .. qpdf:option:: --encryption-file-password=password
@@ -752,12 +755,12 @@ Related Options
    .. help: enable viewing PDF code in a text editor
       Create a PDF file suitable for viewing in a text editor and even
-      editing. This is to edit the PDF code, not the page contents.
+      editing. This is for editing the PDF code, not the page contents.
       All streams that can be uncompressed are uncompressed, and
       content streams are normalized, among other changes. The
       companion tool "fix-qdf" can be used to repair hand-edited QDF
-      files. QDF is a feature specific to the qpdf tool. There is a
-      chapter about it in the manual.
+      files. QDF is a feature specific to the qpdf tool. Please see
+      the "QDF Mode" chapter in the manual.
    Create a PDF file suitable for viewing and editing in a text
    editor. This is to edit the PDF code, not the page contents. To
@@ -766,13 +769,13 @@ Related Options
    and content streams are normalized, among other changes. The
    companion tool :command:`fix-qdf` can be used to repair hand-edited
    QDF files. QDF is a feature specific to the qpdf tool. For
-   additional information about QDF mode, see :ref:`qdf`. Note that
+   additional information, see :ref:`qdf`. Note that
    :qpdf:ref:`--linearize` disables QDF mode.
    QDF mode has full support for object streams, but sometimes it's
    easier to locate a specific object if object streams are disabled.
    When trying to understand some PDF construct by inspecting an
-   existing file, it can often be useful to combine :samp:`--qdf` with
+   existing file, it can be useful to combine :samp:`--qdf` with
    :samp:`--object-streams=disable`.
    This flag changes some of the defaults of other options: stream
@@ -788,10 +791,10 @@ Related Options
    When normalizing content, if qpdf runs into any lexical errors, it
    will print a warning indicating that content may be damaged. If you
-   want to create QDF files without content normalization, can you run
-   with :samp:`--qdf --normalize-content=n`. You can also create a
-   non-QDF file with uncompressed streams using
-   :samp:`--stream-data=uncompress`. These will both uncompress all
+   want to create QDF files without content normalization, specify
+   :samp:`--qdf --normalize-content=n`. You can also create a non-QDF
+   file with uncompressed streams using
+   :samp:`--stream-data=uncompress`. Either option will uncompress all
    the streams but will not attempt to normalize content. Please note
    that if you are using content normalization or QDF mode for the
    purpose of manually inspecting files, you don't have to care about
@@ -872,15 +875,15 @@ Related Options
    These are left untouched regardless of the option. Future versions
    of qpdf may support additional filters.
-   Because the default value is ``generalized``, by default, when a stream
-   is encoded using non-lossy filters that qpdf understands and is not
-   already compressed using a good compression scheme, qpdf will
-   uncompress the stream. If ``--compress-streams=y`` is also in
-   effect, which is the default (see :qpdf:ref:`--compress-streams`),
-   the overall effect is that qpdf will recompress streams with
-   generalized filters using flate compression, effectively
-   eliminating LZW and ASCII-based filters. This is usually desirable
-   behavior but can be disabled with ``--decode-level=none``.
+   Because the default value is ``generalized``, qpdf's default
+   behavior is to uncompress any stream that is encoded using
+   non-lossy filters that qpdf understands. If
+   ``--compress-streams=y`` is also in effect, which is the default
+   (see :qpdf:ref:`--compress-streams`), the overall effect is that
+   qpdf will recompress streams with generalized filters using flate
+   compression, effectively eliminating LZW and ASCII-based filters.
+   This is usually desirable behavior but can be disabled with
+   ``--decode-level=none``.
    As a special case, streams already compressed with ``/FlateDecode``
    are not uncompressed and recompressed. You can change this behavior
@@ -956,7 +959,8 @@ Related Options
    already compressed streams, you should also specify
    :qpdf:ref:`--recompress-flate`. If your goal is to shrink the size
    of PDF files, you should also use
-   :samp:`--object-streams=generate`.
+   :samp:`--object-streams=generate`. If you omit this option, qpdf
+   defers to the compression library's default behavior.
 .. qpdf:option:: --normalize-content=[yn]
@@ -1002,10 +1006,10 @@ Related Options
         - create object streams, and compress objects when possible
    Object streams are PDF streams that contain other objects. Putting
-   objects in object streams allows the PDF objects themselves to be
+   objects into object streams allows the PDF objects themselves to be
    compressed, which can result in much smaller PDF files. Combining
    this option with :qpdf:ref:`--compression-level` and
-   :qpdf:ref:`--recompress-flate` can often result in creation of
+   :qpdf:ref:`--recompress-flate` can often result in the creation of
    smaller PDF files.
    Object streams, also known as compressed objects, were introduced
@@ -1014,7 +1018,7 @@ Related Options
    used to transform files with object streams into files without object
    streams or vice versa.
-   In :samp:`preserve` mode, the relationship to objects and the
+   In :samp:`preserve` mode, the relationship between objects and the
    streams that contain them is preserved from the original file. If
    the file has no object streams, qpdf will not add any. In
    :samp:`disable` mode, all objects are written as regular,
@@ -1040,7 +1044,7 @@ Related Options
    objects.
    This flag is ignored for linearized files and has the effect of
-   causing objects in the new file to be written in order by object ID
+   causing objects in the new file to be written ordered by object ID
    from the original file. This does not mean that object numbers will
    be the same since qpdf may create stream lengths as direct or
    indirect differently from the original file, and the original file
@@ -1157,8 +1161,11 @@ Related Options
    .. help: set minimum PDF version
-      Force the PDF version of the output to be at least the
-      specified version.
+      Force the PDF version of the output to be at least the specified
+      version. The version number format is
+      "major.minor[.extension-level]", which sets the version header
+      to "major.minor" and the extension level, if specified, to
+      "extension-level".
    Force the PDF version of the output file to be at least
    :samp:`{version}`. In other words, if the input file has a lower
@@ -1169,12 +1176,13 @@ Related Options
    when adding features that require newer PDF readers.
    The version number may be expressed in the form
-   :samp:`{major.minor.extension-level}`, in which case the version is
-   interpreted as :samp:`{major.minor}` at extension level
-   :samp:`{extension-level}`. For example, version ``1.7.8``
-   represents version 1.7 at extension level 8. Note that minimal
-   syntax checking is done on the command line. :command:`qpdf` does
-   not check whether the specified version is actually required.
+   :samp:`{major}.{minor}[.{extension-level}]`. If
+   :samp:`.{extension-level}`, is given, version is interpreted as
+   :samp:`{major.minor}` at extension level :samp:`{extension-level}`.
+   For example, version ``1.7.8`` represents version 1.7 at extension
+   level 8. Note that minimal syntax checking is done on the command
+   line. :command:`qpdf` does not check whether the specified version
+   is actually required.
 .. qpdf:option:: --force-version=version
@@ -1192,22 +1200,22 @@ Related Options
    version to be lower than that of the input file will cause qpdf to
    disable certain features of the document. Specifically, 256-bit
    keys are disabled if the version is less than 1.7 with extension
-   level 8 (except R5 is disabled if less than 1.7 with extension
-   level 3), AES encryption is disabled if the version is less than
-   1.6, cleartext metadata and object streams are disabled if less
-   than 1.5, 128-bit encryption keys are disabled if less than 1.4,
-   and all encryption is disabled if less than 1.3. Even with these
-   precautions, qpdf won't be able to do things like eliminate use of
-   newer image compression schemes, transparency groups, or other
-   features that may have been added in more recent versions of PDF.
+   level 8 (except the deprecated, unsupported "R5" format is allowed
+   with extension levels 3 through 7), AES encryption is disabled if
+   the version is less than 1.6, cleartext metadata and object streams
+   are disabled if less than 1.5, 128-bit encryption keys are disabled
+   if less than 1.4, and all encryption is disabled if less than 1.3.
+   Even with these precautions, qpdf won't be able to do things like
+   eliminate use of newer image compression schemes, transparency
+   groups, or other features that may have been added in more recent
+   versions of PDF.
    As a general rule, with the exception of big structural things like
    the use of object streams or AES encryption, PDF viewers are
-   supposed to ignore features in files that they don't support from
-   newer versions. This means that forcing the version to a lower
-   version may make it possible to open your PDF file with an older
-   version, though bear in mind that some of the original document's
-   functionality may be lost.
+   supposed to ignore features they don't support. This means that
+   forcing the version to a lower version may make it possible to open
+   your PDF file with an older version, though bear in mind that some
+   of the original document's functionality may be lost.
 .. _page-ranges:
@@ -1310,7 +1318,7 @@ PDF, causing the PDF to render differently from the original. See also
 Related Options
 ~~~~~~~~~~~~~~~
-.. qpdf:option:: --pages file [ --password=password ] [ page-range ] [ ... ] --
+.. qpdf:option:: --pages file [--password=password] [page-range] [...] --
    .. help: begin page selection
@@ -1405,7 +1413,7 @@ Related Options
    if you don't require the document-level data. A future version of
    qpdf may support preservation of some document-level information.
-.. qpdf:option:: --overlay file [ options ] --
+.. qpdf:option:: --overlay file [options] --
    .. help: begin overlay options
@@ -1416,7 +1424,7 @@ Related Options
    See :ref:`overlay-underlay` for details.
-.. qpdf:option:: --underlay file [ options ] --
+.. qpdf:option:: --underlay file [options] --
    .. help: begin underlay options
@@ -1674,7 +1682,7 @@ Encryption
    Create encrypted files. Usage:
-   --encrypt user-password owner-password key-length [ options ] --
+   --encrypt user-password owner-password key-length [options] --
    Either or both of user-password and owner-password may be empty
    strings. key-length may be 40, 128, or 256. Encryption options are
@@ -1741,7 +1749,7 @@ To create an encrypted file, use
 ::
-   --encrypt user-password owner-password key-length [ options ] --
+   --encrypt user-password owner-password key-length [options] --
 Either or both of :samp:`{user-password}` and :samp:`{owner-password}`
 may be empty strings. :samp:`{key-length}` may be ``40``, ``128``, or
@@ -1780,7 +1788,6 @@ encryption from the file entirely.
 Here is a summary of encryption options. Details are provided in the
 help for each option.
-
 .. list-table:: Options for 40-bit Encryption Only
    :widths: 30 70
    :header-rows: 0
@@ -2154,13 +2161,13 @@ Page Selection
    Use the --pages option to select pages from multiple files. Usage:
-   qpdf in.pdf --pages input-file [ --password=password ] [ page-range ] \
-       [ ... ] -- out.pdf
+   qpdf in.pdf --pages input-file [--password=password] [page-range] \
+       [...] -- out.pdf
    Between --pages and the -- that terminates pages option, repeat
    the following:
-   filename [ --password=password ] [ page-range ]
+   filename [--password=password] [page-range]
    Document-level information, such as outlines, tags, etc., is taken
    from in.pdf and is preserved in out.pdf. You can use --empty in place
@@ -2200,12 +2207,12 @@ Page Selection
 split and merge PDF files by selecting pages from one or more input
 files.
-Usage: :samp:`qpdf {in.pdf} --pages input-file [ --password={password} ] [ {page-range} ] [ ... ] -- {out.pdf}`
+Usage: :samp:`qpdf {in.pdf} --pages input-file [--password={password}] [{page-range}] [...] -- {out.pdf}`
 Between ``--pages`` and the ``--`` that terminates pages option,
 repeat the following:
-:samp:`{filename} [ --password={password} ] [ {page-range} ]`
+:samp:`{filename} [--password={password}] [{page-range}]`
 Notes:
   - The password option is needed only for password-protected files.
@@ -2424,10 +2431,10 @@ Overlay and Underlay
    drawn below the destination page. Usage:
    {--overlay | --underlay } file
-         [ --password=password ]
-         [ --to=page-range ]
-         [ --from=[page-range] ]
-         [ --repeat=page-range ]
+         [--password=password]
+         [--to=page-range]
+         [--from=[page-range]]
+         [--repeat=page-range]
          --
    Note the use of "--" by itself to terminate overlay/underlay options.
@@ -2447,7 +2454,7 @@ as follows:
 ::
-   { --overlay | --underlay } file [ options ] --
+   { --overlay | --underlay } file [options] --
 Overlay and underlay options are processed late, so they can be
 combined with other options like merging and will apply to the final
@@ -3,6 +3,8 @@
 QDF Mode
 ========
+.. Help text for --qdf refers to the name of this chapter.
+
 In QDF mode, qpdf creates PDF files in what we call *QDF
 form*. A PDF file in QDF form, sometimes called a QDF
 file, is a completely valid PDF file that has ``%QDF-1.0`` as its third