octoleo/qpdf
2
1
Fork 0
mirror of https://github.com/qpdf/qpdf.git synced 2025-01-31 19:08:24 +00:00
Code Issues Releases Wiki Activity

Editorial changes to cli.rst

Browse Source
This commit is contained in:
Jay Berkenbilt 2022-01-20 07:58:09 -05:00
parent cf8405d91e
commit acf8d18b6e
3 changed files with 67 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
job.sums
View File

@ -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

16
libqpdf/qpdf/auto_job_help.hh
View File

@ -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]

90
manual/cli.rst
View File

@ -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