2
1
mirror of https://github.com/qpdf/qpdf.git synced 2024-12-22 10:58:58 +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,6 +159,9 @@ class Main:
if long_text == '':
raise Exception(f'missing long text for {topic}')
long_text += '\n'
if topic != '--help':
# 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

View File

@ -1,5 +1,5 @@
# 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_copy_att.hh 32275d03cdc69b703dd7e02ba0bbe15756e714e9ad185484773a6178dc09e1ee
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
job.yml 1590fd16fd17ed40db9aa56b6713c844cfd61b3a6d0441a3ccd122b7371c68e9
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_schema.hh 1c3b4b5488270f8d200ed345573e3a241f15baff6fb7e97ec3d044103b2546d9
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
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
how to get help on various topics.
ap.addOptionHelp("--help", "help", "provide help", R"(--help[=--option|topic]
--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.
)");
@ -70,7 +73,7 @@ directly related to the operation it is performing.
ap.addOptionHelp("--password", "general", "specify password", R"(--password=password
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
@ -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
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
password that contains non-ASCII Unicode characters if the first
attempt doesn't succeed.
ap.addOptionHelp("--suppress-password-recovery", "advanced-control", "don't try different password encodings", R"(Suppress qpdf's usual behavior of attempting different encodings
of a password that contains non-ASCII Unicode characters if the
first attempt doesn't succeed.
)");
ap.addOptionHelp("--password-mode", "advanced-control", "tweak how qpdf encodes passwords", R"(--password-mode=mode
@ -159,12 +162,12 @@ If the file named in --copy-encryption requires a password, use
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
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
content streams are normalized, among other changes. The
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
chapter about it in the manual.
files. QDF is a feature specific to the qpdf tool. Please see
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
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
Force the PDF version of the output to be at least the
specified version.
Force the PDF version of the output to be at least the specified
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

View File

@ -294,14 +294,17 @@ are only valid as the first and only command-line argument.
Related Options
~~~~~~~~~~~~~~~
.. qpdf:option:: --help
.. qpdf:option:: --help[=--option|topic]
.. help: provide help
Display help information. Run qpdf --help for information about
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
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
@ -357,7 +360,7 @@ Related Options
.. help: specify password
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
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
``-`` to read the password from standard input, but if you do that
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
@ -407,9 +411,9 @@ Related Options
Indicate progress when writing files.
Indicate progress while writing output files. Progress indication
does not start until writing starts, so if complicated
transformations are being applied before the write process begins,
there may be a delay before progress indicators are seen.
does not start until writing starts, so there may be a delay before
progress indicators are seen if complicated transformations are
being applied before the write process begins.
.. qpdf:option:: --no-warn
@ -435,23 +439,25 @@ Related Options
information, such as the page contents. Does not use the file's
name or attributes or the current time.
Generate of a secure, random document ID using deterministic
values. This prevents use of timestamp and output file name
information in the ID generation. Instead, at some slight
additional runtime cost, the ID field is generated to include a
digest of the significant parts of the content of the output PDF
file. This means that a given qpdf operation should generate the
same ID each time it is run, which can be useful when caching
results or for generation of some test data. Use of this flag is
not compatible with creation of encrypted files.
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
Generate a secure, random document ID using deterministic values.
This prevents use of timestamp and output file name information in
the ID generation. Instead, at some slight additional runtime cost,
the ID field is generated to include a digest of the significant
parts of the content of the output PDF file. This means that a
given qpdf operation should generate the same ID each time it is
run, which can be useful when caching results or for generation of
some test data. Use of this flag is not compatible with creation of
encrypted files. This option can be useful for testing. See also
: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
.. help: allow insecure cryptographic algorithms
@ -561,9 +567,9 @@ Related Options
.. help: don't try different password encodings
Suppress qpdf's behavior of attempting different encodings of a
password that contains non-ASCII Unicode characters if the first
attempt doesn't succeed.
Suppress qpdf's usual behavior of attempting different encodings
of a password that contains non-ASCII Unicode characters if the
first attempt doesn't succeed.
Ordinarily, qpdf attempts to automatically compensate for passwords
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
changing its content. Examples include creating linearized
(web-optimized) files, adding or removing encryption, restructuring
files for older viewers, and rewriting files for human inspection,
among others. See also :ref:`modification-options`.
files for older viewers, and rewriting files for human inspection. See
also :ref:`modification-options`.
Related Options
~~~~~~~~~~~~~~~
@ -692,10 +698,7 @@ Related Options
Run qpdf --help=encryption for details.
This flag starts encryption options, used to create encrypted
files.
Please see :ref:`encryption-options` for details about creating
encrypted files.
files. Please see :ref:`encryption-options` for details.
.. qpdf:option:: --decrypt
@ -720,19 +723,19 @@ Related Options
preserving the input file's encryption. Use --encryption-file-password
to specify the encryption file's password.
Copy encryption parameters, including the user password, the owner
password, and all security restrictions, from the specified file
instead of preserving encryption details from the input file. This
works even if only one of the user password or owner password is
known. If the encryption file requires a password, use the
:qpdf:ref:`--encryption-file-password` option to set it. Note that
copying the encryption parameters from a file also copies the first
half of ``/ID`` from the file since this is part of the encryption
parameters. This option can be useful if you need to decrypt a file
to make manual changes to it or to change it outside of qpdf, and
then want to restore the original encryption on the file
without having to manual specify all the individual settings. See
also :qpdf:ref:`--decrypt`.
Copy all encryption parameters, including the user password, the
owner password, and all security restrictions, from the specified
file instead of preserving the encryption details from the input
file. This works even if only one of the user password or owner
password is known. If the encryption file requires a password, use
the :qpdf:ref:`--encryption-file-password` option to set it. Note
that copying the encryption parameters from a file also copies the
first half of ``/ID`` from the file since this is part of the
encryption parameters. This option can be useful if you need to
decrypt a file to make manual changes to it or to change it outside
of qpdf, and then want to restore the original encryption on the
file without having to manual specify all the individual settings.
See also :qpdf:ref:`--decrypt`.
.. qpdf:option:: --encryption-file-password=password
@ -752,12 +755,12 @@ Related Options
.. help: enable viewing PDF code in a text editor
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
content streams are normalized, among other changes. The
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
chapter about it in the manual.
files. QDF is a feature specific to the qpdf tool. Please see
the "QDF Mode" chapter in the manual.
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
@ -766,13 +769,13 @@ Related Options
and content streams are normalized, among other changes. The
companion tool :command:`fix-qdf` can be used to repair hand-edited
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.
QDF mode has full support for object streams, but sometimes it's
easier to locate a specific object if object streams are disabled.
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`.
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
will print a warning indicating that content may be damaged. If you
want to create QDF files without content normalization, can you run
with :samp:`--qdf --normalize-content=n`. You can also create a
non-QDF file with uncompressed streams using
:samp:`--stream-data=uncompress`. These will both uncompress all
want to create QDF files without content normalization, specify
:samp:`--qdf --normalize-content=n`. You can also create a non-QDF
file with uncompressed streams using
:samp:`--stream-data=uncompress`. Either option will uncompress all
the streams but will not attempt to normalize content. Please note
that if you are using content normalization or QDF mode for the
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
of qpdf may support additional filters.
Because the default value is ``generalized``, by default, when a stream
is encoded using non-lossy filters that qpdf understands and is not
already compressed using a good compression scheme, qpdf will
uncompress the stream. If ``--compress-streams=y`` is also in
effect, which is the default (see :qpdf:ref:`--compress-streams`),
the overall effect is that qpdf will recompress streams with
generalized filters using flate compression, effectively
eliminating LZW and ASCII-based filters. This is usually desirable
behavior but can be disabled with ``--decode-level=none``.
Because the default value is ``generalized``, qpdf's default
behavior is to uncompress any stream that is encoded using
non-lossy filters that qpdf understands. If
``--compress-streams=y`` is also in effect, which is the default
(see :qpdf:ref:`--compress-streams`), the overall effect is that
qpdf will recompress streams with generalized filters using flate
compression, effectively eliminating LZW and ASCII-based filters.
This is usually desirable behavior but can be disabled with
``--decode-level=none``.
As a special case, streams already compressed with ``/FlateDecode``
are not uncompressed and recompressed. You can change this behavior
@ -956,7 +959,8 @@ Related Options
already compressed streams, you should also specify
:qpdf:ref:`--recompress-flate`. If your goal is to shrink the size
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]
@ -1002,10 +1006,10 @@ Related Options
- 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
objects into object streams allows the PDF objects themselves to be
compressed, which can result in much smaller PDF files. Combining
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.
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
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
the file has no object streams, qpdf will not add any. In
:samp:`disable` mode, all objects are written as regular,
@ -1040,7 +1044,7 @@ Related Options
objects.
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
be the same since qpdf may create stream lengths as direct or
indirect differently from the original file, and the original file
@ -1157,8 +1161,11 @@ Related Options
.. help: set minimum PDF version
Force the PDF version of the output to be at least the
specified version.
Force the PDF version of the output to be at least the specified
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
: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.
The version number may be expressed in the form
:samp:`{major.minor.extension-level}`, in which case the version is
interpreted as :samp:`{major.minor}` at extension level
:samp:`{extension-level}`. For example, version ``1.7.8``
represents version 1.7 at extension level 8. Note that minimal
syntax checking is done on the command line. :command:`qpdf` does
not check whether the specified version is actually required.
:samp:`{major}.{minor}[.{extension-level}]`. If
:samp:`.{extension-level}`, is given, version is interpreted as
:samp:`{major.minor}` at extension level :samp:`{extension-level}`.
For example, version ``1.7.8`` represents version 1.7 at extension
level 8. Note that minimal syntax checking is done on the command
line. :command:`qpdf` does not check whether the specified version
is actually required.
.. 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
disable certain features of the document. Specifically, 256-bit
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 3), AES encryption is disabled if the version is less than
1.6, cleartext metadata and object streams are disabled if less
than 1.5, 128-bit encryption keys are disabled if less than 1.4,
and all encryption is disabled if less than 1.3. Even with these
precautions, qpdf won't be able to do things like eliminate use of
newer image compression schemes, transparency groups, or other
features that may have been added in more recent versions of PDF.
level 8 (except the deprecated, unsupported "R5" format is allowed
with extension levels 3 through 7), AES encryption is disabled if
the version is less than 1.6, cleartext metadata and object streams
are disabled if less than 1.5, 128-bit encryption keys are disabled
if less than 1.4, and all encryption is disabled if less than 1.3.
Even with these precautions, qpdf won't be able to do things like
eliminate use of newer image compression schemes, transparency
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
the use of object streams or AES encryption, PDF viewers are
supposed to ignore features in files that they don't support from
newer versions. This means that forcing the version to a lower
version may make it possible to open your PDF file with an older
version, though bear in mind that some of the original document's
functionality may be lost.
supposed to ignore features they don't support. This means that
forcing the version to a lower version may make it possible to open
your PDF file with an older version, though bear in mind that some
of the original document's functionality may be lost.
.. _page-ranges:
@ -1780,7 +1788,6 @@ encryption from the file entirely.
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

View File

@ -3,6 +3,8 @@
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
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