CLI doc: use tables where helpful

Jay Berkenbilt
1 parent c529c28d
Showing 3 changed files with 232 additions and 106 deletions
job.sums
libqpdf/qpdf/auto_job_help.hh
manual/cli.rst
@@ -2,7 +2,7 @@
 generate_auto_job 466aa9211549cebeb3fedc6413108981aeeddd89936621095f5f5223cee9880b
 job.yml 8177cadf41096efdc174f04daadfe5d98c592ad44ad10cb96537521fd79a801a
 libqpdf/qpdf/auto_job_decl.hh 97395ecbe590b23ae04d6cce2080dbd0e998917ff5eeaa5c6aafa91041d3cd6a
-libqpdf/qpdf/auto_job_help.hh fa7ff1d1f6289881ac3a485107d15240c4992c59cff506be425354557108d184
+libqpdf/qpdf/auto_job_help.hh 4dd6a958745b793320d0c657e23b670918e29f4d3dd6d78477d87df3eca2a910
 libqpdf/qpdf/auto_job_init.hh 465bf46769559ceb77110d1b9d3293ba9b3595850b49848c31aeabd10aadb4ad
 manual/_ext/qpdf.py 855fe12de5af7a10bb24be6ecc4d5dff4c84ac58cf388a13be6bbb394346a67d
-manual/cli.rst 7a36de7413b5c2867de573b5a9beff862e28c46123b72d08e3971ddf5bdf3bbe
+manual/cli.rst e99e45275cdbc902b4860091453ae08e7b356da6301c5dc622982ec326e87e2a
@@ -721,7 +721,7 @@ aspects of the file, and write information about the file to
 standard output. Note that qpdf does not perform any validation
 of the actual PDF page content or semantic correctness of the
 PDF file. It merely checks that the PDF file is syntactically
