2
1
mirror of https://github.com/qpdf/qpdf.git synced 2024-06-18 18:02:21 +00:00

Incorporate editorial changes from m-holger

This commit is contained in:
Jay Berkenbilt 2022-01-27 12:18:47 -05:00
parent 7dd5f31230
commit f3d68aa5a0
5 changed files with 154 additions and 136 deletions

View File

@ -159,8 +159,11 @@ class Main:
if long_text == '': if long_text == '':
raise Exception(f'missing long text for {topic}') raise Exception(f'missing long text for {topic}')
long_text += '\n' long_text += '\n'
for i in re.finditer(r'--help=([^\.\s]+)', long_text): if topic != '--help':
self.referenced_topics.add(i.group(1)) # 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 True
return False return False

View File

@ -1,5 +1,5 @@
# Generated by generate_auto_job # 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_att.hh 7ad43bb374c1370ef32ebdcdcb7b73a61d281f7f4e3f12755585872ab30fb60e
include/qpdf/auto_job_c_copy_att.hh 32275d03cdc69b703dd7e02ba0bbe15756e714e9ad185484773a6178dc09e1ee include/qpdf/auto_job_c_copy_att.hh 32275d03cdc69b703dd7e02ba0bbe15756e714e9ad185484773a6178dc09e1ee
include/qpdf/auto_job_c_enc.hh 72e138c7b96ed5aacdce78c1dec04b1c20d361faec4f8faf52f64c1d6be99265 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 include/qpdf/auto_job_c_uo.hh 0585b7de459fa479d9e51a45fa92de0ff6dee748efc9ec1cedd0dde6cee1ad50
job.yml 1590fd16fd17ed40db9aa56b6713c844cfd61b3a6d0441a3ccd122b7371c68e9 job.yml 1590fd16fd17ed40db9aa56b6713c844cfd61b3a6d0441a3ccd122b7371c68e9
libqpdf/qpdf/auto_job_decl.hh 9f79396ec459f191be4c5fe34cf88c265cf47355a1a945fa39169d1c94cf04f6 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_init.hh 3b6323189480a7d782563c9d2b5bc29b8dcd19c6dcc89840b207e38cb503d3f1
libqpdf/qpdf/auto_job_schema.hh 1c3b4b5488270f8d200ed345573e3a241f15baff6fb7e97ec3d044103b2546d9 libqpdf/qpdf/auto_job_schema.hh 1c3b4b5488270f8d200ed345573e3a241f15baff6fb7e97ec3d044103b2546d9
manual/_ext/qpdf.py e9ac9d6c70642a3d29281ee5ad92ae2422dee8be9306fb8a0bc9dba0ed5e28f3 manual/_ext/qpdf.py e9ac9d6c70642a3d29281ee5ad92ae2422dee8be9306fb8a0bc9dba0ed5e28f3
manual/cli.rst 06785f88a28703da0f6d81b6983ae6c09aa1dd8cd958fb5058d56177da431c6c manual/cli.rst 9aecd2905844fbda5cd528afd7fedef693ac0958bcb20e235f1c8e10a1896abe

View File

