diff options
Diffstat (limited to 'manual/cli.rst')
| -rw-r--r-- | manual/cli.rst | 156 |
1 files changed, 84 insertions, 72 deletions
diff --git a/manual/cli.rst b/manual/cli.rst index 194bfacd..c33a545f 100644 --- a/manual/cli.rst +++ b/manual/cli.rst @@ -171,7 +171,9 @@ Related Options equivalent command-line arguments were supplied. It can be repeated and mixed freely with other options. Run ``qpdf`` with :qpdf:ref:`--job-json-help` for a description of the job JSON input - file format. For more information, see :ref:`qpdf-job`. + file format. For more information, see :ref:`qpdf-job`. Note that + this is unrelated to :qpdf:ref:`--json` but may be combined with + it. .. _exit-status: @@ -341,6 +343,17 @@ Related Options itself. The default provider is always listed first. See :ref:`crypto` for more information about crypto providers. +.. qpdf:option:: --job-json-help + + .. help: show format of job JSON + + Describe the format of the QPDFJob JSON input used by + --job-json-file. + + Describe the format of the QPDFJob JSON input used by + :qpdf:ref:`--job-json-file`. For more information about QPDFJob, + see :ref:`qpdf-job`. + .. _general-options: General Options @@ -852,9 +865,11 @@ Related Options When uncompressing streams, control which types of compression schemes should be uncompressed: - - none: don't uncompress anything. This is the default with --json-output. + - none: don't uncompress anything. This is the default with + --json-output. - generalized: uncompress streams compressed with a - general-purpose compression algorithm. This is the default. + general-purpose compression algorithm. This is the default + except when --json-output is given. - specialized: in addition to generalized, also uncompress streams compressed with a special-purpose but non-lossy compression scheme @@ -875,7 +890,8 @@ Related Options ``/ASCII85Decode``, and ``/ASCIIHexDecode``. We define generalized filters as those to be used for general-purpose compression or encoding, as opposed to filters specifically - designed for image data. This is the default. + designed for image data. This is the default except when + :qpdf:ref:`--json-output` is given. - :samp:`specialized`: in addition to generalized, decode streams with supported non-lossy specialized filters; currently this is @@ -3126,8 +3142,9 @@ Related Options is usually but not always equal to the file name and is needed by some of the other options. See also :ref:`attachments`. Note that this option displays dates in PDF timestamp syntax. When attachment - information is included in json output (see :ref:`--json`), dates - are shown in ISO-8601 format. + information is included in json output in the ``"attachments"`` key + (see :ref:`--json`), dates are shown (just within that object) in + ISO-8601 format. .. qpdf:option:: --show-attachment=key @@ -3169,14 +3186,11 @@ Related Options Generate a JSON representation of the file. This is described in depth in :ref:`json`. The version parameter can be used to specify - which version of the qpdf JSON format should be output. The only - supported value is ``1``, but it's possible that a new JSON output - version will be added in a future version. You can also specify - ``latest`` to use the latest JSON version. For backward - compatibility, the default value will remain ``1`` until qpdf - version 11, after which point it will become ``latest``. In all - case, you can tell what version of the JSON output you have from - the ``"version"`` key in the output. Use the + which version of the qpdf JSON format should be output. The version + number be a number or ``latest``. The default is ``latest``. As of + qpdf 11, the latest version is ``2``. If you have code that reads + qpdf JSON output, you can tell what version of the JSON output you + have from the ``"version"`` key in the output. Use the :qpdf:ref:`--json-help` option to get a description of the JSON object. @@ -3189,11 +3203,11 @@ Related Options containing descriptive text. Describe the format of the JSON output by writing to standard - output a JSON object with the same structure with the same keys as - the JSON generated by qpdf. In the output written by - ``--json-help``, each key's value is a description of the key. The - specific contract guaranteed by qpdf in its JSON representation is - explained in more detail in the :ref:`json`. + output a JSON object with the same structure as the JSON generated + by qpdf. In the output written by ``--json-help``, each key's value + is a description of the key. The specific contract guaranteed by + qpdf in its JSON representation is explained in more detail in the + :ref:`json`. .. qpdf:option:: --json-key=key @@ -3216,53 +3230,50 @@ Related Options be shown in the "objects" key of the JSON output. Otherwise, all objects will be shown. - This option is repeatable. If given, only specified objects will - be shown in the "``objects``" key of the JSON output. Otherwise, all - objects will be shown. - -.. qpdf:option:: --job-json-help - - .. help: show format of job JSON - - Describe the format of the QPDFJob JSON input used by - --job-json-file. - - Describe the format of the QPDFJob JSON input used by - :qpdf:ref:`--job-json-file`. For more information about QPDFJob, - see :ref:`qpdf-job`. + This option is repeatable. If given, only specified objects will be + shown in the ``"objects"`` key of the JSON output. Otherwise, all + objects will be shown. For qpdf JSON version 1, this also affects + the ``"objectinfo"`` key, which is not present in version 2. This + option may be used with :qpdf:ref:`--json` and also with + :qpdf:ref:`--json-output`. .. qpdf:option:: --json-stream-data={none|inline|file} .. help: how to handle streams in json output - Control whether streams in json output should be omitted, - written inline (base64-encoded) or written to a file. If "file" - is chosen, the file will be the name of the input file appended - with -nnn where nnn is the object number. The prefix can be - overridden with --json-stream-prefix. - - Control whether streams in json output should be omitted, written - inline (base64-encoded) or written to a file. If ``file`` is - chosen, the file will be the name of the input file appended with - :samp:`-{nnn}` where :samp:`{nnn}` is the object number. The prefix - can be overridden with :qpdf:ref:`--json-stream-prefix`. This - option only applies when used with :qpdf:ref:`--json-output`. + When used with --json-output, this option controls whether + streams in json output should be omitted, written inline + (base64-encoded) or written to a file. If "file" is chosen, the + file will be the name of the output file appended with -nnn where + nnn is the object number. The prefix can be overridden with + --json-stream-prefix. + + When used with :qpdf:ref:`--json-output`, this option controls + whether streams in JSON output should be omitted, written inline + (base64-encoded) or written to a file. If ``file`` is chosen, the + file will be the name of the output file appended with + :samp:`-{nnn}` where :samp:`{nnn}` is the object number. The stream + data file prefix can be overridden with + :qpdf:ref:`--json-stream-prefix`. This option only applies when + used with :qpdf:ref:`--json-output`. .. qpdf:option:: --json-stream-prefix=file-prefix .. help: prefix for json stream data files - When --json-stream-data=file is given, override the input file - name as the prefix for stream data files. Whatever is given here + When used with --json-output, --json-stream-data=file-prefix + sets the prefix for stream data files, overriding the default, + which is to use the output file name. Whatever is given here will be appended with -nnn to create the name of the file that will contain the data for the stream stream in object nnn. - When :qpdf:ref:`--json-stream-data` is given with the value - ``file``, override the input file name as the prefix for stream - data files. Whatever is given here will be appended with - :samp:`-{nnn}` to create the name of the file that will contain the - data for the stream stream in object :samp:`{nnn}`. This - option only applies when used with :qpdf:ref:`--json-output`. + When used with :qpdf:ref:`--json-output`, + ``--json-stream-data=file-prefix`` sets the prefix for stream data + files, overriding the default, which is to use the output file + name. Whatever is given here will be appended with :samp:`-{nnn}` + to create the name of the file that will contain the data for the + stream stream in object :samp:`{nnn}`. This option only applies + when used with :qpdf:ref:`--json-output`. .. qpdf:option:: --json-output[=version] @@ -3270,44 +3281,45 @@ Related Options The output file will be qpdf JSON format at the given version. "version" may be a specific version or "latest" (the default). - Version 1 is not supported. See also --json-stream-data, + The only supported version is 2. See also --json-stream-data, --json-stream-prefix, and --decode-level. - The output file will be qpdf JSON format at the given version. - ``version`` may be a specific version or ``latest`` (the default). - Version 1 is not supported. See also :qpdf:ref:`--json-stream-data` - and :qpdf:ref:`--json-stream-prefix`. The default decode level is - ``none``, but you can override it with :qpdf:ref:`--decode-level`. - If you want to look at the contents of streams easily as you would - in QDF mode (see :ref:`qdf`), you can use - ``--decode-level=generalized`` and ``--json-stream-data=file`` for - a convenient way to do that. + The output file, instead of being a PDF file, will be a JSON file + in qpdf JSON format at the given version. ``version`` may be a + specific version or ``latest`` (the default). The only supported + version is 2. See also :qpdf:ref:`--json-stream-data` and + :qpdf:ref:`--json-stream-prefix`. When this option is specified, + the default decode level for stream data is ``none``, but you can + override it with :qpdf:ref:`--decode-level`. If you want to look at + the contents of streams easily as you would in QDF mode (see + :ref:`qdf`), you can use ``--decode-level=generalized`` and + ``--json-stream-data=file`` for a convenient way to do that. .. qpdf:option:: --json-input .. help: input file is qpdf JSON Treat the input file as a JSON file in qpdf JSON format as - written by qpdf --json-output. See the "QPDF JSON Format" + written by qpdf --json-output. See the "qpdf JSON Format" section of the manual for information about how to use this option. Treat the input file as a JSON file in qpdf JSON format as written by ``qpdf --json-output``. The input file must be complete and include all stream data. For information about converting between - PDF and JSON, please see :ref:`qpdf-json`. + PDF and JSON, please see :ref:`json`. .. qpdf:option:: --update-from-json=qpdf-json-file .. help: update a PDF from qpdf JSON - Update a PDF file from a JSON file. Please see the "QPDF JSON - Format" section of the manual for information about how to use - this option. + Update a PDF file from a JSON file. Please see the "qpdf JSON" + chapter of the manual for information about how to use this + option. - This option updates a PDF file from a qpdf JSON file. For a - information about how to use this option, please see - :ref:`qpdf-json`. + This option updates a PDF file from the specified qpdf JSON file. + For a information about how to use this option, please see + :ref:`json`. .. _test-options: @@ -3420,7 +3432,7 @@ Related Options This is used by qpdf's test suite to check consistency between the output of ``qpdf --json`` and the output of ``qpdf --json-help``. - This option causes an extra copy of the generated json to appear in + This option causes an extra copy of the generated JSON to appear in memory and is therefore unsuitable for use with large files. This is why it's also not on by default. |