-valid.
+valid. See also qpdf --help=exit-status.
 )");
 ap.addOptionHelp("--show-encryption", "copy-attachments", "information about encrypted files", R"(Show document encryption parameters. Also show the document's
 user password if the owner password is given and the file was
@@ -141,25 +141,36 @@ Exit Status
 The exit status of :command:`qpdf` may be interpreted as follows:
-- ``0``: no errors or warnings were found. The file may still have
-  problems qpdf can't detect. If :qpdf:ref:`--warning-exit-0` was
-  specified, exit status ``0`` is used even if there are warnings.
+.. list-table:: Exit Codes
+   :widths: 5 80
+   :header-rows: 0
-- ``1``: :command:`qpdf` does not exit with status ``1`` since the
-  shell uses this exit code if it is unable to invoke the command.
+   - - 0
+     - no errors or warnings were found
-- ``2``: errors were found. qpdf was not able to fully process the
-  file.
+   - - 1
+     - not used
-- ``3``: qpdf encountered problems that it was able to recover from.
-  In some cases, the resulting file may still be damaged. Note that
-  qpdf still exits with status ``3`` if it finds warnings even when
-  :qpdf:ref:`--no-warn` is specified. With
-  :qpdf:ref:`--warning-exit-0`, warnings without errors exit with
-  status ``0`` instead of ``3``.
+   - - 2
+     - errors were found; the file was not processed
-The :qpdf:ref:`--is-encrypted` and :qpdf:ref:`--requires-password`
-options use different exit codes. See their help for details.
+   - - 3
+     - warnings were found without errors
+
+Notes:
+
+- A PDF file may have problems that qpdf can't detect.
+
+- With the :qpdf:ref:`--warning-exit-0` option, exit status ``0`` is
+  used even if there are warnings.
+
+- :command:`qpdf` does not exit with status ``1`` since the shell uses
+  this exit code if it is unable to invoke the command.
+
+- If both errors and warnings were found, exit status ``2`` is used.
+
+- The :qpdf:ref:`--is-encrypted` and :qpdf:ref:`--requires-password`
+  options use different exit codes. See their help for details.
 Related Options
 ~~~~~~~~~~~~~~~
@@ -938,13 +949,18 @@ Related Options
    Controls handling of object streams. The value of :samp:`{mode}`
    may be one of the following:
-   - :samp:`preserve`: preserve original object streams, if any (the
-     default)
+   .. list-table:: Object Stream Modes
+      :widths: 10 80
+      :header-rows: 0
+
+      - - :samp:`preserve`
+        - preserve original object streams, if any (the default)
-   - :samp:`disable`: create output files with no object streams
+      - - :samp:`disable`
+        - create output files with no object streams
-   - :samp:`generate`: create object streams, and compress objects
-     when possible
+      - - :samp:`generate`
+        - 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
@@ -1195,34 +1211,47 @@ options. This section describes the syntax of a page range.
   case, odd and even refer to positions in the final range, not
   whether the original page number is odd or even.
-Example page ranges:
+.. list-table:: Example Page Ranges
+   :widths: 20 80
+   :header-rows: 0
-- ``1,6,4``: pages 1, 6, and 4 in that order
+   - - ``1,6,4``
+     - pages 1, 6, and 4 in that order
-- ``3-7``: pages 3 through 7 inclusive in increasing order
+   - - ``3-7``
+     - pages 3 through 7 inclusive in increasing order
-- ``7-3``: pages 7, 6, 5, 4, and 3 in that order
+   - - ``7-3``
+     - pages 7, 6, 5, 4, and 3 in that order
-- ``1-z``: all pages in order
+   - - ``1-z``
+     - all pages in order
-- ``z-1``: all pages in reverse order
+   - - ``z-1``
+     - all pages in reverse order
-- ``1,3,5-9,15-12``: pages 1, 3, 5, 6, 7, 8, 9, 15, 14, 13, and 12 in
-  that order
+   - - ``1,3,5-9,15-12``
+     - pages 1, 3, 5, 6, 7, 8, 9, 15, 14, 13, and 12 in that order
-- ``r3-r1``: the last three pages of the document
+   - - ``r3-r1``
+     - the last three pages of the document
-- ``r1-r3``: the last three pages of the document in reverse order
+   - - ``r1-r3``
+     - the last three pages of the document in reverse order
-- ``1-20:even``: even pages from 2 to 20
+   - - ``1-20:even``
+     - even pages from 2 to 20
-- ``5,7-9,12``: pages 5, 7, 8, 9, and 12
+   - - ``5,7-9,12``
+     - pages 5, 7, 8, 9, and 12
-- ``5,7-9,12:odd``: pages 5, 8, and 12, which are the pages in odd
-  positions from the original set of 5, 7, 8, 9, 12
+   - - ``5,7-9,12:odd``
+     - pages 5, 8, and 12, which are the pages in odd positions from
+       the original set of 5, 7, 8, 9, 12
-- ``5,7-9,12:even``: pages 7 and 9, which are the pages in even
-  positions from the original set of 5, 7, 8, 9, 12
+   - - ``5,7-9,12:even``
+     - pages 7 and 9, which are the pages in even positions from the
+       original set of 5, 7, 8, 9, 12
 .. _modification-options:
@@ -1393,14 +1422,20 @@ Related Options
    annotations. The :samp:`{option}` parameter may be any of the
    following:
-   - :samp:`all`: include all annotations that are not marked
-     invisible or hidden
+   .. list-table:: Flatten Annotation Options
+      :widths: 10 80
+      :header-rows: 0
+
+      - - :samp:`all`
+        - include all annotations that are not marked invisible or
+          hidden
-   - :samp:`print`: only include annotations that indicate that they
-     should appear when the page is printed
+      - - :samp:`print`
+        - only include annotations that should appear when the page is
+          printed
-   - :samp:`screen`: omit annotations that indicate they should not
-     appear on the screen
+      - - :samp:`screen`
+        - omit annotations that should not appear on the screen
    In a PDF file, interactive form fields have a value and,
    independently, a set of instructions, called an appearance, to
@@ -1702,63 +1737,109 @@ does not obey encryption restrictions already imposed on the file.
 Doing so would be meaningless since qpdf can be used to remove
 encryption from the file entirely.
-Here is a summary of encryption options. Details are provided below.
+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
+
+   - - ``--annotate=[yn]``
+     - restrict comments, filling forms, and signing
-Options for 40-bit only
-  - ``--annotate=[yn]``: restrict comments, filling forms, and signing
+   - - ``--extract=[yn]``
+     - restrict text/graphic extraction
-  - ``--extract=[yn]``: restrict text/graphic extraction
+   - - ``--modify=[yn]``
+     - restrict document modification
-  - ``--modify=[yn]``: restrict document modification
+   - - ``--print=[yn]``
+     - restrict printing
-  - ``--print=[yn]``: restrict printing
+.. list-table:: Options for 128-bit or 256-bit Encryption
+   :widths: 30 70
+   :header-rows: 0
-Options for 128-bit or 256-bit
-  - ``--accessibility=[yn]``: restrict accessibility (usually ignored)
+   - - ``--accessibility=[yn]``
+     - restrict accessibility (usually ignored)
-  - ``--annotate=[yn]``: restrict commenting/filling form fields
+   - - ``--annotate=[yn]``
+     - restrict commenting/filling form fields
-  - ``--assemble=[yn]``: restrict document assembly
+   - - ``--assemble=[yn]``
+     - restrict document assembly
-  - ``--extract=[yn]``: restrict text/graphic extraction
+   - - ``--extract=[yn]``
+     - restrict text/graphic extraction
-  - ``--form=[yn]``: restrict filling form fields
+   - - ``--form=[yn]``
+     - restrict filling form fields
-  - ``--modify-other=[yn]``: restrict other modifications
+   - - ``--modify-other=[yn]``
+     - restrict other modifications
-  - ``--modify=modify-opt``: control modify access by level
+   - - ``--modify=modify-opt``
+     - control modify access by level
-  - ``--print=print-opt``: control printing access
+   - - ``--print=print-opt``
+     - control printing access
-  - ``--cleartext-metadata``: prevent encryption of metadata
+   - - ``--cleartext-metadata``
+     - prevent encryption of metadata
-For 128-bit only
-  - ``--use-aes=[yn]``: indicates whether to use AES encryption
+.. list-table:: Options for 128-bit Encryption Only
+   :widths: 30 70
+   :header-rows: 0
-  - ``--force-V4``: forces use of V=4 encryption handler
+   - - ``--use-aes=[yn]``
+     - indicates whether to use AES encryption
-For 256-bit only
-  - ``--force-R5``: forces use of deprecated ``R=5`` encryption algorithm
+   - - ``--force-V4``
+     - forces use of V=4 encryption handler
-  - ``--allow-insecure``: allow user password with empty owner password
+.. list-table:: Options for 256-bit Encryption Only
+   :widths: 30 70
+   :header-rows: 0
-Values for :samp:`{print-opt}`
-  - ``none``: disallow printing
+   - - ``--force-R5``
+     - forces use of deprecated ``R=5`` encryption algorithm
-  - ``low``: allow only low-resolution printing
+   - - ``--allow-insecure``
+     - allow user password with empty owner password
-  - ``full``: allow full printing
+.. list-table:: Values for :samp:`{print-opt}`
+   :widths: 20 80
+   :header-rows: 0
-Values for :samp:`{modify-opt}`
-  - ``none``: allow no modifications
+   - - ``none``
+     - disallow printing
-  - ``assembly``: allow document assembly only
+   - - ``low``
+     - allow only low-resolution printing
-  - ``form``: ``assembly`` permissions plus filling in form fields and signing
+   - - ``full``
+     - allow full printing
-  - ``annotate``: ``form`` permissions plus commenting and modifying forms
+.. list-table:: Values for :samp:`{modify-opt}`
+   :widths: 20 80
+   :header-rows: 0
-  - ``all``: allow full document modification
+   - - ``none``
+     - allow no modifications
+
+   - - ``assembly``
+     - allow document assembly only
+
+   - - ``form``
+     - ``assembly`` permissions plus filling in form fields and
+       signing
+
+   - - ``annotate``
+     - ``form`` permissions plus commenting and modifying forms
+
+   - - ``all``
+     - allow full document modification
 Related Options
 ~~~~~~~~~~~~~~~
@@ -1873,30 +1954,46 @@ Related Options
    allow enabling and disabling levels of restriction in a manner
    similar to how some PDF creation tools do it:
-   - ``none``: allow no modifications
+   .. list-table:: :samp:`{modify-opt}` for 128-bit and 256-bit Encryption
+      :widths: 10 80
+      :header-rows: 0
+
+      - - ``none``
+        - allow no modifications
+
+      - - ``assembly``
+        - allow document assembly only
-   - ``assembly``: allow document assembly only
+      - - ``form``
+        - ``assembly`` permissions plus filling in form fields and
+          signing
-   - ``form``: ``assembly`` permissions plus filling in form fields
-     and signing
+      - - ``annotate``
+        - ``form`` permissions plus commenting and modifying forms
-   - ``annotate``: ``form`` permissions plus commenting and modifying
-     forms
+      - - ``all``
+        - allow full document modification (the default)
-   - ``all``: allow full document modification (the default)
+   Modify options correspond to the more granular options as follows:
-   :samp:`{modify-opt}` values map to other combinations of options as
-   follows:
+   .. list-table:: Mapping :samp:`{modify-opt}` to Other Options
+      :widths: 10 80
+      :header-rows: 0
-   - ``none``: same as ``--modify-other=n --annotate=n --form=n --assemble=n``
+      - - ``none``
+        - ``--modify-other=n --annotate=n --form=n --assemble=n``
-   - ``assembly``: same as ``--modify-other=n --annotate=n --form=n``
+      - - ``assembly``
+        - ``--modify-other=n --annotate=n --form=n``
-   - ``form``: same as ``--modify-other=n --annotate=n``
+      - - ``form``
+        - ``--modify-other=n --annotate=n``
-   - ``annotate``: same as ``--modify-other=n``
+      - - ``annotate``
+        - ``--modify-other=n``
-   - ``all``: the default
+      - - ``all``
+        - no other modify options (the default)
    You can combine this option with the options listed above. If you
    do, later options override earlier options.
@@ -1919,11 +2016,18 @@ Related Options
    printing. For 128-bit and 256-bit encryption, :samp:`{print-opt}`
    may have the following values:
-   - :samp:`none`: disallow printing
+   .. list-table:: :samp:`{print-opt}` Values
+      :widths: 10 80
+      :header-rows: 0
-   - :samp:`low`: allow low-resolution printing only
+      - - :samp:`none`
+        - disallow printing
-   - :samp:`full`: allow full printing (the default)
+      - - :samp:`low`
+        - allow low-resolution printing only
+
+      - - :samp:`full`
+        - allow full printing (the default)
 .. qpdf:option:: --cleartext-metadata
@@ -2505,10 +2609,15 @@ indicate how far after. For example, US Eastern Standard Time
 (America/New_York) is ``-05'00'``, and Indian Standard Time
 (Asia/Calcutta) is ``+05'30'``.
-Examples:
-  - ``D:20210207161528-05'00'``: February 7, 2021 at 4:15:28 p.m.
+.. list-table:: PDF Date Examples
+   :widths: 30 70
+   :header-rows: 0
+
+   - - ``D:20210207161528-05'00'``
+     - February 7, 2021 at 4:15:28 p.m.
-  - ``D:20210207211528Z``: February 7, 2021 at 21:15:28 UTC
+   - - ``D:20210207211528Z``
+     - February 7, 2021 at 21:15:28 UTC
 .. _add-attachment:
@@ -2670,11 +2779,18 @@ Related Options
    Silently exit with a code indicating the file's encryption status:
-   - ``0``: the file is encrypted
+   .. list-table:: Exit Codes for ``--is-encrypted``
+      :widths: 5 80
+      :header-rows: 0
+
+      - - ``0``
+        - the file is encrypted
-   - ``1``: not used
+      - - ``1``
+        - not used
-   - ``2``: the file is not encrypted
+      - - ``2``
+        - the file is not encrypted
    This option can be used for password-protected files even if you
    don't know the password.
@@ -2698,14 +2814,22 @@ Related Options
    Silently exit with a code indicating the file's password status:
-   - ``0``: a password, other than as supplied, is required
+   .. list-table:: Exit Codes for ``--requires-password``
+      :widths: 5 80
+      :header-rows: 0
-   - ``1``: not used
+      - - ``0``
+        - a password, other than as supplied, is required
-   - ``2``: the file is not encrypted
+      - - ``1``
+        - not used
-   - ``3``: the file is encrypted, and correct password (if any) has
-     been supplied
+      - - ``2``
+        - the file is not encrypted
+
+      - - ``3``
+        - the file is encrypted, and correct password (if any) has
+          been supplied
    Use with the :qpdf:ref:`--password` option to specify the password
    to test.
@@ -2738,7 +2862,7 @@ Related Options
       standard output. Note that qpdf does not perform any validation
       of the actual PDF page content or semantic correctness of the
       PDF file. It merely checks that the PDF file is syntactically
-      valid.
+      valid. See also qpdf --help=exit-status.
    Check the file's structure and well as encryption, linearization,
    and encoding of stream data, and write information about the file
@@ -2764,6 +2888,8 @@ Related Options
    other options in this way can be useful for manually recovering
    severely damaged files.
+   See also :ref:`exit-status`.
+
 .. qpdf:option:: --show-encryption
    .. help: information about encrypted files