@ -54,8 +54,11 @@ ap.addOptionHelp("--completion-zsh", "completion", "enable zsh completion", R"(O
ap.addHelpTopic("help", "information about qpdf", R"(Help options provide some information about qpdf itself. Help 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. 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 ap.addOptionHelp("--help", "help", "provide help", R"(--help[=--option|topic]
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
)"); )");
ap.addOptionHelp("--version", "help", "show qpdf version", R"(Display the version of qpdf. 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 ap.addOptionHelp("--password", "general", "specify password", R"(--password=password
Specify a password for an encrypted, password-protected file. 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 ap.addOptionHelp("--password-file", "general", "read password from a file", R"(--password-file=filename
@ -119,9 +122,9 @@ ap.addOptionHelp("--password-is-hex-key", "advanced-control", "provide hex-encod
string rather than supplying a password. This is an expert string rather than supplying a password. This is an expert
option. 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 ap.addOptionHelp("--suppress-password-recovery", "advanced-control", "don't try different password encodings", R"(Suppress qpdf's usual behavior of attempting different encodings
password that contains non-ASCII Unicode characters if the first of a password that contains non-ASCII Unicode characters if the
attempt doesn't succeed. first attempt doesn't succeed.
)"); )");
ap.addOptionHelp("--password-mode", "advanced-control", "tweak how qpdf encodes passwords", R"(--password-mode=mode 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("--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. 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. 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 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 All streams that can be uncompressed are uncompressed, and
content streams are normalized, among other changes. The content streams are normalized, among other changes. The
companion tool "fix-qdf" can be used to repair hand-edited QDF 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 files. QDF is a feature specific to the qpdf tool. Please see
chapter about it in the manual. 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 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. 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 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 Force the PDF version of the output to be at least the specified
specified version. 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 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 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. 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. 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 Page ranges are single page numbers for single-page groups or first-last
for multi-page groups. 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. Overlay pages from another file on the output.
Run qpdf --help=overlay-underlay for details. 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. Underlay pages from another file on the output.
Run qpdf --help=overlay-underlay for details. Run qpdf --help=overlay-underlay for details.
@ -375,7 +381,7 @@ ap.addOptionHelp("--remove-page-labels", "modification", "remove explicit page n
)"); )");
ap.addHelpTopic("encryption", "create encrypted files", R"(Create encrypted files. Usage: 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 Either or both of user-password and owner-password may be empty
strings. key-length may be 40, 128, or 256. Encryption options are 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: 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 ] \ qpdf in.pdf --pages input-file [--password=password] [page-range] \
[ ... ] -- out.pdf [...] -- out.pdf
Between --pages and the -- that terminates pages option, repeat Between --pages and the -- that terminates pages option, repeat
the following: the following:
filename [ --password=password ] [ page-range ] filename [--password=password] [page-range]
Document-level information, such as outlines, tags, etc., is taken 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 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: drawn below the destination page. Usage:
{--overlay | --underlay } file {--overlay | --underlay } file
[ --password=password ] [--password=password]
[ --to=page-range ] [--to=page-range]
[ --from=[page-range] ] [--from=[page-range]]
[ --repeat=page-range ] [--repeat=page-range]
-- --
Note the use of "--" by itself to terminate overlay/underlay options. Note the use of "--" by itself to terminate overlay/underlay options.

View File

@ -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}`, The :command:`qpdf` command reads the PDF file :samp:`{infile}`,
applies various transformations or modifications to the file in 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 Related Options
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
.. qpdf:option:: --help .. qpdf:option:: --help[=--option|topic]
.. help: provide help .. help: provide help
Display help information. Run qpdf --help for information about --help: provide general information and a list of topics
how to get help on various 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 .. qpdf:option:: --version
@ -357,7 +360,7 @@ Related Options
.. help: specify password .. help: specify password
Specify a password for an encrypted, password-protected file. 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 Specifies a password for accessing encrypted, password-protected
files. To read the password from a file or standard input, you can 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 password for accessing encrypted files. :samp:`{filename}` may be
``-`` to read the password from standard input, but if you do that ``-`` to read the password from standard input, but if you do that
the password is echoed and there is no prompt, so use ``-`` with 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 .. qpdf:option:: --verbose
@ -407,9 +411,9 @@ Related Options
Indicate progress when writing files. Indicate progress when writing files.
Indicate progress while writing output files. Progress indication Indicate progress while writing output files. Progress indication
does not start until writing starts, so if complicated does not start until writing starts, so there may be a delay before
transformations are being applied before the write process begins, progress indicators are seen if complicated transformations are
there may be a delay before progress indicators are seen. being applied before the write process begins.
.. qpdf:option:: --no-warn .. qpdf:option:: --no-warn
@ -435,23 +439,25 @@ Related Options
information, such as the page contents. Does not use the file's information, such as the page contents. Does not use the file's
name or attributes or the current time. name or attributes or the current time.
Generate of a secure, random document ID using deterministic Generate a secure, random document ID using deterministic values.
values. This prevents use of timestamp and output file name This prevents use of timestamp and output file name information in
information in the ID generation. Instead, at some slight the ID generation. Instead, at some slight additional runtime cost,
additional runtime cost, the ID field is generated to include a the ID field is generated to include a digest of the significant
digest of the significant parts of the content of the output PDF parts of the content of the output PDF file. This means that a
file. This means that a given qpdf operation should generate the given qpdf operation should generate the same ID each time it is
same ID each time it is run, which can be useful when caching run, which can be useful when caching results or for generation of
results or for generation of some test data. Use of this flag is some test data. Use of this flag is not compatible with creation of
not compatible with creation of encrypted files. encrypted files. This option can be useful for testing. See also
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
:qpdf:ref:`--static-id`. :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 .. qpdf:option:: --allow-weak-crypto
.. help: allow insecure cryptographic algorithms .. help: allow insecure cryptographic algorithms
@ -561,9 +567,9 @@ Related Options
.. help: don't try different password encodings .. help: don't try different password encodings
Suppress qpdf's behavior of attempting different encodings of a Suppress qpdf's usual behavior of attempting different encodings
password that contains non-ASCII Unicode characters if the first of a password that contains non-ASCII Unicode characters if the
attempt doesn't succeed. first attempt doesn't succeed.
Ordinarily, qpdf attempts to automatically compensate for passwords Ordinarily, qpdf attempts to automatically compensate for passwords
encoded with the wrong character encoding. This option suppresses 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 transformations that change the structure of a PDF file without
changing its content. Examples include creating linearized changing its content. Examples include creating linearized
(web-optimized) files, adding or removing encryption, restructuring (web-optimized) files, adding or removing encryption, restructuring
files for older viewers, and rewriting files for human inspection, files for older viewers, and rewriting files for human inspection. See
among others. See also :ref:`modification-options`. also :ref:`modification-options`.
Related Options Related Options
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
@ -685,17 +691,14 @@ Related Options
important cross-reference information typically appears at the end important cross-reference information typically appears at the end
of the file. 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 .. help: start encryption options
Run qpdf --help=encryption for details. Run qpdf --help=encryption for details.
This flag starts encryption options, used to create encrypted This flag starts encryption options, used to create encrypted
files. files. Please see :ref:`encryption-options` for details.
Please see :ref:`encryption-options` for details about creating
encrypted files.
.. qpdf:option:: --decrypt .. qpdf:option:: --decrypt
@ -720,19 +723,19 @@ Related Options
preserving the input file's encryption. Use --encryption-file-password preserving the input file's encryption. Use --encryption-file-password
to specify the encryption file's password. to specify the encryption file's password.
Copy encryption parameters, including the user password, the owner Copy all encryption parameters, including the user password, the
password, and all security restrictions, from the specified file owner password, and all security restrictions, from the specified
instead of preserving encryption details from the input file. This file instead of preserving the encryption details from the input
works even if only one of the user password or owner password is file. This works even if only one of the user password or owner
known. If the encryption file requires a password, use the password is known. If the encryption file requires a password, use
:qpdf:ref:`--encryption-file-password` option to set it. Note that the :qpdf:ref:`--encryption-file-password` option to set it. Note
copying the encryption parameters from a file also copies the first that copying the encryption parameters from a file also copies the
half of ``/ID`` from the file since this is part of the encryption first half of ``/ID`` from the file since this is part of the
parameters. This option can be useful if you need to decrypt a file encryption parameters. This option can be useful if you need to
to make manual changes to it or to change it outside of qpdf, and decrypt a file to make manual changes to it or to change it outside
then want to restore the original encryption on the file of qpdf, and then want to restore the original encryption on the
without having to manual specify all the individual settings. See file without having to manual specify all the individual settings.
also :qpdf:ref:`--decrypt`. See also :qpdf:ref:`--decrypt`.
.. qpdf:option:: --encryption-file-password=password .. qpdf:option:: --encryption-file-password=password
@ -752,12 +755,12 @@ Related Options
.. help: enable viewing PDF code in a text editor .. help: enable viewing PDF code in a text editor
Create a PDF file suitable for viewing in a text editor and even 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 All streams that can be uncompressed are uncompressed, and
content streams are normalized, among other changes. The content streams are normalized, among other changes. The
companion tool "fix-qdf" can be used to repair hand-edited QDF 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 files. QDF is a feature specific to the qpdf tool. Please see
chapter about it in the manual. the "QDF Mode" chapter in the manual.
Create a PDF file suitable for viewing and editing in a text 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 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 and content streams are normalized, among other changes. The
companion tool :command:`fix-qdf` can be used to repair hand-edited companion tool :command:`fix-qdf` can be used to repair hand-edited
QDF files. QDF is a feature specific to the qpdf tool. For 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. :qpdf:ref:`--linearize` disables QDF mode.
QDF mode has full support for object streams, but sometimes it's QDF mode has full support for object streams, but sometimes it's
easier to locate a specific object if object streams are disabled. easier to locate a specific object if object streams are disabled.
When trying to understand some PDF construct by inspecting an 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`. :samp:`--object-streams=disable`.
This flag changes some of the defaults of other options: stream 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 When normalizing content, if qpdf runs into any lexical errors, it
will print a warning indicating that content may be damaged. If you will print a warning indicating that content may be damaged. If you
want to create QDF files without content normalization, can you run want to create QDF files without content normalization, specify
with :samp:`--qdf --normalize-content=n`. You can also create a :samp:`--qdf --normalize-content=n`. You can also create a non-QDF
non-QDF file with uncompressed streams using file with uncompressed streams using
:samp:`--stream-data=uncompress`. These will both uncompress all :samp:`--stream-data=uncompress`. Either option will uncompress all
the streams but will not attempt to normalize content. Please note the streams but will not attempt to normalize content. Please note
that if you are using content normalization or QDF mode for the that if you are using content normalization or QDF mode for the
purpose of manually inspecting files, you don't have to care about 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 These are left untouched regardless of the option. Future versions
of qpdf may support additional filters. of qpdf may support additional filters.
Because the default value is ``generalized``, by default, when a stream Because the default value is ``generalized``, qpdf's default
is encoded using non-lossy filters that qpdf understands and is not behavior is to uncompress any stream that is encoded using
already compressed using a good compression scheme, qpdf will non-lossy filters that qpdf understands. If
uncompress the stream. If ``--compress-streams=y`` is also in ``--compress-streams=y`` is also in effect, which is the default
effect, which is the default (see :qpdf:ref:`--compress-streams`), (see :qpdf:ref:`--compress-streams`), the overall effect is that
the overall effect is that qpdf will recompress streams with qpdf will recompress streams with generalized filters using flate
generalized filters using flate compression, effectively compression, effectively eliminating LZW and ASCII-based filters.
eliminating LZW and ASCII-based filters. This is usually desirable This is usually desirable behavior but can be disabled with
behavior but can be disabled with ``--decode-level=none``. ``--decode-level=none``.
As a special case, streams already compressed with ``/FlateDecode`` As a special case, streams already compressed with ``/FlateDecode``
are not uncompressed and recompressed. You can change this behavior are not uncompressed and recompressed. You can change this behavior
@ -956,7 +959,8 @@ Related Options
already compressed streams, you should also specify already compressed streams, you should also specify
:qpdf:ref:`--recompress-flate`. If your goal is to shrink the size :qpdf:ref:`--recompress-flate`. If your goal is to shrink the size
of PDF files, you should also use 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] .. qpdf:option:: --normalize-content=[yn]
@ -1002,10 +1006,10 @@ Related Options
- create object streams, and compress objects when possible - create object streams, and compress objects when possible
Object streams are PDF streams that contain other objects. Putting 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 compressed, which can result in much smaller PDF files. Combining
this option with :qpdf:ref:`--compression-level` and 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. smaller PDF files.
Object streams, also known as compressed objects, were introduced 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 used to transform files with object streams into files without object
streams or vice versa. 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 streams that contain them is preserved from the original file. If
the file has no object streams, qpdf will not add any. In the file has no object streams, qpdf will not add any. In
:samp:`disable` mode, all objects are written as regular, :samp:`disable` mode, all objects are written as regular,
@ -1040,7 +1044,7 @@ Related Options
objects. objects.
This flag is ignored for linearized files and has the effect of 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 from the original file. This does not mean that object numbers will
be the same since qpdf may create stream lengths as direct or be the same since qpdf may create stream lengths as direct or
indirect differently from the original file, and the original file indirect differently from the original file, and the original file
@ -1157,8 +1161,11 @@ Related Options
.. help: set minimum PDF version .. help: set minimum PDF version
Force the PDF version of the output to be at least the Force the PDF version of the output to be at least the specified
specified version. 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 Force the PDF version of the output file to be at least
:samp:`{version}`. In other words, if the input file has a lower :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. when adding features that require newer PDF readers.
The version number may be expressed in the form The version number may be expressed in the form
:samp:`{major.minor.extension-level}`, in which case the version is :samp:`{major}.{minor}[.{extension-level}]`. If
interpreted as :samp:`{major.minor}` at extension level :samp:`.{extension-level}`, is given, version is interpreted as
:samp:`{extension-level}`. For example, version ``1.7.8`` :samp:`{major.minor}` at extension level :samp:`{extension-level}`.
represents version 1.7 at extension level 8. Note that minimal For example, version ``1.7.8`` represents version 1.7 at extension
syntax checking is done on the command line. :command:`qpdf` does level 8. Note that minimal syntax checking is done on the command
not check whether the specified version is actually required. line. :command:`qpdf` does not check whether the specified version
is actually required.
.. qpdf:option:: --force-version=version .. 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 version to be lower than that of the input file will cause qpdf to
disable certain features of the document. Specifically, 256-bit disable certain features of the document. Specifically, 256-bit
keys are disabled if the version is less than 1.7 with extension 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 8 (except the deprecated, unsupported "R5" format is allowed
level 3), AES encryption is disabled if the version is less than with extension levels 3 through 7), AES encryption is disabled if
1.6, cleartext metadata and object streams are disabled if less the version is less than 1.6, cleartext metadata and object streams
than 1.5, 128-bit encryption keys are disabled if less than 1.4, are disabled if less than 1.5, 128-bit encryption keys are disabled
and all encryption is disabled if less than 1.3. Even with these if less than 1.4, and all encryption is disabled if less than 1.3.
precautions, qpdf won't be able to do things like eliminate use of Even with these precautions, qpdf won't be able to do things like
newer image compression schemes, transparency groups, or other eliminate use of newer image compression schemes, transparency
features that may have been added in more recent versions of PDF. 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 As a general rule, with the exception of big structural things like
the use of object streams or AES encryption, PDF viewers are the use of object streams or AES encryption, PDF viewers are
supposed to ignore features in files that they don't support from supposed to ignore features they don't support. This means that
newer versions. This means that forcing the version to a lower forcing the version to a lower version may make it possible to open
version may make it possible to open your PDF file with an older your PDF file with an older version, though bear in mind that some
version, though bear in mind that some of the original document's of the original document's functionality may be lost.
functionality may be lost.
.. _page-ranges: .. _page-ranges:
@ -1310,7 +1318,7 @@ PDF, causing the PDF to render differently from the original. See also
Related Options Related Options
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
.. qpdf:option:: --pages file [ --password=password ] [ page-range ] [ ... ] -- .. qpdf:option:: --pages file [--password=password] [page-range] [...] --
.. help: begin page selection .. help: begin page selection
@ -1405,7 +1413,7 @@ Related Options
if you don't require the document-level data. A future version of if you don't require the document-level data. A future version of
qpdf may support preservation of some document-level information. qpdf may support preservation of some document-level information.
.. qpdf:option:: --overlay file [ options ] -- .. qpdf:option:: --overlay file [options] --
.. help: begin overlay options .. help: begin overlay options
@ -1416,7 +1424,7 @@ Related Options
See :ref:`overlay-underlay` for details. See :ref:`overlay-underlay` for details.
.. qpdf:option:: --underlay file [ options ] -- .. qpdf:option:: --underlay file [options] --
.. help: begin underlay options .. help: begin underlay options
@ -1674,7 +1682,7 @@ Encryption
Create encrypted files. Usage: 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 Either or both of user-password and owner-password may be empty
strings. key-length may be 40, 128, or 256. Encryption options are 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}` Either or both of :samp:`{user-password}` and :samp:`{owner-password}`
may be empty strings. :samp:`{key-length}` may be ``40``, ``128``, or 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 Here is a summary of encryption options. Details are provided in the
help for each option. help for each option.
.. list-table:: Options for 40-bit Encryption Only .. list-table:: Options for 40-bit Encryption Only
:widths: 30 70 :widths: 30 70
:header-rows: 0 :header-rows: 0
@ -2154,13 +2161,13 @@ Page Selection
Use the --pages option to select pages from multiple files. Usage: Use the --pages option to select pages from multiple files. Usage:
qpdf in.pdf --pages input-file [ --password=password ] [ page-range ] \ qpdf in.pdf --pages input-file [--password=password] [page-range] \
[ ... ] -- out.pdf [...] -- out.pdf
Between --pages and the -- that terminates pages option, repeat Between --pages and the -- that terminates pages option, repeat
the following: the following:
filename [ --password=password ] [ page-range ] filename [--password=password] [page-range]
Document-level information, such as outlines, tags, etc., is taken 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 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 split and merge PDF files by selecting pages from one or more input
files. 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, Between ``--pages`` and the ``--`` that terminates pages option,
repeat the following: repeat the following:
:samp:`{filename} [ --password={password} ] [ {page-range} ]` :samp:`{filename} [--password={password}] [{page-range}]`
Notes: Notes:
- The password option is needed only for password-protected files. - The password option is needed only for password-protected files.
@ -2424,10 +2431,10 @@ Overlay and Underlay
drawn below the destination page. Usage: drawn below the destination page. Usage:
{--overlay | --underlay } file {--overlay | --underlay } file
[ --password=password ] [--password=password]
[ --to=page-range ] [--to=page-range]
[ --from=[page-range] ] [--from=[page-range]]
[ --repeat=page-range ] [--repeat=page-range]
-- --
Note the use of "--" by itself to terminate overlay/underlay options. 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 Overlay and underlay options are processed late, so they can be
combined with other options like merging and will apply to the final combined with other options like merging and will apply to the final

View File

@ -3,6 +3,8 @@
QDF Mode 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 In QDF mode, qpdf creates PDF files in what we call *QDF
form*. A PDF file in QDF form, sometimes called a 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 file, is a completely valid PDF file that has ``%QDF-1.0`` as its third