diff options
author | Jay Berkenbilt <ejb@ql.org> | 2021-12-12 01:11:56 +0100 |
---|---|---|
committer | Jay Berkenbilt <ejb@ql.org> | 2021-12-13 17:20:14 +0100 |
commit | bf4d1078534f14776d777ae37a83736eb969cb7e (patch) | |
tree | b324a474900b524e658a94687d03d5e4a0e34c42 /manual/index.rst | |
parent | b764ba95edb7c2d9be4f8f804db82faacdebdeac (diff) | |
download | qpdf-bf4d1078534f14776d777ae37a83736eb969cb7e.tar.zst |
Convert <option> to :samp: and clean up literal blocks
:option: is stronger and assumes a reference to a list of options.
Since we don't have that yet, just use :samp: for options. Inside
literal code blocks, there is no expansion, so just remove markup.
Diffstat (limited to 'manual/index.rst')
-rw-r--r-- | manual/index.rst | 910 |
1 files changed, 455 insertions, 455 deletions
diff --git a/manual/index.rst b/manual/index.rst index 7000d7e9..28e2e51b 100644 --- a/manual/index.rst +++ b/manual/index.rst @@ -131,7 +131,7 @@ contents of PDF files. If you are making deep changes to the library that cause changes in the contents of the files that qpdf generates, then you should enable the image comparison tests. Enable them by running :command:`configure` with the -@1@option@1@--enable-test-compare-images@2@option@2@ flag. If you enable +:samp:`--enable-test-compare-images` flag. If you enable this, the following additional requirements are required by the test suite. Note that in no case are these items required to use qpdf. @@ -226,22 +226,22 @@ available crypto providers, and to use an external provider as the default over the native one. This behavior can be changed with the following flags to :command:`./configure`: -- @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@ +- :samp:`--enable-crypto-@1@replaceable@1@x@2@replaceable@2@` (where @1@replaceable@1@x@2@replaceable@2@ is a supported crypto provider): enable the @1@replaceable@1@x@2@replaceable@2@ crypto provider, requiring any external dependencies it needs -- @1@option@1@--disable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@: +- :samp:`--disable-crypto-@1@replaceable@1@x@2@replaceable@2@`: disable the @1@replaceable@1@x@2@replaceable@2@ provider, and do not link against its dependencies even if they are available -- @1@option@1@--with-default-crypto=@1@replaceable@1@x@2@replaceable@2@@2@option@2@: +- :samp:`--with-default-crypto=@1@replaceable@1@x@2@replaceable@2@`: make @1@replaceable@1@x@2@replaceable@2@ the default provider even if a higher priority one is available -- @1@option@1@--disable-implicit-crypto@2@option@2@: only build crypto +- :samp:`--disable-implicit-crypto`: only build crypto providers that are explicitly requested with an - @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@ + :samp:`--enable-crypto-@1@replaceable@1@x@2@replaceable@2@` option For example, if you want to guarantee that the gnutls crypto provider is @@ -278,7 +278,7 @@ files you need to build. Runtime Crypto Provider Selection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use the @1@option@1@--show-crypto@2@option@2@ option to +You can use the :samp:`--show-crypto` option to :command:`qpdf` to get a list of available crypto providers. The default provider is always listed first, and the rest are listed in lexical order. Each crypto provider is listed on a line by @@ -395,7 +395,7 @@ some things you may want to keep in mind: providers. Read `Build Support For Crypto Providers <#ref.crypto.build>`__ for details. -- Passing @1@option@1@--enable-show-failed-test-output@2@option@2@ to +- Passing :samp:`--enable-show-failed-test-output` to :command:`./configure` will cause any failed test output to be written to the console. This can be very useful for seeing test failures generated by autobuilders where you can't access @@ -408,7 +408,7 @@ some things you may want to keep in mind: accidentally forgetting to regenerate automatic files after modifying their sources. If your packaging environment automatically refreshes automatic files, it can cause this check to fail. Suppress qpdf's - checks by passing @1@option@1@--disable-check-autofiles@2@option@2@ + checks by passing :samp:`--disable-check-autofiles` to :command:`/.configure`. This is safe since qpdf's :command:`autogen.sh` just runs autotools in the normal way. @@ -440,41 +440,41 @@ When running qpdf, the basic invocation is as follows: :: - :command:`qpdf`@1@option@1@ [ @1@replaceable@1@options@2@replaceable@2@ ] { @1@replaceable@1@infilename@2@replaceable@2@ | @1@option@1@--empty@2@option@2@ } [ @1@replaceable@1@page_selection_options@2@replaceable@2@ ] @1@replaceable@1@outfilename@2@replaceable@2@@2@option@2@ + qpdf [ options ] { infilename | --empty } outfilename -This converts PDF file @1@option@1@infilename@2@option@2@ to PDF file -@1@option@1@outfilename@2@option@2@. The output file is functionally +This converts PDF file :samp:`infilename` to PDF file +:samp:`outfilename`. The output file is functionally identical to the input file but may have been structurally reorganized. Also, orphaned objects will be removed from the file. Many transformations are available as controlled by the options below. In -place of @1@option@1@infilename@2@option@2@, the parameter -@1@option@1@--empty@2@option@2@ may be specified. This causes qpdf to +place of :samp:`infilename`, the parameter +:samp:`--empty` may be specified. This causes qpdf to use a dummy input file that contains zero pages. The only normal use -case for using @1@option@1@--empty@2@option@2@ would be if you were +case for using :samp:`--empty` would be if you were going to add pages from another source, as discussed in `Page Selection Options <#ref.page-selection>`__. -If @1@option@1@@filename@2@option@2@ appears as a word anywhere in the +If :samp:`@filename` appears as a word anywhere in the command-line, it will be read line by line, and each line will be treated as a command-line argument. Leading and trailing whitespace is intentionally not removed from lines, which makes it possible to handle -arguments that start or end with spaces. The @1@option@1@@-@2@option@2@ +arguments that start or end with spaces. The :samp:`@-` option allows arguments to be read from standard input. This allows qpdf to be invoked with an arbitrary number of arbitrarily long arguments. It is also very useful for avoiding having to pass passwords on the command -line. Note that the @1@option@1@@filename@2@option@2@ can't appear in +line. Note that the :samp:`@filename` can't appear in the middle of an argument, so constructs such as -@1@option@1@--arg=@option@2@option@2@ will not work. You would have to +:samp:`--arg=@option` will not work. You would have to include the argument and its options together in the arguments file. -@1@option@1@outfilename@2@option@2@ does not have to be seekable, even -when generating linearized files. Specifying "@1@option@1@-@2@option@2@" -as @1@option@1@outfilename@2@option@2@ means to write to standard +:samp:`outfilename` does not have to be seekable, even +when generating linearized files. Specifying ":samp:`-`" +as :samp:`outfilename` means to write to standard output. If you want to overwrite the input file with the output, use the -option @1@option@1@--replace-input@2@option@2@ and omit the output file +option :samp:`--replace-input` and omit the output file name. You can't specify the same file as both the input and the output. If you do this, qpdf will tell you about the -@1@option@1@--replace-input@2@option@2@ option. +:samp:`--replace-input` option. Most options require an output file, but some testing or inspection commands do not. These are specifically noted. @@ -489,7 +489,7 @@ follows: - ``0``: no errors or warnings were found. The file may still have problems qpdf can't detect. If - @1@option@1@--warning-exit-0@2@option@2@ was specified, exit status 0 + :samp:`--warning-exit-0` was specified, exit status 0 is used even if there are warnings. - ``2``: errors were found. qpdf was not able to fully process the @@ -498,8 +498,8 @@ follows: - ``3``: qpdf encountered problems that it was able to recover from. In some cases, the resulting file may still be damaged. Note that qpdf still exits with status ``3`` if it finds warnings even when - @1@option@1@--no-warn@2@option@2@ is specified. With - @1@option@1@--warning-exit-0@2@option@2@, warnings without errors + :samp:`--no-warn` is specified. With + :samp:`--warning-exit-0`, warnings without errors exit with status 0 instead of 3. Note that :command:`qpdf` never exists with status ``1``. @@ -534,94 +534,94 @@ Basic Options The following options are the most common ones and perform commonly needed transformations. -@1@option@1@--help@2@option@2@ +:samp:`--help` Display command-line invocation help. -@1@option@1@--version@2@option@2@ +:samp:`--version` Display the current version of qpdf. -@1@option@1@--copyright@2@option@2@ +:samp:`--copyright` Show detailed copyright information. -@1@option@1@--show-crypto@2@option@2@ +:samp:`--show-crypto` Show a list of available crypto providers, each on a line by itself. The default provider is always listed first. See `Crypto Providers <#ref.crypto>`__ for more information about crypto providers. -@1@option@1@--completion-bash@2@option@2@ +:samp:`--completion-bash` Output a completion command you can eval to enable shell completion from bash. -@1@option@1@--completion-zsh@2@option@2@ +:samp:`--completion-zsh` Output a completion command you can eval to enable shell completion from zsh. -@1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@ +:samp:`--password=@1@replaceable@1@password@2@replaceable@2@` Specifies a password for accessing encrypted files. To read the password from a file or standard input, you can use - @1@option@1@--password-file@2@option@2@, added in qpdf 10.2. Note - that you can also use @1@option@1@@filename@2@option@2@ or - @1@option@1@@-@2@option@2@ as described above to put the password in + :samp:`--password-file`, added in qpdf 10.2. Note + that you can also use :samp:`@filename` or + :samp:`@-` as described above to put the password in a file or pass it via standard input, but you would do so by specifying the entire - @1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@ + :samp:`--password=@1@replaceable@1@password@2@replaceable@2@` option in the file. Syntax such as - @1@option@1@--password=@filename@2@option@2@ won't work since - @1@option@1@@filename@2@option@2@ is not recognized in the middle of + :samp:`--password=@filename` won't work since + :samp:`@filename` is not recognized in the middle of an argument. -@1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@ +:samp:`--password-file=@1@replaceable@1@filename@2@replaceable@2@` Reads the first line from the specified file and uses it as the password for accessing encrypted files. - @1@option@1@@1@replaceable@1@filename@2@replaceable@2@@2@option@2@ + :samp:`@1@replaceable@1@filename@2@replaceable@2@` may be ``-`` to read the password from standard input. Note that, in this case, the password is echoed and there is no prompt, so use with caution. -@1@option@1@--is-encrypted@2@option@2@ +:samp:`--is-encrypted` Silently exit with status 0 if the file is encrypted or status 2 if the file is not encrypted. This is useful for shell scripts. Other options are ignored if this is given. This option is mutually - exclusive with @1@option@1@--requires-password@2@option@2@. Both this - option and @1@option@1@--requires-password@2@option@2@ exit with + exclusive with :samp:`--requires-password`. Both this + option and :samp:`--requires-password` exit with status 2 for non-encrypted files. -@1@option@1@--requires-password@2@option@2@ +:samp:`--requires-password` Silently exit with status 0 if a password (other than as supplied) is required. Exit with status 2 if the file is not encrypted. Exit with status 3 if the file is encrypted but requires no password or the correct password has been supplied. This is useful for shell scripts. Note that any supplied password is used when opening the file. When - used with a @1@option@1@--password@2@option@2@ option, this option + used with a :samp:`--password` option, this option can be used to check the correctness of the password. In that case, an exit status of 3 means the file works with the supplied password. This option is mutually exclusive with - @1@option@1@--is-encrypted@2@option@2@. Both this option and - @1@option@1@--is-encrypted@2@option@2@ exit with status 2 for + :samp:`--is-encrypted`. Both this option and + :samp:`--is-encrypted` exit with status 2 for non-encrypted files. -@1@option@1@--verbose@2@option@2@ +:samp:`--verbose` Increase verbosity of output. For now, this just prints some indication of any file that it creates. -@1@option@1@--progress@2@option@2@ +:samp:`--progress` Indicate progress while writing files. -@1@option@1@--no-warn@2@option@2@ +:samp:`--no-warn` Suppress writing of warnings to stderr. If warnings were detected and suppressed, :command:`qpdf` will still exit with exit - code 3. See also @1@option@1@--warning-exit-0@2@option@2@. + code 3. See also :samp:`--warning-exit-0`. -@1@option@1@--warning-exit-0@2@option@2@ +:samp:`--warning-exit-0` If warnings are found but no errors, exit with exit code 0 instead 3. - When combined with @1@option@1@--no-warn@2@option@2@, the effect is + When combined with :samp:`--no-warn`, the effect is for :command:`qpdf` to completely ignore warnings. -@1@option@1@--linearize@2@option@2@ +:samp:`--linearize` Causes generation of a linearized (web-optimized) output file. -@1@option@1@--replace-input@2@option@2@ +:samp:`--replace-input` If specified, the output file name should be omitted. This option tells qpdf to replace the input file with the output. It does this by writing to @@ -630,17 +630,17 @@ needed transformations. If there were any warnings, the original input is saved as :file:`@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-orig`. -@1@option@1@--copy-encryption=file@2@option@2@ +:samp:`--copy-encryption=file` Encrypt the file using the same encryption parameters, including user and owner password, as the specified file. Use - @1@option@1@--encryption-file-password@2@option@2@ to specify a + :samp:`--encryption-file-password` to specify a password if one is needed to open this file. 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. -@1@option@1@--encryption-file-password=password@2@option@2@ - If the file specified with @1@option@1@--copy-encryption@2@option@2@ +:samp:`--encryption-file-password=password` + If the file specified with :samp:`--copy-encryption` requires a password, specify the password using this option. Note that only one of the user or owner password is required. Both passwords will be preserved since QPDF does not distinguish between @@ -648,30 +648,30 @@ needed transformations. including the owner password, from a file even if you don't know the file's owner password. -@1@option@1@--allow-weak-crypto@2@option@2@ +:samp:`--allow-weak-crypto` Starting with version 10.4, qpdf issues warnings when requested to create files using RC4 encryption. This option suppresses those warnings. In future versions of qpdf, qpdf will refuse to create files with weak cryptography when this flag is not given. See `Weak Cryptography <#ref.weak-crypto>`__ for additional details. -@1@option@1@--encrypt options --@2@option@2@ +:samp:`--encrypt options --` Causes generation an encrypted output file. Please see `Encryption Options <#ref.encryption-options>`__ for details on how to specify encryption parameters. -@1@option@1@--decrypt@2@option@2@ +:samp:`--decrypt` Removes any encryption on the file. A password must be supplied if the file is password protected. -@1@option@1@--password-is-hex-key@2@option@2@ +:samp:`--password-is-hex-key` 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 @1@option@1@--password@2@option@2@ option is + the argument to the :samp:`--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 @1@option@1@--pages@2@option@2@ or other + other files opened by :samp:`--pages` or other options or to files being written. Most users will never have a need for this option, and no standard @@ -682,28 +682,28 @@ needed transformations. Also, if a file is heavily damaged, it may be possible to derive the encryption key and recover parts of the file using it directly. To expose the encryption key used by an encrypted file that you can open - normally, use the @1@option@1@--show-encryption-key@2@option@2@ + normally, use the :samp:`--show-encryption-key` option. -@1@option@1@--suppress-password-recovery@2@option@2@ +:samp:`--suppress-password-recovery` Ordinarily, qpdf attempts to automatically compensate for passwords specified in the wrong character encoding. This option suppresses that behavior. Under normal conditions, there are no reasons to use this option. See `Unicode Passwords <#ref.unicode-passwords>`__ for a discussion -@1@option@1@--password-mode=@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ +:samp:`--password-mode=@1@replaceable@1@mode@2@replaceable@2@` This option can be used to fine-tune how qpdf interprets Unicode (non-ASCII) password strings passed on the command line. With the - exception of the @1@option@1@hex-bytes@2@option@2@ mode, these only + exception of the :samp:`hex-bytes` mode, these only apply to passwords provided when encrypting files. The - @1@option@1@hex-bytes@2@option@2@ mode also applies to passwords + :samp:`hex-bytes` mode also applies to passwords specified for reading files. For additional discussion of the supported password modes and when you might want to use them, see `Unicode Passwords <#ref.unicode-passwords>`__. The following modes are supported: - - @1@option@1@auto@2@option@2@: Automatically determine whether the + - :samp:`auto`: Automatically determine whether the specified password is a properly encoded Unicode (UTF-8) string, and transcode it as required by the PDF spec based on the type encryption being applied. On Windows starting with version 8.4.0, @@ -711,40 +711,40 @@ needed transformations. be properly encoded in UTF-8, so this is almost always what you want. - - @1@option@1@unicode@2@option@2@: Tells qpdf that the incoming + - :samp:`unicode`: Tells qpdf that the incoming password is UTF-8, overriding whatever its automatic detection determines. The only difference between this mode and - @1@option@1@auto@2@option@2@ is that qpdf will fail with an error + :samp:`auto` is that qpdf will fail with an error message if the password is not valid UTF-8 instead of falling back - to @1@option@1@bytes@2@option@2@ mode with a warning. + to :samp:`bytes` mode with a warning. - - @1@option@1@bytes@2@option@2@: Interpret the password as a literal + - :samp:`bytes`: Interpret the password as a literal byte string. For non-Windows platforms, this is what versions of qpdf prior to 8.4.0 did. For Windows platforms, there is no way to specify strings of binary data on the command line directly, but - you can use the @1@option@1@@filename@2@option@2@ option to do it, + you can use the :samp:`@filename` option to do it, in which case this option forces qpdf to respect the string of bytes as provided. This option will allow you to encrypt PDF files with passwords that will not be usable by other readers. - - @1@option@1@hex-bytes@2@option@2@: Interpret the password as a + - :samp:`hex-bytes`: Interpret the password as a hex-encoded string. This provides a way to pass binary data as a password on all platforms including Windows. As with - @1@option@1@bytes@2@option@2@, this option may allow creation of + :samp:`bytes`, this option may allow creation of files that can't be opened by other readers. This mode affects qpdf's interpretation of passwords specified for decrypting files as well as for encrypting them. It makes it possible to specify strings that are encoded in some manner other than the system's default encoding. -@1@option@1@--rotate=[+|-]angle[:page-range]@2@option@2@ +:samp:`--rotate=[+|-]angle[:page-range]` Apply rotation to specified pages. The - @1@option@1@page-range@2@option@2@ portion of the option value has + :samp:`page-range` portion of the option value has the same format as page ranges in `Page Selection Options <#ref.page-selection>`__. If the page range is omitted, the - rotation is applied to all pages. The @1@option@1@angle@2@option@2@ + rotation is applied to all pages. The :samp:`angle` portion of the parameter may be either 0, 90, 180, or 270. If - preceded by @1@option@1@+@2@option@2@ or @1@option@1@-@2@option@2@, + preceded by :samp:`+` or :samp:`-`, the angle is added to or subtracted from the specified pages' original rotations. This is almost always what you want. Otherwise the pages' rotations are set to the exact value, which may cause the @@ -757,7 +757,7 @@ needed transformations. out.pdf --rotate=+180` would rotate all pages by 180 degrees. -@1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@ +:samp:`--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@` This option controls whether qpdf keeps individual files open while merging. Prior to version 8.1.0, qpdf always kept all files open, but this meant that the number of files that could be merged was limited @@ -770,45 +770,45 @@ needed transformations. version 8.2.1, the default behavior is that files are kept open if no more than 200 files are specified, but that the behavior can be explicitly overridden with the - @1@option@1@--keep-files-open@2@option@2@ flag. If you are merging + :samp:`--keep-files-open` flag. If you are merging more than 200 files but less than the operating system's max open files limit, you may want to use - @1@option@1@--keep-files-open=y@2@option@2@, especially if working + :samp:`--keep-files-open=y`, especially if working over a networked file system. If you are using a local file system where the overhead is low and you might sometimes merge more than the OS limit's number of files from a script and are not worried about a few seconds additional processing time, you may want to specify - @1@option@1@--keep-files-open=n@2@option@2@. The threshold for + :samp:`--keep-files-open=n`. The threshold for switching may be changed from the default 200 with the - @1@option@1@--keep-files-open-threshold@2@option@2@ option. + :samp:`--keep-files-open-threshold` option. -@1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@ +:samp:`--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@` If specified, overrides the default value of 200 used as the threshold for qpdf deciding whether or not to keep files open. See - @1@option@1@--keep-files-open@2@option@2@ for details. + :samp:`--keep-files-open` for details. -@1@option@1@--pages options --@2@option@2@ +:samp:`--pages options --` Select specific pages from one or more input files. See `Page Selection Options <#ref.page-selection>`__ for details on how to do page selection (splitting and merging). -@1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@ +:samp:`--collate=@1@replaceable@1@n@2@replaceable@2@` When specified, collate rather than concatenate pages from files - specified with @1@option@1@--pages@2@option@2@. With a numeric + specified with :samp:`--pages`. With a numeric argument, collate in groups of @1@replaceable@1@n@2@replaceable@2@. The default is 1. See `Page Selection Options <#ref.page-selection>`__ for additional details. -@1@option@1@--flatten-rotation@2@option@2@ +:samp:`--flatten-rotation` For each page that is rotated using the ``/Rotate`` key in the page's dictionary, remove the ``/Rotate`` key and implement the identical rotation semantics by modifying the page's contents. This option can be useful to prepare files for buggy PDF applications that don't properly handle rotated pages. -@1@option@1@--split-pages=[n]@2@option@2@ - Write each group of @1@option@1@n@2@option@2@ pages to a separate - output file. If @1@option@1@n@2@option@2@ is not specified, create +:samp:`--split-pages=[n]` + Write each group of :samp:`n` pages to a separate + output file. If :samp:`n` is not specified, create single pages. Output file names are generated as follows: - If the string ``%d`` appears in the output file name, it is @@ -845,24 +845,24 @@ needed transformations. option creates an empty PDF and copies a single page from the output into it. If you require the global data, you will have to run :command:`qpdf` with the - @1@option@1@--pages@2@option@2@ option once for each file. Using - @1@option@1@--split-pages@2@option@2@ is much faster if you don't + :samp:`--pages` option once for each file. Using + :samp:`--split-pages` is much faster if you don't require the global data. -@1@option@1@--overlay options --@2@option@2@ +:samp:`--overlay options --` Overlay pages from another file onto the output pages. See `Overlay and Underlay Options <#ref.overlay-underlay>`__ for details on overlay/underlay. -@1@option@1@--underlay options --@2@option@2@ +:samp:`--underlay options --` Overlay pages from another file onto the output pages. See `Overlay and Underlay Options <#ref.overlay-underlay>`__ for details on overlay/underlay. Password-protected files may be opened by specifying a password. By default, qpdf will preserve any encryption data associated with a file. -If @1@option@1@--decrypt@2@option@2@ is specified, qpdf will attempt to -remove any encryption information. If @1@option@1@--encrypt@2@option@2@ +If :samp:`--decrypt` is specified, qpdf will attempt to +remove any encryption information. If :samp:`--encrypt` is specified, qpdf will replace the document's encryption parameters with whatever is specified. @@ -893,9 +893,9 @@ The syntax is :: - @1@option@1@--encrypt @1@replaceable@1@user-password@2@replaceable@2@ @1@replaceable@1@owner-password@2@replaceable@2@ @1@replaceable@1@key-length@2@replaceable@2@ [ @1@replaceable@1@restrictions@2@replaceable@2@ ] --@2@option@2@ + --encrypt user-password owner-password key-length [ restrictions ] -- -Note that "@1@option@1@--@2@option@2@" terminates parsing of encryption +Note that ":samp:`--`" terminates parsing of encryption flags and must be present even if no restrictions are present. Either or both of the user password and the owner password may be empty @@ -903,34 +903,34 @@ strings. Starting in qpdf 10.2, qpdf defaults to not allowing creation of PDF files with a non-empty user password, an empty owner password, and a 256-bit key since such files can be opened with no password. If you want to create such files, specify the encryption option -@1@option@1@--allow-insecure@2@option@2@, as described below. +:samp:`--allow-insecure`, as described below. The value for -@1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ may +:samp:`@1@replaceable@1@key-length@2@replaceable@2@` may be 40, 128, or 256. The restriction flags are dependent upon key length. When no additional restrictions are given, the default is to be fully permissive. -If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ +If :samp:`@1@replaceable@1@key-length@2@replaceable@2@` is 40, the following restriction options are available: -@1@option@1@--print=[yn]@2@option@2@ +:samp:`--print=[yn]` Determines whether or not to allow printing. -@1@option@1@--modify=[yn]@2@option@2@ +:samp:`--modify=[yn]` Determines whether or not to allow document modification. -@1@option@1@--extract=[yn]@2@option@2@ +:samp:`--extract=[yn]` Determines whether or not to allow text/image extraction. -@1@option@1@--annotate=[yn]@2@option@2@ +:samp:`--annotate=[yn]` Determines whether or not to allow comments and form fill-in and signing. -If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ +If :samp:`@1@replaceable@1@key-length@2@replaceable@2@` is 128, the following restriction options are available: -@1@option@1@--accessibility=[yn]@2@option@2@ +:samp:`--accessibility=[yn]` Determines whether or not to allow accessibility to visually impaired. The qpdf library disregards this field when AES is used or when 256-bit encryption is used. You should really never disable @@ -939,74 +939,74 @@ is 128, the following restriction options are available: conforming readers should disregard this permission and always allow accessibility. -@1@option@1@--extract=[yn]@2@option@2@ +:samp:`--extract=[yn]` Determines whether or not to allow text/graphic extraction. -@1@option@1@--assemble=[yn]@2@option@2@ +:samp:`--assemble=[yn]` Determines whether document assembly (rotation and reordering of pages) is allowed. -@1@option@1@--annotate=[yn]@2@option@2@ +:samp:`--annotate=[yn]` Determines whether modifying annotations is allowed. This includes adding comments and filling in form fields. Also allows editing of - form fields if @1@option@1@--modify-other=y@2@option@2@ is given. + form fields if :samp:`--modify-other=y` is given. -@1@option@1@--form=[yn]@2@option@2@ +:samp:`--form=[yn]` Determines whether filling form fields is allowed. -@1@option@1@--modify-other=[yn]@2@option@2@ +:samp:`--modify-other=[yn]` Allow all document editing except those controlled separately by the - @1@option@1@--assemble@2@option@2@, - @1@option@1@--annotate@2@option@2@, and - @1@option@1@--form@2@option@2@ options. + :samp:`--assemble`, + :samp:`--annotate`, and + :samp:`--form` options. -@1@option@1@--print=@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@ +:samp:`--print=@1@replaceable@1@print-opt@2@replaceable@2@` Controls printing access. - @1@option@1@@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@ + :samp:`@1@replaceable@1@print-opt@2@replaceable@2@` may be one of the following: - - @1@option@1@full@2@option@2@: allow full printing + - :samp:`full`: allow full printing - - @1@option@1@low@2@option@2@: allow low-resolution printing only + - :samp:`low`: allow low-resolution printing only - - @1@option@1@none@2@option@2@: disallow printing + - :samp:`none`: disallow printing -@1@option@1@--modify=@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@ +:samp:`--modify=@1@replaceable@1@modify-opt@2@replaceable@2@` Controls modify access. This way of controlling modify access has less granularity than new options added in qpdf 8.4. - @1@option@1@@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@ + :samp:`@1@replaceable@1@modify-opt@2@replaceable@2@` may be one of the following: - - @1@option@1@all@2@option@2@: allow full document modification + - :samp:`all`: allow full document modification - - @1@option@1@annotate@2@option@2@: allow comment authoring, form + - :samp:`annotate`: allow comment authoring, form operations, and document assembly - - @1@option@1@form@2@option@2@: allow form field fill-in and signing + - :samp:`form`: allow form field fill-in and signing and document assembly - - @1@option@1@assembly@2@option@2@: allow document assembly only + - :samp:`assembly`: allow document assembly only - - @1@option@1@none@2@option@2@: allow no modifications + - :samp:`none`: allow no modifications - Using the @1@option@1@--modify@2@option@2@ option does not allow you + Using the :samp:`--modify` option does not allow you to create certain combinations of permissions such as allowing form filling but not allowing document assembly. Starting with qpdf 8.4, you can either just use the other options to control fields - individually, or you can use something like @1@option@1@--modify=form - --assembly=n@2@option@2@ to fine tune. + individually, or you can use something like :samp:`--modify=form + --assembly=n` to fine tune. -@1@option@1@--cleartext-metadata@2@option@2@ +:samp:`--cleartext-metadata` If specified, any metadata stream in the document will be left unencrypted even if the rest of the document is encrypted. This also forces the PDF version to be at least 1.5. -@1@option@1@--use-aes=[yn]@2@option@2@ - If @1@option@1@--use-aes=y@2@option@2@ is specified, AES encryption +:samp:`--use-aes=[yn]` + If :samp:`--use-aes=y` is specified, AES encryption will be used instead of RC4 encryption. This forces the PDF version to be at least 1.6. -@1@option@1@--allow-insecure@2@option@2@ +:samp:`--allow-insecure` From qpdf 10.2, qpdf defaults to not allowing creation of PDF files where the user password is non-empty, the owner password is empty, and a 256-bit key is in use. Files created in this way are insecure @@ -1015,27 +1015,27 @@ is 128, the following restriction options are available: intentionally created strange files for testing (a definite valid use of qpdf!), this option allows you to create such insecure files. -@1@option@1@--force-V4@2@option@2@ +:samp:`--force-V4` Use of this option forces the ``/V`` and ``/R`` parameters in the document's encryption dictionary to be set to the value ``4``. As qpdf will automatically do this when required, there is no reason to ever use this option. It exists primarily for use in testing qpdf itself. This option also forces the PDF version to be at least 1.5. -If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ +If :samp:`@1@replaceable@1@key-length@2@replaceable@2@` is 256, the minimum PDF version is 1.7 with extension level 8, and the AES-based encryption format used is the PDF 2.0 encryption method supported by Acrobat X. the same options are available as with 128 bits with the following exceptions: -@1@option@1@--use-aes@2@option@2@ +:samp:`--use-aes` This option is not available with 256-bit keys. AES is always used with 256-bit encryption keys. -@1@option@1@--force-V4@2@option@2@ +:samp:`--force-V4` This option is not available with 256 keys. -@1@option@1@--force-R5@2@option@2@ +:samp:`--force-R5` If specified, qpdf sets the minimum version to 1.7 at extension level 3 and writes the deprecated encryption format used by Acrobat version IX. This option should not be used in practice to generate PDF files @@ -1057,11 +1057,11 @@ replaced with pages as specified. :: - @1@option@1@--pages @1@replaceable@1@input-file@2@replaceable@2@ [ @1@replaceable@1@--password=password@2@replaceable@2@ ] [ @1@replaceable@1@page-range@2@replaceable@2@ ] [ ... ] --@2@option@2@ + --pages input-file [ --password=password ] [ page-range ] [ ... ] -- Multiple input files may be specified. Each one is given as the name of the input file, an optional password (if required to open the file), and -the range of pages. Note that "@1@option@1@--@2@option@2@" terminates +the range of pages. Note that ":samp:`--`" terminates parsing of page selection flags. Starting with qpf 8.4, the special input file name @@ -1077,7 +1077,7 @@ password here. The same file can be repeated multiple times. If a file that is repeated has a password, the password only has to be given the first time. All non-page data (info, outlines, page numbers, etc.) are taken from the primary input file. To discard these, use -@1@option@1@--empty@2@option@2@ as the primary input. +:samp:`--empty` as the primary input. Starting with qpdf 5.0.0, it is possible to omit the page range. If qpdf sees a value in the place where it expects a page range and that value @@ -1117,10 +1117,10 @@ Example page ranges: 8, 9, and 12. Starting in qpdf version 8.3, you can specify the -@1@option@1@--collate@2@option@2@ option. Note that this option is -specified outside of @1@option@1@--pages ... --@2@option@2@. When -@1@option@1@--collate@2@option@2@ is specified, it changes the meaning -of @1@option@1@--pages@2@option@2@ so that the specified files, as +:samp:`--collate` option. Note that this option is +specified outside of :samp:`--pages ... --`. When +:samp:`--collate` is specified, it changes the meaning +of :samp:`--pages` so that the specified files, as modified by page ranges, are collated rather than concatenated. For example, if you add the files :file:`odd.pdf` and :file:`even.pdf` containing odd and even pages of a @@ -1153,8 +1153,8 @@ following pages in this order: - a.pdf page 5 Starting in qpdf version 10.2, you may specify a numeric argument to -@1@option@1@--collate@2@option@2@. With -@1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@, +:samp:`--collate`. With +:samp:`--collate=@1@replaceable@1@n@2@replaceable@2@`, pull groups of @1@replaceable@1@n@2@replaceable@2@ pages from each file, again, stopping when there are no more pages. For example, if you ran :command:`qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf @@ -1191,14 +1191,14 @@ remaining bookmarks will not work. A future version of issues. (Note that the qpdf library already contains all of the APIs required in order to implement this in your own application if you need it.) In the mean time, you can always use -@1@option@1@--empty@2@option@2@ as the primary input file to avoid +:samp:`--empty` as the primary input file to avoid copying all of that from the first file. For example, to take pages 1 through 5 from a :file:`infile.pdf` while preserving all metadata associated with that file, you could use :: - :command:`qpdf` @1@option@1@infile.pdf --pages . 1-5 -- outfile.pdf@2@option@2@ + qpdf infile.pdf --pages . 1-5 -- outfile.pdf If you wanted pages 1 through 5 from :file:`infile.pdf` but you wanted the rest of the @@ -1206,7 +1206,7 @@ metadata to be dropped, you could instead run :: - :command:`qpdf` @1@option@1@--empty --pages infile.pdf 1-5 -- outfile.pdf@2@option@2@ + qpdf --empty --pages infile.pdf 1-5 -- outfile.pdf If you wanted to take pages 1 through 5 from :file:`file1.pdf` and pages 11 through 15 from @@ -1215,7 +1215,7 @@ metadata from :file:`file2.pdf`, you would run :: - :command:`qpdf` @1@option@1@file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf@2@option@2@ + qpdf file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf If, for some reason, you wanted to take the first page of an encrypted file called :file:`encrypted.pdf` with password @@ -1224,12 +1224,12 @@ drop document-level metadata but preserve encryption, you would use :: - :command:`qpdf` @1@option@1@--empty --copy-encryption=encrypted.pdf --encryption-file-password=pass + qpdf --empty --copy-encryption=encrypted.pdf --encryption-file-password=pass --pages encrypted.pdf --password=pass 1 ./encrypted.pdf --password=pass 1 -- - outfile.pdf@2@option@2@ + outfile.pdf Note that we had to specify the password all three times because giving -a password as @1@option@1@--encryption-file-password@2@option@2@ doesn't +a password as :samp:`--encryption-file-password` doesn't count for page selection, and as far as qpdf is concerned, :file:`encrypted.pdf` and :file:`./encrypted.pdf` are separated files. These @@ -1260,11 +1260,11 @@ underlay as follows: :: - { @1@option@1@--overlay@2@option@2@ | @1@option@1@--underlay@2@option@2@ } @1@replaceable@1@file@2@replaceable@2@ [ @1@option@1@options@2@option@2@ ] @1@option@1@--@2@option@2@ + { --overlay | --underlay } file [ options ] -- Overlay and underlay options are processed late, so they can be combined with other like merging and will apply to the final output. The -@1@option@1@--overlay@2@option@2@ and @1@option@1@--underlay@2@option@2@ +:samp:`--overlay` and :samp:`--underlay` options work the same way, except underlay pages are drawn underneath the page to which they are applied, possibly obscured by the original page, and overlay files are drawn on top of the page to which they are @@ -1276,29 +1276,29 @@ from the overlay/underlay file in sequence and applied to corresponding pages in the output until there are no more output pages. If the overlay or underlay file runs out of pages, remaining output pages are left alone. This behavior can be modified by options, which are provided -between the @1@option@1@--overlay@2@option@2@ or -@1@option@1@--underlay@2@option@2@ flag and the -@1@option@1@--@2@option@2@ option. The following options are supported: +between the :samp:`--overlay` or +:samp:`--underlay` flag and the +:samp:`--` option. The following options are supported: -- @1@option@1@--password=password@2@option@2@: supply a password if the +- :samp:`--password=password`: supply a password if the overlay/underlay file is encrypted. -- @1@option@1@--to=page-range@2@option@2@: a range of pages in the same +- :samp:`--to=page-range`: a range of pages in the same form at described in `Page Selection Options <#ref.page-selection>`__ indicates which pages in the output should have the overlay/underlay applied. If not specified, overlay/underlay are applied to all pages. -- @1@option@1@--from=[page-range]@2@option@2@: a range of pages that +- :samp:`--from=[page-range]`: a range of pages that specifies which pages in the overlay/underlay file will be used for overlay or underlay. If not specified, all pages will be used. This can be explicitly specified to be empty if - @1@option@1@--repeat@2@option@2@ is used. + :samp:`--repeat` is used. -- @1@option@1@--repeat=page-range@2@option@2@: an optional range of +- :samp:`--repeat=page-range`: an optional range of pages that specifies which pages in the overlay/underlay file will be repeated after the "from" pages are used up. If you want to repeat a range of pages starting at the beginning, you can explicitly use - @1@option@1@--from=@2@option@2@. + :samp:`--from=`. Here are some examples. @@ -1323,78 +1323,78 @@ Embedded Files/Attachments Options Starting with qpdf 10.2, you can work with file attachments in PDF files from the command line. The following options are available: -@1@option@1@--list-attachments@2@option@2@ +:samp:`--list-attachments` Show the "key" and stream number for embedded files. With - @1@option@1@--verbose@2@option@2@, additional information, including + :samp:`--verbose`, additional information, including preferred file name, description, dates, and more are also displayed. The key is usually but not always equal to the file name, and is needed by some of the other options. -@1@option@1@--show-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@ +:samp:`--show-attachment=@1@replaceable@1@key@2@replaceable@2@` Write the contents of the specified attachment to standard output as binary data. The key should match one of the keys shown by - @1@option@1@--list-attachments@2@option@2@. If specified multiple + :samp:`--list-attachments`. If specified multiple times, only the last attachment will be shown. -@1@option@1@--add-attachment @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --@2@option@2@ +:samp:`--add-attachment @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --` Add or replace an attachment with the contents of @1@replaceable@1@file@2@replaceable@2@. This may be specified more than once. The following additional options may appear before the ``--`` that ends this option: - @1@option@1@--key=@1@replaceable@1@key@2@replaceable@2@@2@option@2@ + :samp:`--key=@1@replaceable@1@key@2@replaceable@2@` The key to use to register the attachment in the embedded files table. Defaults to the last path element of @1@replaceable@1@file@2@replaceable@2@. - @1@option@1@--filename=@1@replaceable@1@name@2@replaceable@2@@2@option@2@ + :samp:`--filename=@1@replaceable@1@name@2@replaceable@2@` The file name to be used for the attachment. This is what is usually displayed to the user and is the name most graphical PDF viewers will use when saving a file. It defaults to the last path element of @1@replaceable@1@file@2@replaceable@2@. - @1@option@1@--creationdate=@1@replaceable@1@date@2@replaceable@2@@2@option@2@ + :samp:`--creationdate=@1@replaceable@1@date@2@replaceable@2@` The attachment's creation date in PDF format; defaults to the current time. The date format is explained below. - @1@option@1@--moddate=@1@replaceable@1@date@2@replaceable@2@@2@option@2@ + :samp:`--moddate=@1@replaceable@1@date@2@replaceable@2@` The attachment's modification date in PDF format; defaults to the current time. The date format is explained below. - @1@option@1@--mimetype=@1@replaceable@1@type/subtype@2@replaceable@2@@2@option@2@ + :samp:`--mimetype=@1@replaceable@1@type/subtype@2@replaceable@2@` The mime type for the attachment, e.g. ``text/plain`` or ``application/pdf``. Note that the mimetype appears in a field called ``/Subtype`` in the PDF but actually includes the full type and subtype of the mime type. - @1@option@1@--description=@1@replaceable@1@"text"@2@replaceable@2@@2@option@2@ + :samp:`--description=@1@replaceable@1@"text"@2@replaceable@2@` Descriptive text for the attachment, displayed by some PDF viewers. - @1@option@1@--replace@2@option@2@ + :samp:`--replace` Indicates that any existing attachment with the same key should be replaced by the new attachment. Otherwise, :command:`qpdf` gives an error if an attachment with that key is already present. -@1@option@1@--remove-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@ +:samp:`--remove-attachment=@1@replaceable@1@key@2@replaceable@2@` Remove the specified attachment. This doesn't only remove the attachment from the embedded files table but also clears out the file specification. That means that any potential internal links to the attachment will be broken. This option may be specified multiple - times. Run with @1@option@1@--verbose@2@option@2@ to see status of + times. Run with :samp:`--verbose` to see status of the removal. -@1@option@1@--copy-attachments-from @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --@2@option@2@ +:samp:`--copy-attachments-from @1@replaceable@1@file@2@replaceable@2@ @1@replaceable@1@options@2@replaceable@2@ --` Copy attachments from another file. This may be specified more than once. The following additional options may appear before the ``--`` that ends this option: - @1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@ + :samp:`--password=@1@replaceable@1@password@2@replaceable@2@` If required, the password needed to open @1@replaceable@1@file@2@replaceable@2@ - @1@option@1@--prefix=@1@replaceable@1@prefix@2@replaceable@2@@2@option@2@ + :samp:`--prefix=@1@replaceable@1@prefix@2@replaceable@2@` Only required if the file from which attachments are being copied has attachments with keys that conflict with attachments already in the file. In this case, the specified prefix will be prepended @@ -1420,10 +1420,10 @@ are of use to people who are working with damaged files. There is little reason to use these options unless you are trying to solve specific problems. The following options are available: -@1@option@1@--suppress-recovery@2@option@2@ +:samp:`--suppress-recovery` Prevents qpdf from attempting to recover damaged files. -@1@option@1@--ignore-xref-streams@2@option@2@ +:samp:`--ignore-xref-streams` Tells qpdf to ignore any cross-reference streams. Ordinarily, qpdf will attempt to recover from certain types of errors in @@ -1432,12 +1432,12 @@ types of object numbering errors, and certain types of stream length errors. Sometimes, qpdf may think it has recovered but may not have actually recovered, so care should be taken when using this option as some data loss is possible. The -@1@option@1@--suppress-recovery@2@option@2@ option will prevent qpdf +:samp:`--suppress-recovery` option will prevent qpdf from attempting recovery. In this case, it will fail on the first error that it encounters. Ordinarily, qpdf reads cross-reference streams when they are present in -a PDF file. If @1@option@1@--ignore-xref-streams@2@option@2@ is +a PDF file. If :samp:`--ignore-xref-streams` is specified, qpdf will ignore any cross-reference streams for hybrid PDF files. The purpose of hybrid files is to make some content available to viewers that are not aware of cross-reference streams. It is almost @@ -1456,99 +1456,99 @@ output file. Mostly these are of use only to people who are very familiar with the PDF file format or who are PDF developers. The following options are available: -@1@option@1@--compress-streams=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@ - By default, or with @1@option@1@--compress-streams=y@2@option@2@, +:samp:`--compress-streams=@1@replaceable@1@[yn]@2@replaceable@2@` + By default, or with :samp:`--compress-streams=y`, qpdf will compress any stream with no other filters applied to it with the ``/FlateDecode`` filter when it writes it. To suppress this behavior and preserve uncompressed streams as uncompressed, use - @1@option@1@--compress-streams=n@2@option@2@. + :samp:`--compress-streams=n`. -@1@option@1@--decode-level=@1@replaceable@1@option@2@replaceable@2@@2@option@2@ +:samp:`--decode-level=@1@replaceable@1@option@2@replaceable@2@` Controls which streams qpdf tries to decode. The default is - @1@option@1@generalized@2@option@2@. The following options are + :samp:`generalized`. The following options are available: - - @1@option@1@none@2@option@2@: do not attempt to decode any streams + - :samp:`none`: do not attempt to decode any streams - - @1@option@1@generalized@2@option@2@: decode streams filtered with + - :samp:`generalized`: decode streams filtered with supported generalized filters: ``/LZWDecode``, ``/FlateDecode``, ``/ASCII85Decode``, and ``/ASCIIHexDecode``. We define generalized filters as those to be used for general-purpose compression or encoding, as opposed to filters specifically designed for image data. Note that, by default, streams already compressed with ``/FlateDecode`` are not uncompressed and recompressed unless you - also specify @1@option@1@--recompress-flate@2@option@2@. + also specify :samp:`--recompress-flate`. - - @1@option@1@specialized@2@option@2@: in addition to generalized, + - :samp:`specialized`: in addition to generalized, decode streams with supported non-lossy specialized filters; currently this is just ``/RunLengthDecode`` - - @1@option@1@all@2@option@2@: in addition to generalized and + - :samp:`all`: in addition to generalized and specialized, decode streams with supported lossy filters; currently this is just ``/DCTDecode`` (JPEG) -@1@option@1@--stream-data=@1@replaceable@1@option@2@replaceable@2@@2@option@2@ +:samp:`--stream-data=@1@replaceable@1@option@2@replaceable@2@` Controls transformation of stream data. This option predates the - @1@option@1@--compress-streams@2@option@2@ and - @1@option@1@--decode-level@2@option@2@ options. Those options can be + :samp:`--compress-streams` and + :samp:`--decode-level` options. Those options can be used to achieve the same affect with more control. The value of - @1@option@1@@1@replaceable@1@option@2@replaceable@2@@2@option@2@ may + :samp:`@1@replaceable@1@option@2@replaceable@2@` may be one of the following: - - @1@option@1@compress@2@option@2@: recompress stream data when + - :samp:`compress`: recompress stream data when possible (default); equivalent to - @1@option@1@--compress-streams=y@2@option@2@ - @1@option@1@--decode-level=generalized@2@option@2@. Does not + :samp:`--compress-streams=y` + :samp:`--decode-level=generalized`. Does not recompress streams already compressed with ``/FlateDecode`` unless - @1@option@1@--recompress-flate@2@option@2@ is also specified. + :samp:`--recompress-flate` is also specified. - - @1@option@1@preserve@2@option@2@: leave all stream data as is; - equivalent to @1@option@1@--compress-streams=n@2@option@2@ - @1@option@1@--decode-level=none@2@option@2@ + - :samp:`preserve`: leave all stream data as is; + equivalent to :samp:`--compress-streams=n` + :samp:`--decode-level=none` - - @1@option@1@uncompress@2@option@2@: uncompress stream data + - :samp:`uncompress`: uncompress stream data compressed with generalized filters when possible; equivalent to - @1@option@1@--compress-streams=n@2@option@2@ - @1@option@1@--decode-level=generalized@2@option@2@ + :samp:`--compress-streams=n` + :samp:`--decode-level=generalized` -@1@option@1@--recompress-flate@2@option@2@ +:samp:`--recompress-flate` By default, streams already compressed with ``/FlateDecode`` are left alone rather than being uncompressed and recompressed. This option causes qpdf to uncompress and recompress the streams. There is a significant performance cost to using this option, but you probably want to use it if you specify - @1@option@1@--compression-level@2@option@2@. + :samp:`--compression-level`. -@1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@ +:samp:`--compression-level=@1@replaceable@1@level@2@replaceable@2@` When writing new streams that are compressed with ``/FlateDecode``, use the specified compression level. The value of - @1@option@1@level@2@option@2@ should be a number from 1 to 9 and is + :samp:`level` should be a number from 1 to 9 and is passed directly to zlib, which implements deflate compression. Note that qpdf doesn't uncompress and recompress streams by default. To have this option apply to already compressed streams, you should also - specify @1@option@1@--recompress-flate@2@option@2@. If your goal is + specify :samp:`--recompress-flate`. If your goal is to shrink the size of PDF files, you should also use - @1@option@1@--object-streams=generate@2@option@2@. + :samp:`--object-streams=generate`. -@1@option@1@--normalize-content=[yn]@2@option@2@ +:samp:`--normalize-content=[yn]` Enables or disables normalization of content streams. Content normalization is enabled by default in QDF mode. Please see `QDF Mode <#ref.qdf>`__ for additional discussion of QDF mode. -@1@option@1@--object-streams=@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ +:samp:`--object-streams=@1@replaceable@1@mode@2@replaceable@2@` Controls handling of object streams. The value of - @1@option@1@@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ may be + :samp:`@1@replaceable@1@mode@2@replaceable@2@` may be one of the following: - - @1@option@1@preserve@2@option@2@: preserve original object streams + - :samp:`preserve`: preserve original object streams (default) - - @1@option@1@disable@2@option@2@: don't write any object streams + - :samp:`disable`: don't write any object streams - - @1@option@1@generate@2@option@2@: use object streams wherever + - :samp:`generate`: use object streams wherever possible -@1@option@1@--preserve-unreferenced@2@option@2@ +:samp:`--preserve-unreferenced` Tells qpdf to preserve objects that are not referenced when writing the file. Ordinarily any object that is not referenced in a traversal of the document from the trailer dictionary will be discarded. This @@ -1562,10 +1562,10 @@ following options are available: indirect differently from the original file, and the original file may have gaps in its numbering. - See also @1@option@1@--preserve-unreferenced-resources@2@option@2@, + See also :samp:`--preserve-unreferenced-resources`, which does something completely different. -@1@option@1@--remove-unreferenced-resources=@1@replaceable@1@option@2@replaceable@2@@2@option@2@ +:samp:`--remove-unreferenced-resources=@1@replaceable@1@option@2@replaceable@2@` The @1@replaceable@1@option@2@replaceable@2@ may be ``auto``, ``yes``, or ``no``. The default is ``auto``. @@ -1592,14 +1592,14 @@ following options are available: be removing. If you encounter that case, please report it as bug at https://github.com/qpdf/qpdf/issues/. -@1@option@1@--preserve-unreferenced-resources@2@option@2@ +:samp:`--preserve-unreferenced-resources` This is a synonym for - @1@option@1@--remove-unreferenced-resources=no@2@option@2@. + :samp:`--remove-unreferenced-resources=no`. - See also @1@option@1@--preserve-unreferenced@2@option@2@, which does + See also :samp:`--preserve-unreferenced`, which does something completely different. -@1@option@1@--newline-before-endstream@2@option@2@ +:samp:`--newline-before-endstream` Tells qpdf to insert a newline before the ``endstream`` keyword, not counted in the length, after any stream content even if the last character of the stream was a newline. This may result in two @@ -1608,7 +1608,7 @@ following options are available: at least prevents it from removing compliance on already compliant files. -@1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@ +:samp:`--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@` Write the first pass of linearization to the named file. The resulting file is not a valid PDF file. This option is useful only for debugging ``QPDFWriter``'s linearization code. When qpdf @@ -1617,7 +1617,7 @@ following options are available: and the linearization dictionary. Ordinarily, the first pass is discarded. This option enables it to be captured. -@1@option@1@--coalesce-contents@2@option@2@ +:samp:`--coalesce-contents` When a page's contents are split across multiple streams, this option causes qpdf to combine them into a single stream. Use of this option is never necessary for ordinary usage, but it can help when working @@ -1625,7 +1625,7 @@ following options are available: with QDF mode or content normalization to make it easier to look at all of a page's contents at once. -@1@option@1@--flatten-annotations=@1@replaceable@1@option@2@replaceable@2@@2@option@2@ +:samp:`--flatten-annotations=@1@replaceable@1@option@2@replaceable@2@` This option collapses annotations into the pages' contents with special handling for form fields. Ordinarily, an annotation is rendered separately and on top of the page. Combining annotations @@ -1637,13 +1637,13 @@ following options are available: annotations. The @1@replaceable@1@option@2@replaceable@2@ parameter may be any of the following: - - @1@option@1@all@2@option@2@: include all annotations that are not + - :samp:`all`: include all annotations that are not marked invisible or hidden - - @1@option@1@print@2@option@2@: only include annotations that + - :samp:`print`: only include annotations that indicate that they should appear when the page is printed - - @1@option@1@screen@2@option@2@: omit annotations that indicate + - :samp:`screen`: omit annotations that indicate they should not appear on the screen Note that form fields are special because the annotations that are @@ -1655,14 +1655,14 @@ following options are available: chance to go back and resave the form with a program that knows how to generate appearances. QPDF itself can generate appearances with some limitations. See the - @1@option@1@--generate-appearances@2@option@2@ option below. + :samp:`--generate-appearances` option below. -@1@option@1@--generate-appearances@2@option@2@ +:samp:`--generate-appearances` If a file contains interactive form fields and indicates that the appearances are out of date with the values of the form, this flag will regenerate appearances, subject to a few limitations. Note that there is not usually a reason to do this, but it can be necessary - before using the @1@option@1@--flatten-annotations@2@option@2@ + before using the :samp:`--flatten-annotations` option. Most of these are not a problem with well-behaved PDF files. The limitations are as follows: @@ -1690,61 +1690,61 @@ following options are available: application to save your filled-in form before processing it with qpdf. -@1@option@1@--optimize-images@2@option@2@ +:samp:`--optimize-images` This flag causes qpdf to recompress all images that are not compressed with DCT (JPEG) using DCT compression as long as doing so decreases the size in bytes of the image data and the image does not fall below minimum specified dimensions. Useful information is provided when used in combination with - @1@option@1@--verbose@2@option@2@. See also the - @1@option@1@--oi-min-width@2@option@2@, - @1@option@1@--oi-min-height@2@option@2@, and - @1@option@1@--oi-min-area@2@option@2@ options. By default, starting + :samp:`--verbose`. See also the + :samp:`--oi-min-width`, + :samp:`--oi-min-height`, and + :samp:`--oi-min-area` options. By default, starting in qpdf 8.4, inline images are converted to regular images and - optimized as well. Use @1@option@1@--keep-inline-images@2@option@2@ + optimized as well. Use :samp:`--keep-inline-images` to prevent inline images from being included. -@1@option@1@--oi-min-width=@1@replaceable@1@width@2@replaceable@2@@2@option@2@ +:samp:`--oi-min-width=@1@replaceable@1@width@2@replaceable@2@` Avoid optimizing images whose width is below the specified amount. If omitted, the default is 128 pixels. Use 0 for no minimum. -@1@option@1@--oi-min-height=@1@replaceable@1@height@2@replaceable@2@@2@option@2@ +:samp:`--oi-min-height=@1@replaceable@1@height@2@replaceable@2@` Avoid optimizing images whose height is below the specified amount. If omitted, the default is 128 pixels. Use 0 for no minimum. -@1@option@1@--oi-min-area=@1@replaceable@1@area-in-pixels@2@replaceable@2@@2@option@2@ +:samp:`--oi-min-area=@1@replaceable@1@area-in-pixels@2@replaceable@2@` Avoid optimizing images whose pixel count (width × height) is below the specified amount. If omitted, the default is 16,384 pixels. Use 0 for no minimum. -@1@option@1@--externalize-inline-images@2@option@2@ +:samp:`--externalize-inline-images` Convert inline images to regular images. By default, images whose data is at least 1,024 bytes are converted when this option is - selected. Use @1@option@1@--ii-min-bytes@2@option@2@ to change the + selected. Use :samp:`--ii-min-bytes` to change the size threshold. This option is implicitly selected when - @1@option@1@--optimize-images@2@option@2@ is selected. Use - @1@option@1@--keep-inline-images@2@option@2@ to exclude inline images + :samp:`--optimize-images` is selected. Use + :samp:`--keep-inline-images` to exclude inline images from image optimization. -@1@option@1@--ii-min-bytes=@1@replaceable@1@bytes@2@replaceable@2@@2@option@2@ +:samp:`--ii-min-bytes=@1@replaceable@1@bytes@2@replaceable@2@` Avoid converting inline images whose size is below the specified minimum size to regular images. If omitted, the default is 1,024 bytes. Use 0 for no minimum. -@1@option@1@--keep-inline-images@2@option@2@ +:samp:`--keep-inline-images` Prevent inline images from being included in image optimization. This - option has no affect when @1@option@1@--optimize-images@2@option@2@ + option has no affect when :samp:`--optimize-images` is not specified. -@1@option@1@--remove-page-labels@2@option@2@ +:samp:`--remove-page-labels` Remove page labels from the output file. -@1@option@1@--qdf@2@option@2@ +:samp:`--qdf` Turns on QDF mode. For additional information on QDF, please see `QDF - Mode <#ref.qdf>`__. Note that @1@option@1@--linearize@2@option@2@ + Mode <#ref.qdf>`__. Note that :samp:`--linearize` disables QDF mode. -@1@option@1@--min-version=@1@replaceable@1@version@2@replaceable@2@@2@option@2@ +:samp:`--min-version=@1@replaceable@1@version@2@replaceable@2@` Forces the PDF version of the output file to be at least @1@replaceable@1@version@2@replaceable@2@. In other words, if the input file has a lower version than the specified version, the @@ -1762,11 +1762,11 @@ following options are available: version ``1.7.8`` represents version 1.7 at extension level 8. Note that minimal syntax checking is done on the command line. -@1@option@1@--force-version=@1@replaceable@1@version@2@replaceable@2@@2@option@2@ +:samp:`--force-version=@1@replaceable@1@version@2@replaceable@2@` This option forces the PDF version to be the exact version specified *even when the file may have content that is not supported in that version*. The version number is interpreted in the same way as with - @1@option@1@--min-version@2@option@2@ so that extension levels can be + :samp:`--min-version` so that extension levels can be set. In some cases, forcing the output file's PDF 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 @@ -1793,9 +1793,9 @@ understands and is not already compressed using a good compression scheme, qpdf will uncompress and recompress streams. Assuming proper filter implements, this is safe and generally results in smaller files. This behavior may also be explicitly requested with -@1@option@1@--stream-data=compress@2@option@2@. +:samp:`--stream-data=compress`. -When @1@option@1@--normalize-content=y@2@option@2@ is specified, qpdf +When :samp:`--normalize-content=y` is specified, qpdf will attempt to normalize whitespace and newlines in page content streams. This is generally safe but could, in some cases, cause damage to the content streams. This option is intended for people who wish to @@ -1811,9 +1811,9 @@ string, name, or inline image. Note that files that do this are invalid since the PDF specification states that content streams are not to be split in the middle of a token. If you want to inspect the original content streams in an uncompressed format, you can always run with -@1@option@1@--qdf --normalize-content=n@2@option@2@ for a QDF file +:samp:`--qdf --normalize-content=n` for a QDF file without content normalization, or alternatively -@1@option@1@--stream-data=uncompress@2@option@2@ for a regular non-QDF +:samp:`--stream-data=uncompress` for a regular non-QDF mode file with uncompressed streams. These will both 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 @@ -1824,22 +1824,22 @@ the PDF specification at version 1.5, corresponding to Acrobat 6. Some older PDF viewers may not support files with object streams. qpdf can be used to transform files with object streams to files without object streams or vice versa. As mentioned above, there are three object stream -modes: @1@option@1@preserve@2@option@2@, -@1@option@1@disable@2@option@2@, and @1@option@1@generate@2@option@2@. +modes: :samp:`preserve`, +:samp:`disable`, and :samp:`generate`. -In @1@option@1@preserve@2@option@2@ mode, the relationship to objects +In :samp:`preserve` mode, the relationship to objects and the streams that contain them is preserved from the original file. -In @1@option@1@disable@2@option@2@ mode, all objects are written as +In :samp:`disable` mode, all objects are written as regular, uncompressed objects. The resulting file should be readable by older PDF viewers. (Of course, the content of the files may include features not supported by older viewers, but at least the structure will -be supported.) In @1@option@1@generate@2@option@2@ mode, qpdf will +be supported.) In :samp:`generate` mode, qpdf will create its own object streams. This will usually result in more compact PDF files, though they may not be readable by older viewers. In this mode, qpdf will also make sure the PDF version number in the header is at least 1.5. -The @1@option@1@--qdf@2@option@2@ flag turns on QDF mode, which changes +The :samp:`--qdf` flag turns on QDF mode, which changes some of the defaults described above. Specifically, in QDF mode, by default, stream data is uncompressed, content streams are normalized, and encryption is removed. These defaults can still be overridden by @@ -1862,7 +1862,7 @@ automated test suites for software that uses the qpdf library. When any of the options in this section are specified, no output file should be given. The following options are available: -@1@option@1@--deterministic-id@2@option@2@ +:samp:`--deterministic-id` Causes generation of a deterministic value for /ID. 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 @@ -1872,138 +1872,138 @@ given. The following options are available: caching results or for generation of some test data. Use of this flag is not compatible with creation of encrypted files. -@1@option@1@--static-id@2@option@2@ +:samp:`--static-id` Causes generation of a fixed value for /ID. This is intended for testing only. Never use it for production files. If you are trying to get the same /ID each time for a given file and you are not generating encrypted files, consider using the - @1@option@1@--deterministic-id@2@option@2@ option. + :samp:`--deterministic-id` option. -@1@option@1@--static-aes-iv@2@option@2@ +:samp:`--static-aes-iv` Causes use of a static initialization vector for AES-CBC. This is intended for testing only so that output files can be reproducible. Never use it for production files. This option in particular is not secure since it significantly weakens the encryption. -@1@option@1@--no-original-object-ids@2@option@2@ +:samp:`--no-original-object-ids` Suppresses inclusion of original object ID comments in QDF files. This can be useful when generating QDF files for test purposes, particularly when comparing them to determine whether two PDF files have identical content. -@1@option@1@--show-encryption@2@option@2@ +:samp:`--show-encryption` Shows document encryption parameters. Also shows the document's user password if the owner password is given. -@1@option@1@--show-encryption-key@2@option@2@ +:samp:`--show-encryption-key` When encryption information is being displayed, as when - @1@option@1@--check@2@option@2@ or - @1@option@1@--show-encryption@2@option@2@ is given, display the + :samp:`--check` or + :samp:`--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 @1@option@1@--password@2@option@2@ if the - @1@option@1@--password-is-hex-key@2@option@2@ is specified. Note + argument to :samp:`--password` if the + :samp:`--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 enables retrieval of that key. -@1@option@1@--check-linearization@2@option@2@ +:samp:`--check-linearization` Checks file integrity and linearization status. -@1@option@1@--show-linearization@2@option@2@ +:samp:`--show-linearization` Checks and displays all data in the linearization hint tables. -@1@option@1@--show-xref@2@option@2@ +:samp:`--show-xref` Shows the contents of the cross-reference table in a human-readable form. This is especially useful for files with cross-reference streams which are stored in a binary format. -@1@option@1@--show-object=trailer|obj[,gen]@2@option@2@ +:samp:`--show-object=trailer|obj[,gen]` Show the contents of the given object. This is especially useful for inspecting objects that are inside of object streams (also known as "compressed objects"). -@1@option@1@--raw-stream-data@2@option@2@ - When used along with the @1@option@1@--show-object@2@option@2@ +:samp:`--raw-stream-data` + When used along with the :samp:`--show-object` option, if the object is a stream, shows the raw stream data instead of object's contents. -@1@option@1@--filtered-stream-data@2@option@2@ - When used along with the @1@option@1@--show-object@2@option@2@ +:samp:`--filtered-stream-data` + When used along with the :samp:`--show-object` option, if the object is a stream, shows the filtered stream data instead of object's contents. If the stream is filtered using filters that qpdf does not support, an error will be issued. -@1@option@1@--show-npages@2@option@2@ +:samp:`--show-npages` Prints the number of pages in the input file on a line by itself. Since the number of pages appears by itself on a line, this option can be useful for scripting if you need to know the number of pages in a file. -@1@option@1@--show-pages@2@option@2@ +:samp:`--show-pages` Shows the object and generation number for each page dictionary object and for each content stream associated with the page. Having this information makes it more convenient to inspect objects from a particular page. -@1@option@1@--with-images@2@option@2@ - When used along with @1@option@1@--show-pages@2@option@2@, also shows +:samp:`--with-images` + When used along with :samp:`--show-pages`, also shows the object and generation numbers for the image objects on each page. (At present, information about images in shared resource dictionaries are not output by this command. This is discussed in a comment in the source code.) -@1@option@1@--json@2@option@2@ +:samp:`--json` Generate a JSON representation of the file. This is described in depth in `QPDF JSON <#ref.json>`__ -@1@option@1@--json-help@2@option@2@ +:samp:`--json-help` Describe the format of the JSON output. -@1@option@1@--json-key=key@2@option@2@ +:samp:`--json-key=key` This option is repeatable. If specified, only top-level keys specified will be included in the JSON output. If not specified, all keys will be shown. -@1@option@1@--json-object=trailer|obj[,gen]@2@option@2@ +:samp:`--json-object=trailer|obj[,gen]` This option is repeatable. If specified, only specified objects will be shown in the "``objects``" key of the JSON output. If absent, all objects will be shown. -@1@option@1@--check@2@option@2@ +:samp:`--check` Checks file structure and well as encryption, linearization, and encoding of stream data. A file for which - @1@option@1@--check@2@option@2@ reports no errors may still have + :samp:`--check` reports no errors may still have errors in stream data content but should otherwise be structurally - sound. If @1@option@1@--check@2@option@2@ any errors, qpdf will exit + sound. If :samp:`--check` any errors, qpdf will exit with a status of 2. There are some recoverable conditions that - @1@option@1@--check@2@option@2@ detects. These are issued as warnings + :samp:`--check` detects. These are issued as warnings instead of errors. If qpdf finds no errors but finds warnings, it will exit with a status of 3 (as of version 2.0.4). When - @1@option@1@--check@2@option@2@ is combined with other options, + :samp:`--check` is combined with other options, checks are always performed before any other options are processed. - For erroneous files, @1@option@1@--check@2@option@2@ will cause qpdf + For erroneous files, :samp:`--check` will cause qpdf to attempt to recover, after which other options are effectively operating on the recovered file. Combining - @1@option@1@--check@2@option@2@ with other options in this way can be + :samp:`--check` with other options in this way can be useful for manually recovering severely damaged files. Note that - @1@option@1@--check@2@option@2@ produces no output to standard output + :samp:`--check` produces no output to standard output when everything is valid, so if you are using this to programmatically validate files in bulk, it is safe to run without output redirected to :file:`/dev/null` and just check for a 0 exit code. -The @1@option@1@--raw-stream-data@2@option@2@ and -@1@option@1@--filtered-stream-data@2@option@2@ options are ignored -unless @1@option@1@--show-object@2@option@2@ is given. Either of these +The :samp:`--raw-stream-data` and +:samp:`--filtered-stream-data` options are ignored +unless :samp:`--show-object` is given. Either of these options will cause the stream data to be written to standard output. In order to avoid commingling of stream data with other output, it is recommend that these objects not be combined with other test/inspection options. -If @1@option@1@--filtered-stream-data@2@option@2@ is given and -@1@option@1@--normalize-content=y@2@option@2@ is also given, qpdf will +If :samp:`--filtered-stream-data` is given and +:samp:`--normalize-content=y` is also given, qpdf will attempt to normalize the stream data as if it is a page content stream. This attempt will be made even if it is not a page content stream, in which case it will produce unusable results. @@ -2055,23 +2055,23 @@ would contain strings of even numbers of characters that alternate between accented letters and symbols. In the extremely unlikely event that you are intentionally using such passwords and qpdf is thwarting you by interpreting them as UTF-8, you can use -@1@option@1@--password-mode=bytes@2@option@2@ to suppress qpdf's +:samp:`--password-mode=bytes` to suppress qpdf's automatic behavior. -The @1@option@1@--password-mode@2@option@2@ option, as described earlier +The :samp:`--password-mode` option, as described earlier in this chapter, can be used to change qpdf's interpretation of supplied passwords. There are very few reasons to use this option. One would be the unlikely case described in the previous paragraph in which the supplied password happens to be valid UTF-8 but isn't supposed to be UTF-8. Your best bet would be just to provide the password as a valid UTF-8 string, but you could also use -@1@option@1@--password-mode=bytes@2@option@2@. Another reason to use -@1@option@1@--password-mode=bytes@2@option@2@ would be to intentionally +:samp:`--password-mode=bytes`. Another reason to use +:samp:`--password-mode=bytes` would be to intentionally generate PDF files encrypted with passwords that are not properly encoded. The qpdf test suite does this to generate invalid files for the purpose of testing its password recovery capability. If you were trying to create intentionally incorrect files for a similar purposes, the -@1@option@1@bytes@2@option@2@ password mode can enable you to do this. +:samp:`bytes` password mode can enable you to do this. When qpdf attempts to decrypt a file with a password that contains non-ASCII characters, it will generate a list of alternative passwords @@ -2089,7 +2089,7 @@ recovery methods should make qpdf transparently open most encrypted files with the password supplied correctly but in the wrong coding system. There are no real downsides to this behavior, but if you don't want qpdf to do this, you can use the -@1@option@1@--suppress-password-recovery@2@option@2@ option. One reason +:samp:`--suppress-password-recovery` option. One reason to do that is to ensure that you know the exact password that was used to encrypt the file. @@ -2105,7 +2105,7 @@ will be addressed in a future version of qpdf. The ``QPDFWriter`` methods that enable encryption on the output file accept passwords as strings of bytes. -Please note that the @1@option@1@--password-is-hex-key@2@option@2@ +Please note that the :samp:`--password-is-hex-key` option is unrelated to all this. This flag bypasses the normal process of going from password to encryption string entirely, allowing the raw encryption key to be specified directly. This is useful for forensic @@ -2315,12 +2315,12 @@ cryptography algorithm, and MD5, which is a weak hashing algorithm. In version 10.4, qpdf generates warnings for some (but not all) cases of writing files with weak cryptography when invoked from the command-line. These warnings can be suppressed using the -@1@option@1@--allow-weak-crypto@2@option@2@ option. +:samp:`--allow-weak-crypto` option. It is planned for qpdf version 11 to be stricter, making it an error to write files with insecure cryptography from the command-line tool in most cases without specifying the -@1@option@1@--allow-weak-crypto@2@option@2@ flag and also to require +:samp:`--allow-weak-crypto` flag and also to require explicit steps when using the C++ library to enable use of insecure cryptography. @@ -2387,7 +2387,7 @@ Compatibility Documentation The :command:`qpdf` command can be invoked with the - @1@option@1@--json-help@2@option@2@ option. This will output a JSON + :samp:`--json-help` option. This will output a JSON structure that has the same structure as the JSON output that qpdf generates, except that each field in the help output is a description of the corresponding field in the JSON output. The specific @@ -2470,7 +2470,7 @@ There are a few limitations to be aware of with the JSON structure: encoding. In other words, it's best if you don't try to use the JSON format to extract binary strings from the PDF file, but if you really had to, it could be done. Note that qpdf's - @1@option@1@--show-object@2@option@2@ option does not have this + :samp:`--show-object` option does not have this limitation and will reveal the string as encoded in the original file. @@ -2486,9 +2486,9 @@ be aware of: - While qpdf guarantees that keys present in the help will be present in the output, those fields may be null or empty if the information is not known or absent in the file. Also, if you specify - @1@option@1@--json-keys@2@option@2@, the keys that are not listed + :samp:`--json-keys`, the keys that are not listed will be excluded entirely except for those that - @1@option@1@--json-help@2@option@2@ says are always present. + :samp:`--json-help` says are always present. - In a few places, there are keys with names containing ``pageposfrom1``. The values of these keys are null or an integer. If @@ -2504,7 +2504,7 @@ be aware of: - The image information included in the ``page`` section of the JSON output includes the key "``filterable``". Note that the value of this - field may depend on the @1@option@1@--decode-level@2@option@2@ that + field may depend on the :samp:`--decode-level` that you invoke qpdf with. The JSON output includes a top-level key "``parameters``" that indicates the decode level used for computing whether a stream was filterable. For example, jpeg images will be @@ -3630,8 +3630,8 @@ Implementation Notes -------------------- There are three modes for writing object streams: -@1@option@1@disable@2@option@2@, @1@option@1@preserve@2@option@2@, and -@1@option@1@generate@2@option@2@. In disable mode, we do not generate +:samp:`disable`, :samp:`preserve`, and +:samp:`generate`. In disable mode, we do not generate any object streams, and we also generate an xref table rather than xref streams. This can be used to generate PDF files that are viewable with older readers. In preserve mode, we write object streams such that @@ -3642,7 +3642,7 @@ ourselves by grouping objects that are allowed in object streams together in sets of no more than 100 objects. We also ensure that the PDF version is at least 1.5 in generate mode, but we preserve the version header in the other modes. The default is -@1@option@1@preserve@2@option@2@. +:samp:`preserve`. We do not support creation of hybrid files. When we write files, even in preserve mode, we will lose any xref tables and merge any appended @@ -3697,7 +3697,7 @@ For a detailed list of changes, please see the file - Handling of Weak Cryptography Algorithms - From the qpdf CLI, the - @1@option@1@--allow-weak-crypto@2@option@2@ is now required to + :samp:`--allow-weak-crypto` is now required to suppress a warning when explicitly creating PDF files using RC4 encryption. While qpdf will always retain the ability to read and write such files, doing so will require explicit @@ -3716,7 +3716,7 @@ For a detailed list of changes, please see the file (with no resource dictionary). - Fix crash that could occur under certain conditions when using - @1@option@1@--pages@2@option@2@ with files that had form + :samp:`--pages` with files that had form fields. - Library Enhancements @@ -3735,7 +3735,7 @@ For a detailed list of changes, please see the file - CLI Enhancements - Improve diagnostics around parsing - @1@option@1@--pages@2@option@2@ command-line options + :samp:`--pages` command-line options - Packaging Changes @@ -3747,7 +3747,7 @@ For a detailed list of changes, please see the file - When generating a file while preserving object streams, unreferenced objects are correctly removed unless - @1@option@1@--preserve-unreferenced@2@option@2@ is specified. + :samp:`--preserve-unreferenced` is specified. - Library Enhancements @@ -3810,19 +3810,19 @@ For a detailed list of changes, please see the file - Operations that work on combining pages are much better about protecting form fields. In particular, - @1@option@1@--split-pages@2@option@2@ and - @1@option@1@--pages@2@option@2@ now preserve interaction form + :samp:`--split-pages` and + :samp:`--pages` now preserve interaction form functionality by copying the relevant form field information from the original files. Additionally, if you use - @1@option@1@--pages@2@option@2@ to select only some pages from + :samp:`--pages` to select only some pages from the original input file, unused form fields are removed, which prevents lots of unused annotations from being retained. - By default, :command:`qpdf` no longer allows creation of encrypted PDF files whose user password is non-empty and owner password is empty when a 256-bit key is in - use. The @1@option@1@--allow-insecure@2@option@2@ option, - specified inside the @1@option@1@--encrypt@2@option@2@ options, + use. The :samp:`--allow-insecure` option, + specified inside the :samp:`--encrypt` options, allows creation of such files. Behavior changes in the CLI are avoided when possible, but an exception was made here because this is security-related. qpdf must always allow creation of @@ -3864,7 +3864,7 @@ For a detailed list of changes, please see the file Files/Attachments Options <#ref.attachments>`__ for details. - Page splitting and merging operations, as well as - @1@option@1@--flatten-rotation@2@option@2@, are better behaved + :samp:`--flatten-rotation`, are better behaved with respect to annotations and interactive form fields. In most cases, interactive form field functionality and proper formatting and functionality of annotations is preserved by @@ -3877,12 +3877,12 @@ For a detailed list of changes, please see the file that is out of spec but that works in most viewers anyway). - The option - @1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@ + :samp:`--password-file=@1@replaceable@1@filename@2@replaceable@2@` can now be used to read the decryption password from a file. You can use ``-`` as the file name to read the password from standard input. This is an easier/more obvious way to read passwords from files or standard input than using - @1@option@1@@file@2@option@2@ for this purpose. + :samp:`@file` for this purpose. - Add some information about attachments to the json output, and added ``attachments`` as an additional json key. The @@ -3893,12 +3893,12 @@ For a detailed list of changes, please see the file extraction of attachments. More detailed information can be obtained by following the reference to the file spec object. - - Add numeric option to @1@option@1@--collate@2@option@2@. If - @1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@ + - Add numeric option to :samp:`--collate`. If + :samp:`--collate=@1@replaceable@1@n@2@replaceable@2@` is given, take pages in groups of @1@replaceable@1@n@2@replaceable@2@ from the given files. - - It is now valid to provide @1@option@1@--rotate=0@2@option@2@ + - It is now valid to provide :samp:`--rotate=0` to clear rotation from a page. - Library Enhancements @@ -3976,7 +3976,7 @@ For a detailed list of changes, please see the file - Bug Fixes - - The @1@option@1@--flatten-rotation@2@option@2@ option applies + - The :samp:`--flatten-rotation` option applies transformations to any annotations that may be on the page. - If a form XObject lacks a resources dictionary, consider any @@ -3999,7 +3999,7 @@ For a detailed list of changes, please see the file 10.1.0: January 5, 2021 - CLI Enhancements - - Add @1@option@1@--flatten-rotation@2@option@2@ command-line + - Add :samp:`--flatten-rotation` command-line option, which causes all pages that are rotated using parameters in the page's dictionary to instead be identically rotated in the page's contents. The change is not user-visible @@ -4119,7 +4119,7 @@ For a detailed list of changes, please see the file - Bug Fixes - When concatenating content streams, as with - @1@option@1@--coalesce-contents@2@option@2@, there were cases + :samp:`--coalesce-contents`, there were cases in which qpdf would merge two lexical tokens together, creating invalid results. A newline is now inserted between merged content streams if one is not already present. @@ -4136,23 +4136,23 @@ For a detailed list of changes, please see the file already ignored the user's locale for numeric conversion. - Fix several instances in which warnings were not suppressed in - spite of @1@option@1@--no-warn@2@option@2@ and/or errors or + spite of :samp:`--no-warn` and/or errors or warnings were written to standard output rather than standard error. - Fixed a memory leak that could occur under specific circumstances when - @1@option@1@--object-streams=generate@2@option@2@ was used. + :samp:`--object-streams=generate` was used. - Fix various integer overflows and similar conditions found by the OSS-Fuzz project. - Enhancements - - New option @1@option@1@--warning-exit-0@2@option@2@ causes qpdf + - New option :samp:`--warning-exit-0` causes qpdf to exit with a status of ``0`` rather than ``3`` if there are warnings but no errors. Combine with - @1@option@1@--no-warn@2@option@2@ to completely ignore + :samp:`--no-warn` to completely ignore warnings. - Performance improvements have been made to @@ -4163,7 +4163,7 @@ For a detailed list of changes, please see the file - Build Changes - - The option @1@option@1@--disable-rpath@2@option@2@ is now + - The option :samp:`--disable-rpath` is now supported by qpdf's :command:`./configure` script. Some distributions' packaging standards recommended the use of this option. @@ -4265,7 +4265,7 @@ For a detailed list of changes, please see the file :command:`qpdf --json-help` for details. - Add new option - @1@option@1@--remove-unreferenced-resources@2@option@2@ which + :samp:`--remove-unreferenced-resources` which takes ``auto``, ``yes``, or ``no`` as arguments. The new ``auto`` mode, which is the default, performs a fast heuristic over a PDF file when splitting pages to determine whether the @@ -4276,9 +4276,9 @@ For a detailed list of changes, please see the file Options <#ref.advanced-transformation>`__ for a more detailed discussion. - - The @1@option@1@--preserve-unreferenced-resources@2@option@2@ + - The :samp:`--preserve-unreferenced-resources` is now just a synonym for - @1@option@1@--remove-unreferenced-resources=no@2@option@2@. + :samp:`--remove-unreferenced-resources=no`. - If the ``QPDF_EXECUTABLE`` environment variable is set when invoking :command:`qpdf --bash-completion` or @@ -4370,8 +4370,8 @@ For a detailed list of changes, please see the file - CLI Enhancements - - Added options @1@option@1@--is-encrypted@2@option@2@ and - @1@option@1@--requires-password@2@option@2@ for testing whether + - Added options :samp:`--is-encrypted` and + :samp:`--requires-password` for testing whether a file is encrypted or requires a password other than the supplied (or empty) password. These communicate via exit status, making them useful for shell scripts. They also work on @@ -4380,7 +4380,7 @@ For a detailed list of changes, please see the file - Added ``encrypt`` key to JSON options. With the exception of the reconstructed user password for older encryption formats, this provides the same information as - @1@option@1@--show-encryption@2@option@2@ but in a consistent, + :samp:`--show-encryption` but in a consistent, parseable format. See output of :command:`qpdf --json-help` for details. @@ -4388,7 +4388,7 @@ For a detailed list of changes, please see the file - In QDF mode, be sure not to write more than one XRef stream to a file, even when - @1@option@1@--preserve-unreferenced@2@option@2@ is used. + :samp:`--preserve-unreferenced` is used. :command:`fix-qdf` assumes that there is only one XRef stream, and that it appears at the end of the file. @@ -4437,7 +4437,7 @@ For a detailed list of changes, please see the file - CLI Enhancements - - Addition of the @1@option@1@--show-crypto@2@option@2@ option in + - Addition of the :samp:`--show-crypto` option in support of selectable crypto providers, as described in `Crypto Providers <#ref.crypto>`__. @@ -4452,7 +4452,7 @@ For a detailed list of changes, please see the file - Bug Fix - Fix the name of the temporary file used by - @1@option@1@--replace-input@2@option@2@ so that it doesn't + :samp:`--replace-input` so that it doesn't require path splitting and works with paths include directories. @@ -4505,22 +4505,22 @@ For a detailed list of changes, please see the file - CLI Enhancements - - The @1@option@1@--replace-input@2@option@2@ option may be given + - The :samp:`--replace-input` option may be given in place of an output file name. This causes qpdf to overwrite the input file with the output. See the description of - @1@option@1@--replace-input@2@option@2@ in `Basic + :samp:`--replace-input` in `Basic Options <#ref.basic-options>`__ for more details. - - The @1@option@1@--recompress-flate@2@option@2@ instructs + - The :samp:`--recompress-flate` instructs :command:`qpdf` to recompress streams that are already compressed with ``/FlateDecode``. Useful with - @1@option@1@--compression-level@2@option@2@. + :samp:`--compression-level`. - The - @1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@ + :samp:`--compression-level=@1@replaceable@1@level@2@replaceable@2@` sets the zlib compression level used for any streams compressed by ``/FlateDecode``. Most effective when combined with - @1@option@1@--recompress-flate@2@option@2@. + :samp:`--recompress-flate`. - Library Enhancements @@ -4614,8 +4614,8 @@ For a detailed list of changes, please see the file a file with linearization warnings but not errors, it now properly exits with exit code 3 instead of 2. - - The @1@option@1@--completion-bash@2@option@2@ and - @1@option@1@--completion-zsh@2@option@2@ options now work + - The :samp:`--completion-bash` and + :samp:`--completion-zsh` options now work properly when qpdf is invoked as an AppImage. - Calling ``QPDFWriter::set*EncryptionParameters`` on a @@ -4630,7 +4630,7 @@ For a detailed list of changes, please see the file - Build Changes - On platforms that support it, qpdf now builds with - @1@option@1@-fvisibility=hidden@2@option@2@. If you build qpdf + :samp:`-fvisibility=hidden`. If you build qpdf with your own build system, this is now safe to use. This prevents methods that are not part of the public API from being exported by the shared library, and makes qpdf's ELF shared @@ -4679,7 +4679,7 @@ For a detailed list of changes, please see the file qpdf than the library, which may indicate a problem with the installation. - - New option @1@option@1@--remove-page-labels@2@option@2@ will + - New option :samp:`--remove-page-labels` will remove page labels before generating output. This used to happen if you ran :command:`qpdf --empty --pages .. --`, but the behavior changed in qpdf 8.3.0. This @@ -4687,7 +4687,7 @@ For a detailed list of changes, please see the file get it again. - New option - @1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@ + :samp:`--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@` can be used to override number of files that qpdf will use to trigger the behavior of not keeping all files open when merging files. This may be necessary if your system allows fewer than @@ -4706,7 +4706,7 @@ For a detailed list of changes, please see the file during page splitting operations. - Revert change that included preservation of outlines - (bookmarks) in @1@option@1@--split-pages@2@option@2@. The way + (bookmarks) in :samp:`--split-pages`. The way it was implemented in 8.3.0 and 8.4.0 caused a very significant degradation of performance for splitting certain files. A future release of qpdf may re-introduce the behavior in a more @@ -4759,17 +4759,17 @@ For a detailed list of changes, please see the file depth in `Unicode Passwords <#ref.unicode-passwords>`__. - New options - @1@option@1@--externalize-inline-images@2@option@2@, - @1@option@1@--ii-min-bytes@2@option@2@, and - @1@option@1@--keep-inline-images@2@option@2@ control qpdf's + :samp:`--externalize-inline-images`, + :samp:`--ii-min-bytes`, and + :samp:`--keep-inline-images` control qpdf's handling of inline images and possible conversion of them to regular images. By default, - @1@option@1@--optimize-images@2@option@2@ now also applies to + :samp:`--optimize-images` now also applies to inline images. These options are discussed in `Advanced Transformation Options <#ref.advanced-transformation>`__. - - Add options @1@option@1@--overlay@2@option@2@ and - @1@option@1@--underlay@2@option@2@ for overlaying or + - Add options :samp:`--overlay` and + :samp:`--underlay` for overlaying or underlaying pages of other files onto output pages. See `Overlay and Underlay Options <#ref.overlay-underlay>`__ for details. @@ -4779,33 +4779,33 @@ For a detailed list of changes, please see the file non-ASCII characters, qpdf will try a number of alternative passwords to try to compensate for possible character encoding errors. This behavior can be suppressed with the - @1@option@1@--suppress-password-recovery@2@option@2@ option. + :samp:`--suppress-password-recovery` option. See `Unicode Passwords <#ref.unicode-passwords>`__ for a full discussion. - - Add the @1@option@1@--password-mode@2@option@2@ option to + - Add the :samp:`--password-mode` option to fine-tune how qpdf interprets password arguments, especially when they contain non-ASCII characters. See `Unicode Passwords <#ref.unicode-passwords>`__ for more information. - - In the @1@option@1@--pages@2@option@2@ option, it is now + - In the :samp:`--pages` option, it is now possible to copy the same page more than once from the same file without using the previous workaround of specifying two different paths to the same file. - - In the @1@option@1@--pages@2@option@2@ option, allow use of "." + - In the :samp:`--pages` option, allow use of "." as a shortcut for the primary input file. That way, you can do :command:`qpdf in.pdf --pages . 1-2 -- out.pdf` instead of having to repeat :file:`in.pdf` in the command. - When encrypting with 128-bit and 256-bit encryption, new - encryption options @1@option@1@--assemble@2@option@2@, - @1@option@1@--annotate@2@option@2@, - @1@option@1@--form@2@option@2@, and - @1@option@1@--modify-other@2@option@2@ allow more fine-grained + encryption options :samp:`--assemble`, + :samp:`--annotate`, + :samp:`--form`, and + :samp:`--modify-other` allow more fine-grained granularity in configuring options. Before, the - @1@option@1@--modify@2@option@2@ option only configured certain + :samp:`--modify` option only configured certain predefined groups of permissions. - Bug Fixes and Enhancements @@ -4816,7 +4816,7 @@ For a detailed list of changes, please see the file file's internal structure shared these resource lists across pages and if some but not all of the pages in the output did not reference all the fonts and images. Using the - @1@option@1@--preserve-unreferenced-resources@2@option@2@ + :samp:`--preserve-unreferenced-resources` option would work around the incorrect behavior. This bug was the result of a typo in the code and a deficiency in the test suite. The case that triggered the error was known, just not @@ -4831,7 +4831,7 @@ For a detailed list of changes, please see the file from files that have duplicate Page objects in the pages tree. - Using older option - @1@option@1@--stream-data=compress@2@option@2@ with object + :samp:`--stream-data=compress` with object streams, object streams and xref streams were not compressed. - When the tokenizer returns inline image tokens, delimiters @@ -4919,7 +4919,7 @@ For a detailed list of changes, please see the file - Build Improvements - Add new configure option - @1@option@1@--enable-avoid-windows-handle@2@option@2@, which + :samp:`--enable-avoid-windows-handle`, which causes the preprocessor symbol ``AVOID_WINDOWS_HANDLE`` to be defined. When defined, qpdf will avoid referencing the Windows ``HANDLE`` type, which is disallowed with certain versions of @@ -4944,11 +4944,11 @@ For a detailed list of changes, please see the file - Page numbers (also known as page labels) are now preserved when merging and splitting files with the - @1@option@1@--pages@2@option@2@ and - @1@option@1@--split-pages@2@option@2@ options. + :samp:`--pages` and + :samp:`--split-pages` options. - Bookmarks are partially preserved when splitting pages with the - @1@option@1@--split-pages@2@option@2@ option. Specifically, the + :samp:`--split-pages` option. Specifically, the outlines dictionary and some supporting metadata are copied into the split files. The result is that all bookmarks from the original file appear, those that point to pages that are @@ -4958,50 +4958,50 @@ For a detailed list of changes, please see the file operations. - Page collation: add new option - @1@option@1@--collate@2@option@2@. When specified, the - semantics of @1@option@1@--pages@2@option@2@ change from + :samp:`--collate`. When specified, the + semantics of :samp:`--pages` change from concatenation to collation. See `Page Selection Options <#ref.page-selection>`__ for examples and discussion. - Generation of information in JSON format, primarily to facilitate use of qpdf from languages other than C++. Add new - options @1@option@1@--json@2@option@2@, - @1@option@1@--json-key@2@option@2@, and - @1@option@1@--json-object@2@option@2@ to generate a JSON + options :samp:`--json`, + :samp:`--json-key`, and + :samp:`--json-object` to generate a JSON representation of the PDF file. Run :command:`qpdf --json-help` to get a description of the JSON format. For more information, see `QPDF JSON <#ref.json>`__. - - The @1@option@1@--generate-appearances@2@option@2@ flag will + - The :samp:`--generate-appearances` flag will cause qpdf to generate appearances for form fields if the PDF file indicates that form field appearances are out of date. This can happen when PDF forms are filled in by a program that doesn't know how to regenerate the appearances of the filled-in fields. - - The @1@option@1@--flatten-annotations@2@option@2@ flag can be + - The :samp:`--flatten-annotations` flag can be used to *flatten* annotations, including form fields. Ordinarily, annotations are drawn separately from the page. Flattening annotations is the process of combining their appearances into the page's contents. You might want to do this if you are going to rotate or combine pages using a tool that doesn't understand about annotations. You may also want to use - @1@option@1@--generate-appearances@2@option@2@ when using this + :samp:`--generate-appearances` when using this flag since annotations for outdated form fields are not flattened as that would cause loss of information. - - The @1@option@1@--optimize-images@2@option@2@ flag tells qpdf + - The :samp:`--optimize-images` flag tells qpdf to recompresses every image using DCT (JPEG) compression as long as the image is not already compressed with lossy compression and recompressing the image reduces its size. The - additional options @1@option@1@--oi-min-width@2@option@2@, - @1@option@1@--oi-min-height@2@option@2@, and - @1@option@1@--oi-min-area@2@option@2@ prevent recompression of + additional options :samp:`--oi-min-width`, + :samp:`--oi-min-height`, and + :samp:`--oi-min-area` prevent recompression of images whose width, height, or pixel area (width × height) are below a specified threshold. - - The @1@option@1@--show-object@2@option@2@ option can now be - given as @1@option@1@--show-object=trailer@2@option@2@ to show + - The :samp:`--show-object` option can now be + given as :samp:`--show-object=trailer` to show the trailer dictionary. - Bug Fixes and Enhancements @@ -5024,7 +5024,7 @@ For a detailed list of changes, please see the file Instead, it issues a normal warning or error. - Ordinarily qpdf treats an argument of the form - @1@option@1@@file@2@option@2@ to mean that command-line options + :samp:`@file` to mean that command-line options should be read from :file:`file`. Now, if :file:`file` does not exist but :file:`@file` does, qpdf will treat @@ -5135,7 +5135,7 @@ For a detailed list of changes, please see the file your packaging system automatically refreshes libtool or autoconf files, it could cause this check to fail. To avoid this problem, pass - @1@option@1@--disable-check-autofiles@2@option@2@ to + :samp:`--disable-check-autofiles` to :command:`configure`. - If you would like to have qpdf completion enabled @@ -5148,16 +5148,16 @@ For a detailed list of changes, please see the file - Command-line Enhancements - Add - @1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@ + :samp:`--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@` to override default determination of whether to keep files open when merging. Please see the discussion of - @1@option@1@--keep-files-open@2@option@2@ in `Basic + :samp:`--keep-files-open` in `Basic Options <#ref.basic-options>`__ for additional details. 8.2.0: August 16, 2018 - Command-line Enhancements - - Add @1@option@1@--no-warn@2@option@2@ option to suppress + - Add :samp:`--no-warn` option to suppress issuing warning messages. If there are any conditions that would have caused warnings to be issued, the exit status is still 3. @@ -5177,7 +5177,7 @@ For a detailed list of changes, please see the file - Bug fix: end of line characters were not properly handled inside strings in some cases. - - Bug fix: using @1@option@1@--progress@2@option@2@ on very small + - Bug fix: using :samp:`--progress` on very small files could cause an infinite loop. - API enhancements @@ -5217,7 +5217,7 @@ For a detailed list of changes, please see the file old behavior should be desired, or if you have a case where page splitting is very slow, the old behavior (and speed) can be enabled by specifying - @1@option@1@--preserve-unreferenced-resources@2@option@2@. For + :samp:`--preserve-unreferenced-resources`. For additional details, please see `Advanced Transformation Options <#ref.advanced-transformation>`__. @@ -5226,19 +5226,19 @@ For a detailed list of changes, please see the file that may exceed the operating system's limit for the maximum number of open files. - - The @1@option@1@--rotate@2@option@2@ option's syntax has been + - The :samp:`--rotate` option's syntax has been extended to make the page range optional. If you specify - @1@option@1@--rotate=@1@replaceable@1@angle@2@replaceable@2@@2@option@2@ + :samp:`--rotate=@1@replaceable@1@angle@2@replaceable@2@` without specifying a page range, the rotation will be applied to all pages. This can be especially useful for adjusting a PDF created from a multi-page document that was scanned upside down. - When merging multiple files, the - @1@option@1@--verbose@2@option@2@ option now prints information + :samp:`--verbose` option now prints information about each file as it operates on that file. - - When the @1@option@1@--progress@2@option@2@ option is + - When the :samp:`--progress` option is specified, qpdf will print a running indicator of its best guess at how far through the writing process it is. Note that, as with all progress meters, it's an approximation. This option @@ -5294,7 +5294,7 @@ For a detailed list of changes, please see the file it thinks it is through writing its output. Client programs can use this to implement reasonably accurate progress meters. The :command:`qpdf` command line tool uses this to - implement its @1@option@1@--progress@2@option@2@ option. + implement its :samp:`--progress` option. - New methods ``QPDFObjectHandle::newUnicodeString`` and ``QPDFObject::unparseBinary`` have been added to allow for more @@ -5352,10 +5352,10 @@ For a detailed list of changes, please see the file `Running QPDF <#ref.using>`__. - The option - @1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@ + :samp:`--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@` has been added for debugging qpdf's linearization code. - - The option @1@option@1@--coalesce-contents@2@option@2@ can be + - The option :samp:`--coalesce-contents` can be used to combine content streams of a page whose contents are an array of streams into a single stream. @@ -5404,7 +5404,7 @@ For a detailed list of changes, please see the file password when opening encrypted files, and will optionally display the encryption key used by a file. This is a non-standard operation, but it can be useful in certain situations. Please see - the discussion of @1@option@1@--password-is-hex-key@2@option@2@ in + the discussion of :samp:`--password-is-hex-key` in `Basic Options <#ref.basic-options>`__ or the comments around ``QPDF::setPasswordIsHexKey`` in :file:`QPDF.hh` for additional details. @@ -5442,8 +5442,8 @@ For a detailed list of changes, please see the file or RunLength encoding. Library API enhancements and command-line options have been added to control this behavior. See command-line options - @1@option@1@--compress-streams@2@option@2@ and - @1@option@1@--decode-level@2@option@2@ and methods + :samp:`--compress-streams` and + :samp:`--decode-level` and methods ``QPDFWriter::setCompressStreams`` and ``QPDFWriter::setDecodeLevel``. @@ -5469,27 +5469,27 @@ For a detailed list of changes, please see the file input using ``@file`` or ``@-`` syntax. Please see `Basic Invocation <#ref.invocation>`__. - - @1@option@1@--rotate@2@option@2@: request page rotation + - :samp:`--rotate`: request page rotation - - @1@option@1@--newline-before-endstream@2@option@2@: ensure that + - :samp:`--newline-before-endstream`: ensure that a newline appears before every ``endstream`` keyword in the file; used to prevent qpdf from breaking PDF/A compliance on already compliant files. - - @1@option@1@--preserve-unreferenced@2@option@2@: preserve + - :samp:`--preserve-unreferenced`: preserve unreferenced objects in the input PDF - - @1@option@1@--split-pages@2@option@2@: break output into chunks + - :samp:`--split-pages`: break output into chunks with fixed numbers of pages - - @1@option@1@--verbose@2@option@2@: print the name of each + - :samp:`--verbose`: print the name of each output file that is created - - @1@option@1@--compress-streams@2@option@2@ and - @1@option@1@--decode-level@2@option@2@ replace - @1@option@1@--stream-data@2@option@2@ for improving granularity + - :samp:`--compress-streams` and + :samp:`--decode-level` replace + :samp:`--stream-data` for improving granularity of controlling compression and decompression of stream data. - The @1@option@1@--stream-data@2@option@2@ option will remain + The :samp:`--stream-data` option will remain available. - When running :command:`qpdf --check` with other @@ -5500,8 +5500,8 @@ For a detailed list of changes, please see the file reference table, or other similar operations. - Process :command:`--pages` earlier so that other - options like @1@option@1@--show-pages@2@option@2@ or - @1@option@1@--split-pages@2@option@2@ can operate on the file + options like :samp:`--show-pages` or + :samp:`--split-pages` can operate on the file after page splitting/merging has occurred. - API Changes. All new API calls are documented in their respective @@ -5534,7 +5534,7 @@ For a detailed list of changes, please see the file ``QPDFWriter`` methods. 6.0.0: November 10, 2015 - - Implement @1@option@1@--deterministic-id@2@option@2@ command-line + - Implement :samp:`--deterministic-id` command-line option and ``QPDFWriter::setDeterministicID`` as well as C API function ``qpdf_set_deterministic_ID`` for generating a deterministic ID for non-encrypted files. When this option is @@ -5618,11 +5618,11 @@ For a detailed list of changes, please see the file Windows build, this results in an added dependency on Microsoft's cryptography API. To disable the OS-specific cryptography and use the old version, pass the - @1@option@1@--enable-insecure-random@2@option@2@ option to + :samp:`--enable-insecure-random` option to :command:`./configure`. - The :command:`qpdf` command-line tool now issues a - warning when @1@option@1@-accessibility=n@2@option@2@ is specified + warning when :samp:`-accessibility=n` is specified for newer encryption versions stating that the option is ignored. qpdf, per the spec, has always ignored this flag, but it previously did so silently. This warning is issued only by the @@ -5647,12 +5647,12 @@ For a detailed list of changes, please see the file :file:`QPDFObjectHandle.hh` for additional notes. - - Add @1@option@1@--show-npages@2@option@2@ command-line option to + - Add :samp:`--show-npages` command-line option to the :command:`qpdf` command to show the number of pages in a file. - Allow omission of the page range within - @1@option@1@--pages@2@option@2@ for the + :samp:`--pages` for the :command:`qpdf` command. When omitted, the page range is implicitly taken to be all the pages in the file. @@ -5701,7 +5701,7 @@ For a detailed list of changes, please see the file - Warning flags have been moved into a separate variable in :file:`autoconf.mk` - - The configure flag @1@option@1@--enable-werror@2@option@2@ work + - The configure flag :samp:`--enable-werror` work for Microsoft compilers - All MSVC CRT security warnings have been resolved. @@ -5837,12 +5837,12 @@ For a detailed list of changes, please see the file ``QPDFWriter``. - Removed the method ``decodeStreams``. This method was used by - the @1@option@1@--check@2@option@2@ option of the + the :samp:`--check` option of the :command:`qpdf` command-line tool to force all streams in the file to be decoded, but it also suffered from the problem of opening otherwise unreferenced streams and thus could report false positive. The - @1@option@1@--check@2@option@2@ option now causes qpdf to go + :samp:`--check` option now causes qpdf to go through all the motions of writing a new file based on the original one, so it will always reference and check exactly those parts of a file that any ordinary viewer would check. @@ -5951,7 +5951,7 @@ For a detailed list of changes, please see the file - When building on a platform that supports ELF shared libraries (such as Linux), symbol versions are enabled by default. They can be disabled by passing - @1@option@1@--disable-ld-version-script@2@option@2@ to + :samp:`--disable-ld-version-script` to :command:`./configure`. - The file :file:`libqpdf.pc` is now installed @@ -5972,7 +5972,7 @@ For a detailed list of changes, please see the file terminal anymore by default. Instead, find them in :file:`build/qtest.log`. For packagers who are building with an autobuilder, you can add the - @1@option@1@--enable-show-failed-test-output@2@option@2@ option to + :samp:`--enable-show-failed-test-output` option to :command:`./configure` to restore the old behavior. 2.3.1: December 28, 2011 @@ -6180,7 +6180,7 @@ For a detailed list of changes, please see the file permissions, it does make them available so that applications that use qpdf can enforce permissions. - - The @1@option@1@--check@2@option@2@ option to + - The :samp:`--check` option to :command:`qpdf` has been extended to include some additional information. |