mirror of
https://github.com/qpdf/qpdf.git
synced 2024-06-01 18:00:52 +00:00
Editorial changes to cli.rst
This commit is contained in:
Jay Berkenbilt
parent
cf8405d91e
commit
acf8d18b6e
4
job.sums
4
job.sums
|
|
@ -2,7 +2,7 @@
|
|||
generate_auto_job 466aa9211549cebeb3fedc6413108981aeeddd89936621095f5f5223cee9880b
|
||||
job.yml 8177cadf41096efdc174f04daadfe5d98c592ad44ad10cb96537521fd79a801a
|
||||
libqpdf/qpdf/auto_job_decl.hh 97395ecbe590b23ae04d6cce2080dbd0e998917ff5eeaa5c6aafa91041d3cd6a
|
||||
libqpdf/qpdf/auto_job_help.hh 4dd6a958745b793320d0c657e23b670918e29f4d3dd6d78477d87df3eca2a910
|
||||
libqpdf/qpdf/auto_job_help.hh 9f4bd3e42510446a714771143e6a1db599a614818329d6c7126bb9fbcccd1f36
|
||||
libqpdf/qpdf/auto_job_init.hh 465bf46769559ceb77110d1b9d3293ba9b3595850b49848c31aeabd10aadb4ad
|
||||
manual/_ext/qpdf.py 855fe12de5af7a10bb24be6ecc4d5dff4c84ac58cf388a13be6bbb394346a67d
|
||||
manual/cli.rst e99e45275cdbc902b4860091453ae08e7b356da6301c5dc622982ec326e87e2a
|
||||
manual/cli.rst a1d5a72677eed46cfc91dba7cde8163107594adecb7f7362f0d402dea59833bd
|
||||
|
|
|
|||
|
|
@ -173,7 +173,7 @@ streams uncompressed intentionally.
|
|||
}
|
||||
static void add_help_3(QPDFArgParser& ap)
|
||||
{
|
||||
ap.addOptionHelp("--decode-level", "transformation", "control which streams to uncompress", R"(--decode-level=option
|
||||
ap.addOptionHelp("--decode-level", "transformation", "control which streams to uncompress", R"(--decode-level=parameter
|
||||
|
||||
When uncompressing streams, control which types of compression
|
||||
schemes should be uncompressed:
|
||||
|
|
@ -187,13 +187,13 @@ schemes should be uncompressed:
|
|||
with lossy compression schemes like JPEG (DCT)
|
||||
qpdf does not know how to uncompress all compression schemes.
|
||||
)");
|
||||
ap.addOptionHelp("--stream-data", "transformation", "control stream compression", R"(--stream-data=option
|
||||
ap.addOptionHelp("--stream-data", "transformation", "control stream compression", R"(--stream-data=parameter
|
||||
|
||||
This option controls how streams are compressed in the output.
|
||||
It is less granular than the newer options, --compress-streams
|
||||
and --decode-level.
|
||||
|
||||
Options:
|
||||
Parameters:
|
||||
- compress: same as --compress-streams=y --decode-level=generalized
|
||||
- preserve: same as --compress-streams=n --decode-level=none
|
||||
- uncompress: same as --compress-streams=n --decode-level=generalized
|
||||
|
|
@ -228,10 +228,10 @@ Control what qpdf does regarding object streams. Options:
|
|||
)");
|
||||
ap.addOptionHelp("--preserve-unreferenced", "transformation", "preserve unreferenced objects", R"(Preserve all objects from the input even if not referenced.
|
||||
)");
|
||||
ap.addOptionHelp("--remove-unreferenced-resources", "transformation", "remove unreferenced page resources", R"(--remove-unreferenced-resources=option
|
||||
ap.addOptionHelp("--remove-unreferenced-resources", "transformation", "remove unreferenced page resources", R"(--remove-unreferenced-resources=parameter
|
||||
|
||||
Remove from a page's resource dictionary any resources that are
|
||||
not referenced in the page's contents. Options: "auto"
|
||||
not referenced in the page's contents. Parameters: "auto"
|
||||
(default), "yes", "no".
|
||||
)");
|
||||
ap.addOptionHelp("--preserve-unreferenced-resources", "transformation", "use --remove-unreferenced-resources=no", R"(Synonym for --remove-unreferenced-resources=no. Use that instead.
|
||||
|
|
@ -283,7 +283,7 @@ Run qpdf --help=page-selection for details.
|
|||
ap.addOptionHelp("--collate", "modification", "collate with --pages", R"(--collate=n
|
||||
|
||||
Collate rather than concatenate pages specified with --pages.
|
||||
With a numeric argument, collate in groups of n. The default
|
||||
With a numeric parameter, collate in groups of n. The default
|
||||
is 1. Run qpdf --help=page-selection for additional details.
|
||||
)");
|
||||
}
|
||||
|
|
@ -321,11 +321,11 @@ ap.addOptionHelp("--flatten-rotation", "modification", "remove rotation from pag
|
|||
metadata. This can be useful if a broken PDF viewer fails to
|
||||
properly consider page rotation metadata.
|
||||
)");
|
||||
ap.addOptionHelp("--flatten-annotations", "modification", "push annotations into content", R"(--flatten-annotations=option
|
||||
ap.addOptionHelp("--flatten-annotations", "modification", "push annotations into content", R"(--flatten-annotations=parameter
|
||||
|
||||
Push page annotations into the content streams. This may be
|
||||
necessary in some case when printing or splitting files.
|
||||
Options: "all", "print", "screen".
|
||||
Parameters: "all", "print", "screen".
|
||||
)");
|
||||
ap.addOptionHelp("--rotate", "modification", "rotate pages", R"(--rotate=[+|-]angle[:page-range]
|
||||
|
||||
|
|
|
|||
|
|
@ -13,11 +13,34 @@
|
|||
for additional help. Command line arguments can be referenced using
|
||||
:qpdf:ref:`--option`. They also appear in an index.
|
||||
|
||||
STYLE NOTES
|
||||
|
||||
In this text, :samp:`...` and ``...`` are used somewhat
|
||||
interchangeably. :samp: should be used when there is replaceable
|
||||
text enclosed in curly braces. Otherwise, either is fine. Ideally
|
||||
there should be a stricter editorial convention, but they render
|
||||
the same, so I have not gone to the trouble of making it consistent.
|
||||
the same, so I have not gone to the trouble of making it
|
||||
consistent.
|
||||
|
||||
USE :qpdf:ref:`--option` to refer to an option whenever it is
|
||||
specified without parameters in any place other than its own help.
|
||||
This creates a link.
|
||||
|
||||
When referring to command-line options, use the following
|
||||
terminology:
|
||||
|
||||
argument: any command-line argument whether option or positional
|
||||
option: any argument starting with -- including its parameter, if any
|
||||
flag: the --flag part of the option; only use to disambiguate
|
||||
parameter: the parameter part of the option
|
||||
|
||||
Example: qpdf in.pdf --object-stream=generalized out.pdf
|
||||
|
||||
Each word is an argument.
|
||||
The "--object-stream=generalized" option consists of
|
||||
the "--object-stream" flag with the "generalized" parameter. It
|
||||
would be okay to talk about "the --object-stream option" in the
|
||||
text if there's no ambiguity.
|
||||
|
||||
.. _using:
|
||||
|
||||
|
|
@ -58,23 +81,24 @@ Basic Invocation
|
|||
The :command:`qpdf` command reads the PDF file :samp:`{infile}`,
|
||||
applies various transformations or modifications to the file in
|
||||
memory, and writes the results to :samp:`{outfile}`. When run with no
|
||||
arguments, the output file is functionally identical to the input file
|
||||
options, the output file is functionally identical to the input file
|
||||
but may be structurally reorganized, and orphaned objects are removed
|
||||
from the file. Many options are available for applying transformations
|
||||
or modifications to the file.
|
||||
|
||||
:samp:`{infile}` can be a regular file, or it can be
|
||||
:qpdf:ref:`--empty` to start with an empty PDF file. :samp:`{outfile}`
|
||||
can be a regular file, ``-`` to represent standard output, or
|
||||
:qpdf:ref:`--replace-input` to indicate that the input file should be
|
||||
overwritten. The output file does not have to be seekable, even when
|
||||
generating linearized files. The input file *does* have to be
|
||||
seekable. You can't read from standard input or a pipe. You can also
|
||||
use :qpdf:ref:`--split-pages` to create separate output files for each
|
||||
:qpdf:ref:`--empty` to start with an empty PDF file. There is no way
|
||||
to use standard input since the input file has to be seekable.
|
||||
|
||||
:samp:`{outfile}` can be a regular file, ``-`` to represent standard
|
||||
output, or :qpdf:ref:`--replace-input` to indicate that the input file
|
||||
should be overwritten. The output file does not have to be seekable,
|
||||
even when generating linearized files. You can also use
|
||||
:qpdf:ref:`--split-pages` to create separate output files for each
|
||||
page (or group of pages) instead of a single output file.
|
||||
|
||||
Password-protected files may be opened by specifying a password with
|
||||
:qpdf:ref:`--password`. These and many other options are discussed in
|
||||
the remaining sections of this chapter.
|
||||
:qpdf:ref:`--password`.
|
||||
|
||||
All options other than help options (see :ref:`help-options`) require
|
||||
an input file. If inspection options (see :ref:`inspection-options`)
|
||||
|
|
@ -92,8 +116,8 @@ is also very useful for avoiding having to pass passwords on the
|
|||
command line, though see also :qpdf:ref:`--password-file`. Note that
|
||||
the :samp:`@filename` can't appear in the middle of an argument, so
|
||||
constructs such as :samp:`--arg=@filename` will not work. Instead, you
|
||||
would have to include the argument and its parameter (e.g.,
|
||||
:samp:`--arg=parameter`) as a line in the :file:`filename` file and
|
||||
would have to include the option and its parameter (e.g.,
|
||||
:samp:`--option=parameter`) as a line in the :file:`filename` file and
|
||||
just pass :samp:`@filename` on the command line.
|
||||
|
||||
Related Options
|
||||
|
|
@ -501,7 +525,7 @@ Related Options
|
|||
Overrides the usual computation/retrieval of the PDF file's
|
||||
encryption key from user/owner password with an explicit
|
||||
specification of the encryption key. When this option is specified,
|
||||
the argument to the :qpdf:ref:`--password` option is interpreted as
|
||||
the parameter to the :qpdf:ref:`--password` option is interpreted as
|
||||
a hexadecimal-encoded key value. This only applies to the password
|
||||
used to open the main input file. It does not apply to other files
|
||||
opened by :qpdf:ref:`--pages` or other options or to files being
|
||||
|
|
@ -791,7 +815,7 @@ Related Options
|
|||
:samp:`--compress-streams=n`. In QDF mode (see :ref:`qdf` and
|
||||
:qpdf:ref:`--qdf`), the default is to leave streams uncompressed.
|
||||
|
||||
.. qpdf:option:: --decode-level=option
|
||||
.. qpdf:option:: --decode-level=parameter
|
||||
|
||||
.. help: control which streams to uncompress
|
||||
|
||||
|
|
@ -810,7 +834,7 @@ Related Options
|
|||
Controls which streams qpdf tries to decode. The default is
|
||||
:samp:`generalized`.
|
||||
|
||||
The following options are available:
|
||||
The following values for :samp:`{parameter}` are available:
|
||||
|
||||
- :samp:`none`: do not attempt to decode any streams
|
||||
|
||||
|
|
@ -847,7 +871,7 @@ Related Options
|
|||
are not uncompressed and recompressed. You can change this behavior
|
||||
with :qpdf:ref:`--recompress-flate`.
|
||||
|
||||
.. qpdf:option:: --stream-data=option
|
||||
.. qpdf:option:: --stream-data=parameter
|
||||
|
||||
.. help: control stream compression
|
||||
|
||||
|
|
@ -855,7 +879,7 @@ Related Options
|
|||
It is less granular than the newer options, --compress-streams
|
||||
and --decode-level.
|
||||
|
||||
Options:
|
||||
Parameters:
|
||||
- compress: same as --compress-streams=y --decode-level=generalized
|
||||
- preserve: same as --compress-streams=n --decode-level=none
|
||||
- uncompress: same as --compress-streams=n --decode-level=generalized
|
||||
|
|
@ -863,7 +887,7 @@ Related Options
|
|||
Controls transformation of stream data. This option predates the
|
||||
:qpdf:ref:`--compress-streams` and :qpdf:ref:`--decode-level`
|
||||
options. Those options can be used to achieve the same affect with
|
||||
more control. The value of :samp:`{option}` may be one of the
|
||||
more control. The value of :samp:`{parameter}` may be one of the
|
||||
following:
|
||||
|
||||
- :samp:`compress`: recompress stream data when possible (default);
|
||||
|
|
@ -1009,15 +1033,15 @@ Related Options
|
|||
See also :qpdf:ref:`--preserve-unreferenced-resources`, which does
|
||||
something completely different.
|
||||
|
||||
.. qpdf:option:: --remove-unreferenced-resources=option
|
||||
.. qpdf:option:: --remove-unreferenced-resources=parameter
|
||||
|
||||
.. help: remove unreferenced page resources
|
||||
|
||||
Remove from a page's resource dictionary any resources that are
|
||||
not referenced in the page's contents. Options: "auto"
|
||||
not referenced in the page's contents. Parameters: "auto"
|
||||
(default), "yes", "no".
|
||||
|
||||
Options: ``auto`` (the default), ``yes``, or ``no``.
|
||||
Parameters: ``auto`` (the default), ``yes``, or ``no``.
|
||||
|
||||
Starting with qpdf 8.1, when splitting pages, qpdf is able to
|
||||
attempt to remove images and fonts that are not used by a page even
|
||||
|
|
@ -1189,8 +1213,8 @@ Page Ranges
|
|||
:even starts with the second page. These are odd and even pages
|
||||
from the resulting set, not based on the original page numbers.
|
||||
|
||||
Several :command:`qpdf` command-line arguments accept page ranges as
|
||||
options. This section describes the syntax of a page range.
|
||||
Several :command:`qpdf` command-line options use page ranges. This
|
||||
section describes the syntax of a page range.
|
||||
|
||||
- A plain number indicates a page numbered from ``1``, so ``1``
|
||||
represents the first page.
|
||||
|
|
@ -1290,12 +1314,12 @@ Related Options
|
|||
.. help: collate with --pages
|
||||
|
||||
Collate rather than concatenate pages specified with --pages.
|
||||
With a numeric argument, collate in groups of n. The default
|
||||
With a numeric parameter, collate in groups of n. The default
|
||||
is 1. Run qpdf --help=page-selection for additional details.
|
||||
|
||||
This option causes :command:`qpdf` to collate rather than
|
||||
concatenate pages specified with :qpdf:ref:`--pages`. With a
|
||||
numeric argument, collate in groups of :samp:`{n}`. The default
|
||||
numeric parameter, collate in groups of :samp:`{n}`. The default
|
||||
is 1.
|
||||
|
||||
Please see :ref:`page-selection` for additional details.
|
||||
|
|
@ -1403,13 +1427,13 @@ Related Options
|
|||
reason to use this option unless you are working around a specific
|
||||
problem.
|
||||
|
||||
.. qpdf:option:: --flatten-annotations=option
|
||||
.. qpdf:option:: --flatten-annotations=parameter
|
||||
|
||||
.. help: push annotations into content
|
||||
|
||||
Push page annotations into the content streams. This may be
|
||||
necessary in some case when printing or splitting files.
|
||||
Options: "all", "print", "screen".
|
||||
Parameters: "all", "print", "screen".
|
||||
|
||||
This option collapses annotations into the pages' contents with
|
||||
special handling for form fields. Ordinarily, an annotation is
|
||||
|
|
@ -1419,10 +1443,10 @@ Related Options
|
|||
transformations. The library functionality backing this option was
|
||||
added for the benefit of programs that want to create *n-up* page
|
||||
layouts and other similar things that don't work well with
|
||||
annotations. The :samp:`{option}` parameter may be any of the
|
||||
annotations. The value of :samp:`{parameter}` may be any of the
|
||||
following:
|
||||
|
||||
.. list-table:: Flatten Annotation Options
|
||||
.. list-table:: Flatten Annotation Parameters
|
||||
:widths: 10 80
|
||||
:header-rows: 0
|
||||
|
||||
|
|
@ -2168,7 +2192,7 @@ repeat the following:
|
|||
:samp:`{filename} [ --password={password} ] [ {page-range} ]`
|
||||
|
||||
Notes:
|
||||
- The password argument is needed only for password-protected files.
|
||||
- The password option is needed only for password-protected files.
|
||||
If you specify the same file more than once, you only need to supply
|
||||
the password the first time.
|
||||
|
||||
|
|
@ -2255,7 +2279,7 @@ Examples
|
|||
|
||||
- a.pdf page 5
|
||||
|
||||
- You can specify a numeric argument to :qpdf:ref:`--collate`. With
|
||||
- You can specify a numeric parameter to :qpdf:ref:`--collate`. With
|
||||
:samp:`--collate={n}`, pull groups of :samp:`{n}` pages from each
|
||||
file, as always, stopping when there are no more pages. For example,
|
||||
if you ran
|
||||
|
|
@ -2917,7 +2941,7 @@ Related Options
|
|||
:qpdf:ref:`--check` or :qpdf:ref:`--show-encryption` is given, display the
|
||||
computed or retrieved encryption key as a hexadecimal string. This
|
||||
value is not ordinarily useful to users, but it can be used as the
|
||||
argument to :qpdf:ref:`--password` if the :qpdf:ref:`--password-is-hex-key`
|
||||
parameter to :qpdf:ref:`--password` if the :qpdf:ref:`--password-is-hex-key`
|
||||
is specified. Note that, when PDF files are encrypted, passwords
|
||||
and other metadata are used only to compute an encryption key, and
|
||||
the encryption key is what is actually used for encryption. This
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user