diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml index ae144af..78bab7f 100644 --- a/manual/qpdf-manual.xml +++ b/manual/qpdf-manual.xml @@ -107,8 +107,8 @@ Building and Installing QPDF This chapter describes how to build and install qpdf. Please see - also the README.md and - INSTALL files in the source distribution. + also the @1@filename@1@README.md@2@filename@2@ and + @1@filename@1@INSTALL@2@filename@2@ files in the source distribution. System Requirements @@ -162,8 +162,8 @@ url="http://www.gnu.org/software/diffutils/">http://www.gnu.org/software/diffutils/ is required to run the test suite. Note that this is the version of diff present on virtually all GNU/Linux systems. - This is required because the test suite uses diff - -u. + This is required because the test suite uses @1@command@1@diff + -u@2@command@2@. @@ -182,8 +182,8 @@ 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 configure with the - flag. If you enable + Enable them by running @1@command@1@configure@2@command@2@ with the + @1@option@1@--enable-test-compare-images@2@option@2@ 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. @@ -223,23 +223,23 @@ ./configure make - You can also run make check to run the test - suite and make install to install. Please run - ./configure --help for options on what can be + You can also run @1@command@1@make check@2@command@2@ to run the test + suite and @1@command@1@make install@2@command@2@ to install. Please run + @1@command@1@./configure --help@2@command@2@ for options on what can be configured. You can also set the value of DESTDIR during installation to install to a temporary location, as is common with many open source packages. - Please see also the README.md and - INSTALL files in the source distribution. + Please see also the @1@filename@1@README.md@2@filename@2@ and + @1@filename@1@INSTALL@2@filename@2@ files in the source distribution. Building on Windows is a little bit more complicated. For - details, please see README-windows.md in the + details, please see @1@filename@1@README-windows.md@2@filename@2@ in the source distribution. You can also download a binary distribution for Windows. There is a port of qpdf to Visual C++ version 6 in - the contrib area generously contributed by + the @1@filename@1@contrib@2@filename@2@ area generously contributed by Jian Ma. This is also discussed in more detail in - README-windows.md. + @1@filename@1@README-windows.md@2@filename@2@. While wchar_t is part of the C++ standard, qpdf uses @@ -253,11 +253,11 @@ make There are some other things you can do with the build. Although - qpdf uses autoconf, it does not use - automake but instead uses a + qpdf uses @1@application@1@autoconf@2@application@2@, it does not use + @1@application@1@automake@2@application@2@ but instead uses a hand-crafted non-recursive Makefile that requires gnu make. If you're really interested, please read the comments in the - top-level Makefile. + top-level @1@filename@1@Makefile@2@filename@2@. @@ -284,41 +284,41 @@ make When building with qpdf's build system, crypto providers can be enabled at build time using various - ./configure options. The default behavior is - for ./configure to discover which crypto + @1@command@1@./configure@2@command@2@ options. The default behavior is + for @1@command@1@./configure@2@command@2@ to discover which crypto providers can be supported based on available external libraries, to build all 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 - ./configure: + @1@command@1@./configure@2@command@2@: - - (where x is a supported crypto - provider): enable the x crypto + @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@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 - : - disable the x provider, and do not + @1@option@1@--disable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@: + disable the @1@replaceable@1@x@2@replaceable@2@ provider, and do not link against its dependencies even if they are available - : - make x the default provider even if + @1@option@1@--with-default-crypto=@1@replaceable@1@x@2@replaceable@2@@2@option@2@: + make @1@replaceable@1@x@2@replaceable@2@ the default provider even if a higher priority one is available - : only build crypto + @1@option@1@--disable-implicit-crypto@2@option@2@: 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@ option @@ -327,19 +327,19 @@ make For example, if you want to guarantee that the gnutls crypto provider is used and that the native provider is not built, you - could run ./configure --enable-crypto-gnutls - --disable-implicit-crypto. + could run @1@command@1@./configure --enable-crypto-gnutls + --disable-implicit-crypto@2@command@2@. If you build qpdf using your own build system, in order for qpdf to work at all, you need to enable at least one crypto provider. - The file libqpdf/qpdf/qpdf-config.h.in + The file @1@filename@1@libqpdf/qpdf/qpdf-config.h.in@2@filename@2@ provides macros DEFAULT_CRYPTO, whose value must be a string naming the default crypto provider, and various symbols starting with USE_CRYPTO_, at least one of which has to be enabled. Additionally, you must compile the source files that implement a crypto provider. To get a list - of those files, look at libqpdf/build.mk. If + of those files, look at @1@filename@1@libqpdf/build.mk@2@filename@2@. If you want to omit a particular crypto provider, as long as its USE_CRYPTO_ symbol is undefined, you can completely ignore the source files that belong to a particular @@ -354,16 +354,16 @@ make "native". Then you must include the source files used in the native implementation, some of which were added or renamed from earlier versions, to your build, and you can - ignore QPDFCrypto_gnutls.cc. Always consult - libqpdf/build.mk to get the list of source + ignore @1@filename@1@QPDFCrypto_gnutls.cc@2@filename@2@. Always consult + @1@filename@1@libqpdf/build.mk@2@filename@2@ to get the list of source files you need to build. Runtime Crypto Provider Selection - You can use the option to - qpdf to get a list of available crypto + You can use the @1@option@1@--show-crypto@2@option@2@ option to + @1@command@1@qpdf@2@command@2@ 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 itself with no other text, enabling the output of @@ -390,7 +390,7 @@ make class derived from QPDFCryptoImpl and register it with QPDFCryptoProvider. For additional information, see comments in - include/qpdf/QPDFCryptoImpl.hh. + @1@filename@1@include/qpdf/QPDFCryptoImpl.hh@2@filename@2@. @@ -502,8 +502,8 @@ make - Passing to - ./configure will cause any failed test + Passing @1@option@1@--enable-show-failed-test-output@2@option@2@ to + @1@command@1@./configure@2@command@2@ 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 qtest.log after the fact. @@ -519,25 +519,25 @@ make 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 to - /.configure. This is safe since qpdf's - autogen.sh just runs autotools in the normal + passing @1@option@1@--disable-check-autofiles@2@option@2@ to + @1@command@1@/.configure@2@command@2@. This is safe since qpdf's + @1@command@1@autogen.sh@2@command@2@ just runs autotools in the normal way. - QPDF's make install does not install + QPDF's @1@command@1@make install@2@command@2@ does not install completion files by default, but as a packager, it's good if you install them wherever your distribution expects such files to go. You can find completion files to install in the - completions directory. + @1@filename@1@completions@2@filename@2@ directory. Packagers are encouraged to install the source files from the - examples directory along with qpdf + @1@filename@1@examples@2@filename@2@ directory along with qpdf development packages. @@ -556,45 +556,45 @@ make When running qpdf, the basic invocation is as follows: - qpdf } [ page_selection_options ] outfilename + @1@command@1@qpdf@2@command@2@@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@ - This converts PDF file to PDF file - . The output file is functionally + 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 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 , the - parameter may be specified. This causes + 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 use a dummy input file that contains zero pages. The only - normal use case for using would be if you + normal use case for using @1@option@1@--empty@2@option@2@ would be if you were going to add pages from another source, as discussed in . - If appears as a word anywhere in the + If @1@option@1@@filename@2@option@2@ 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 - option allows arguments to be read from + @1@option@1@@-@2@option@2@ 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 can't appear in the middle of an - argument, so constructs such as + the @1@option@1@@filename@2@option@2@ 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 include the argument and its options together in the arguments file. - does not have to be seekable, even + @1@option@1@outfilename@2@option@2@ does not have to be seekable, even when generating linearized files. Specifying - “” as + “@1@option@1@-@2@option@2@” as @1@option@1@outfilename@2@option@2@ means to write to standard output. If you want to overwrite the input file with the output, use the option - and omit the output file name. + @1@option@1@--replace-input@2@option@2@ 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 - option. + @1@option@1@--replace-input@2@option@2@ option. Most options require an output file, but some testing or @@ -603,14 +603,14 @@ make Exit Status - The exit status of qpdf may be interpreted as + The exit status of @1@command@1@qpdf@2@command@2@ may be interpreted as follows: 0: no errors or warnings were found. The file may still have problems qpdf can't detect. If - was specified, exit status 0 + @1@option@1@--warning-exit-0@2@option@2@ was specified, exit status 0 is used even if there are warnings. @@ -626,16 +626,16 @@ make 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 - is specified. With - , warnings without errors + @1@option@1@--no-warn@2@option@2@ is specified. With + @1@option@1@--warning-exit-0@2@option@2@, warnings without errors exit with status 0 instead of 3. - Note that qpdf never exists with status + Note that @1@command@1@qpdf@2@command@2@ never exists with status 1. If you get an exit status of 1, it was something else, like the shell not - being able to find or execute qpdf. + being able to find or execute @1@command@1@qpdf@2@command@2@. @@ -644,9 +644,9 @@ make Starting in qpdf version 8.3.0, qpdf provides its own completion support for zsh and bash. You can enable bash completion with - eval $(qpdf --completion-bash) and zsh - completion with eval $(qpdf --completion-zsh). - If qpdf is not in your path, you should invoke + @1@command@1@eval $(qpdf --completion-bash)@2@command@2@ and zsh + completion with @1@command@1@eval $(qpdf --completion-zsh)@2@command@2@. + If @1@command@1@qpdf@2@command@2@ is not in your path, you should invoke it above with an absolute path. If you invoke it with a relative path, it will warn you, and the completion won't work if you're in a different directory. @@ -667,7 +667,7 @@ make commonly needed transformations. - + @1@option@1@--help@2@option@2@ Display command-line invocation help. @@ -675,7 +675,7 @@ make - + @1@option@1@--version@2@option@2@ Display the current version of qpdf. @@ -683,7 +683,7 @@ make - + @1@option@1@--copyright@2@option@2@ Show detailed copyright information. @@ -691,7 +691,7 @@ make - + @1@option@1@--show-crypto@2@option@2@ Show a list of available crypto providers, each on a line by @@ -702,7 +702,7 @@ make - + @1@option@1@--completion-bash@2@option@2@ Output a completion command you can eval to enable shell @@ -711,7 +711,7 @@ make - + @1@option@1@--completion-zsh@2@option@2@ Output a completion command you can eval to enable shell @@ -720,31 +720,31 @@ make - + @1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@ Specifies a password for accessing encrypted files. To read the password from a file or standard input, you can use - , added in qpdf 10.2. Note - that you can also use or - as described above to put the password in + @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 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@ option in the file. Syntax such as - won't work since - is not recognized in the middle of + @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 an argument. - + @1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@ Reads the first line from the specified file and uses it as the password for accessing encrypted files. - may be + @1@option@1@@1@replaceable@1@filename@2@replaceable@2@@2@option@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. @@ -752,21 +752,21 @@ make - + @1@option@1@--is-encrypted@2@option@2@ 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 - . Both this option and - exit with status 2 for + @1@option@1@--requires-password@2@option@2@. Both this option and + @1@option@1@--requires-password@2@option@2@ exit with status 2 for non-encrypted files. - + @1@option@1@--requires-password@2@option@2@ Silently exit with status 0 if a password (other than as @@ -775,18 +775,18 @@ make 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 option, this option can be + with a @1@option@1@--password@2@option@2@ 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 - . Both this option and - exit with status 2 for + @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 non-encrypted files. - + @1@option@1@--verbose@2@option@2@ Increase verbosity of output. For now, this just prints some @@ -795,7 +795,7 @@ make - + @1@option@1@--progress@2@option@2@ Indicate progress while writing files. @@ -803,29 +803,29 @@ make - + @1@option@1@--no-warn@2@option@2@ Suppress writing of warnings to stderr. If warnings were - detected and suppressed, qpdf will still + detected and suppressed, @1@command@1@qpdf@2@command@2@ will still exit with exit code 3. See also - . + @1@option@1@--warning-exit-0@2@option@2@. - + @1@option@1@--warning-exit-0@2@option@2@ If warnings are found but no errors, exit with exit code 0 - instead 3. When combined with , the - effect is for qpdf to completely ignore + instead 3. When combined with @1@option@1@--no-warn@2@option@2@, the + effect is for @1@command@1@qpdf@2@command@2@ to completely ignore warnings. - + @1@option@1@--linearize@2@option@2@ Causes generation of a linearized (web-optimized) output file. @@ -833,27 +833,27 @@ make - + @1@option@1@--replace-input@2@option@2@ 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 - infilename.~qpdf-temp# + @1@filename@1@@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-temp#@2@filename@2@ and, when done, overwriting the input file with the temporary file. If there were any warnings, the original input is saved as - infilename.~qpdf-orig. + @1@filename@1@@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-orig@2@filename@2@. - + @1@option@1@--copy-encryption=file@2@option@2@ Encrypt the file using the same encryption parameters, including user and owner password, as the specified file. Use - to specify a password + @1@option@1@--encryption-file-password@2@option@2@ 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 @@ -862,10 +862,10 @@ make - + @1@option@1@--encryption-file-password=password@2@option@2@ - If the file specified with + If the file specified with @1@option@1@--copy-encryption@2@option@2@ 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 @@ -876,7 +876,7 @@ make - + @1@option@1@--allow-weak-crypto@2@option@2@ Starting with version 10.4, qpdf issues warnings when @@ -889,7 +889,7 @@ make - + @1@option@1@--encrypt options --@2@option@2@ Causes generation an encrypted output file. Please see - + @1@option@1@--decrypt@2@option@2@ Removes any encryption on the file. A password must be @@ -908,17 +908,17 @@ make - + @1@option@1@--password-is-hex-key@2@option@2@ 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 + specified, the argument to the @1@option@1@--password@2@option@2@ 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 - or other options or to files being + @1@option@1@--pages@2@option@2@ or other options or to files being written. @@ -931,13 +931,13 @@ make 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 + normally, use the @1@option@1@--show-encryption-key@2@option@2@ option. - + @1@option@1@--suppress-password-recovery@2@option@2@ Ordinarily, qpdf attempts to automatically compensate for @@ -949,14 +949,14 @@ make - + @1@option@1@--password-mode=@1@replaceable@1@mode@2@replaceable@2@@2@option@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 + line. With the exception of the @1@option@1@hex-bytes@2@option@2@ mode, these only apply to passwords provided when encrypting - files. The mode also applies to + files. The @1@option@1@hex-bytes@2@option@2@ 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 . @@ -964,7 +964,7 @@ make - : Automatically determine whether the + @1@option@1@auto@2@option@2@: 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 @@ -975,22 +975,22 @@ make - : Tells qpdf that the incoming + @1@option@1@unicode@2@option@2@: Tells qpdf that the incoming password is UTF-8, overriding whatever its automatic detection determines. The only difference between this mode - and is that qpdf will fail with an + and @1@option@1@auto@2@option@2@ is that qpdf will fail with an error message if the password is not valid UTF-8 instead of - falling back to mode with a warning. + falling back to @1@option@1@bytes@2@option@2@ mode with a warning. - : Interpret the password as a literal + @1@option@1@bytes@2@option@2@: 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 - option to do it, in which case + @1@option@1@@filename@2@option@2@ 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. @@ -998,10 +998,10 @@ make - : Interpret the password as a + @1@option@1@hex-bytes@2@option@2@: 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 - , this option may allow creation of + @1@option@1@bytes@2@option@2@, 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 @@ -1014,33 +1014,33 @@ make - + @1@option@1@--rotate=[+|-]angle[:page-range]@2@option@2@ Apply rotation to specified pages. The - portion of the option value has + @1@option@1@page-range@2@option@2@ portion of the option value has the same format as page ranges in . If the page range is omitted, the rotation is applied to all pages. The - portion of the parameter may be either - 0, 90, 180, or 270. If preceded by or - , the angle is added to or subtracted from + @1@option@1@angle@2@option@2@ 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@, 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 appearances of the pages to be inconsistent, especially for scans. For example, the - command qpdf in.pdf out.pdf --rotate=+90:2,4,6 - --rotate=180:7-8 would rotate pages 2, 4, and 6 90 + command @1@command@1@qpdf in.pdf out.pdf --rotate=+90:2,4,6 + --rotate=180:7-8@2@command@2@ would rotate pages 2, 4, and 6 90 degrees clockwise from their original rotation and force the rotation of pages 7 through 8 to 180 degrees regardless of - their original rotation, and the command qpdf in.pdf - out.pdf --rotate=+180 would rotate all pages by 180 + their original rotation, and the command @1@command@1@qpdf in.pdf + out.pdf --rotate=+180@2@command@2@ would rotate all pages by 180 degrees. - + @1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@ This option controls whether qpdf keeps individual files open @@ -1056,33 +1056,33 @@ make with 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 - flag. If you are merging + @1@option@1@--keep-files-open@2@option@2@ 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 - , especially if working + @1@option@1@--keep-files-open=y@2@option@2@, 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 . + you may want to specify @1@option@1@--keep-files-open=n@2@option@2@. The threshold for switching may be changed from the default - 200 with the + 200 with the @1@option@1@--keep-files-open-threshold@2@option@2@ option. - + @1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@ If specified, overrides the default value of 200 used as the threshold for qpdf deciding whether or not to keep files open. - See for details. + See @1@option@1@--keep-files-open@2@option@2@ for details. - + @1@option@1@--pages options --@2@option@2@ Select specific pages from one or more input files. See - + @1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@ When specified, collate rather than concatenate pages from - files specified with . With a numeric - argument, collate in groups of n. + files specified with @1@option@1@--pages@2@option@2@. With a numeric + argument, collate in groups of @1@replaceable@1@n@2@replaceable@2@. The default is 1. See for additional details. - + @1@option@1@--flatten-rotation@2@option@2@ For each page that is rotated using the @@ -1117,11 +1117,11 @@ make - + @1@option@1@--split-pages=[n]@2@option@2@ - Write each group of pages to a separate - output file. If is not specified, create + 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 single pages. Output file names are generated as follows: @@ -1134,7 +1134,7 @@ make Otherwise, if the output file name ends in - .pdf (case insensitive), a zero-padded + @1@filename@1@.pdf@2@filename@2@ (case insensitive), a zero-padded page range, preceded by a dash, is inserted before the file extension. @@ -1150,29 +1150,29 @@ make Page ranges are a single number in the case of single-page groups or two numbers separated by a dash otherwise. - For example, if infile.pdf has 12 pages + For example, if @1@filename@1@infile.pdf@2@filename@2@ has 12 pages - qpdf --split-pages infile.pdf %d-out - would generate files 01-out through - 12-out + @1@command@1@qpdf --split-pages infile.pdf %d-out@2@command@2@ + would generate files @1@filename@1@01-out@2@filename@2@ through + @1@filename@1@12-out@2@filename@2@ - qpdf --split-pages=2 infile.pdf - outfile.pdf would generate files - outfile-01-02.pdf through - outfile-11-12.pdf + @1@command@1@qpdf --split-pages=2 infile.pdf + outfile.pdf@2@command@2@ would generate files + @1@filename@1@outfile-01-02.pdf@2@filename@2@ through + @1@filename@1@outfile-11-12.pdf@2@filename@2@ - qpdf --split-pages infile.pdf - something.else would generate files - something.else-01 through - something.else-12 + @1@command@1@qpdf --split-pages infile.pdf + something.else@2@command@2@ would generate files + @1@filename@1@something.else-01@2@filename@2@ through + @1@filename@1@something.else-12@2@filename@2@ @@ -1182,15 +1182,15 @@ make original PDF file are not preserved. For each page of output, this 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 qpdf with the - option once for each file. Using - is much faster if you don't + have to run @1@command@1@qpdf@2@command@2@ 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 require the global data. - + @1@option@1@--overlay options --@2@option@2@ Overlay pages from another file onto the output pages. See @@ -1200,7 +1200,7 @@ make - + @1@option@1@--underlay options --@2@option@2@ Overlay pages from another file onto the output pages. See @@ -1214,9 +1214,9 @@ make Password-protected files may be opened by specifying a password. By default, qpdf will preserve any encryption data associated with - a file. If is specified, qpdf will + a file. If @1@option@1@--decrypt@2@option@2@ is specified, qpdf will attempt to remove any encryption information. If - is specified, qpdf will replace the + @1@option@1@--encrypt@2@option@2@ is specified, qpdf will replace the document's encryption parameters with whatever is specified. @@ -1234,7 +1234,7 @@ make the user. Starting in qpdf 8.4.0, qpdf does this automatically in most cases. For an in-depth discussion, please see . Previous versions of this - manual described workarounds using the iconv + manual described workarounds using the @1@command@1@iconv@2@command@2@ command. Such workarounds are no longer required or recommended with qpdf 8.4.0. However, for backward compatibility, qpdf attempts to detect those workarounds and do the right thing in @@ -1247,9 +1247,9 @@ make To change the encryption parameters of a file, use the --encrypt flag. 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@ - Note that “” terminates parsing of + Note that “@1@option@1@--@2@option@2@” terminates parsing of encryption flags and must be present even if no restrictions are present. @@ -1259,22 +1259,22 @@ make 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 , as + the encryption option @1@option@1@--allow-insecure@2@option@2@, as described below. The value for - may be 40, + @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@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 is 40, + If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ is 40, the following restriction options are available: - + @1@option@1@--print=[yn]@2@option@2@ Determines whether or not to allow printing. @@ -1282,7 +1282,7 @@ make - + @1@option@1@--modify=[yn]@2@option@2@ Determines whether or not to allow document modification. @@ -1290,7 +1290,7 @@ make - + @1@option@1@--extract=[yn]@2@option@2@ Determines whether or not to allow text/image extraction. @@ -1298,7 +1298,7 @@ make - + @1@option@1@--annotate=[yn]@2@option@2@ Determines whether or not to allow comments and form fill-in @@ -1307,11 +1307,11 @@ make - If is 128, + If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@2@ is 128, the following restriction options are available: - + @1@option@1@--accessibility=[yn]@2@option@2@ Determines whether or not to allow accessibility to visually @@ -1325,7 +1325,7 @@ make - + @1@option@1@--extract=[yn]@2@option@2@ Determines whether or not to allow text/graphic extraction. @@ -1333,7 +1333,7 @@ make - + @1@option@1@--assemble=[yn]@2@option@2@ Determines whether document assembly (rotation and reordering @@ -1342,18 +1342,18 @@ make - + @1@option@1@--annotate=[yn]@2@option@2@ Determines whether modifying annotations is allowed. This includes adding comments and filling in form fields. Also allows editing of form fields if - is given. + @1@option@1@--modify-other=y@2@option@2@ is given. - + @1@option@1@--form=[yn]@2@option@2@ Determines whether filling form fields is allowed. @@ -1361,37 +1361,37 @@ make - + @1@option@1@--modify-other=[yn]@2@option@2@ Allow all document editing except those controlled separately - by the , - , and + 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. - + @1@option@1@--print=@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@ Controls printing access. - may be + @1@option@1@@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@ may be one of the following: - : allow full printing + @1@option@1@full@2@option@2@: allow full printing - : allow low-resolution printing only + @1@option@1@low@2@option@2@: allow low-resolution printing only - : disallow printing + @1@option@1@none@2@option@2@: disallow printing @@ -1399,53 +1399,53 @@ make - + @1@option@1@--modify=@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@ Controls modify access. This way of controlling modify access has less granularity than new options added in qpdf 8.4. - may be + @1@option@1@@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@ may be one of the following: - : allow full document modification + @1@option@1@all@2@option@2@: allow full document modification - : allow comment authoring, form + @1@option@1@annotate@2@option@2@: allow comment authoring, form operations, and document assembly - : allow form field fill-in and signing + @1@option@1@form@2@option@2@: allow form field fill-in and signing and document assembly - : allow document assembly only + @1@option@1@assembly@2@option@2@: allow document assembly only - : allow no modifications + @1@option@1@none@2@option@2@: allow no modifications - Using the option does not allow you + Using the @1@option@1@--modify@2@option@2@ 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 - to fine tune. + @1@option@1@--modify=form --assembly=n@2@option@2@ to fine tune. - + @1@option@1@--cleartext-metadata@2@option@2@ If specified, any metadata stream in the document will be left @@ -1455,17 +1455,17 @@ make - + @1@option@1@--use-aes=[yn]@2@option@2@ - If is specified, AES encryption + If @1@option@1@--use-aes=y@2@option@2@ 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@ From qpdf 10.2, qpdf defaults to not allowing creation of PDF @@ -1480,7 +1480,7 @@ make - + @1@option@1@--force-V4@2@option@2@ Use of this option forces the /V and @@ -1494,14 +1494,14 @@ make - If is 256, + If @1@option@1@@1@replaceable@1@key-length@2@replaceable@2@@2@option@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@ This option is not available with 256-bit keys. AES is always @@ -1510,7 +1510,7 @@ make - + @1@option@1@--force-V4@2@option@2@ This option is not available with 256 keys. @@ -1518,7 +1518,7 @@ make - + @1@option@1@--force-R5@2@option@2@ If specified, qpdf sets the minimum version to 1.7 at @@ -1543,17 +1543,17 @@ make file is given as the primary input file is used as the starting point, but its pages are 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@ 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 - “” terminates parsing of page + “@1@option@1@--@2@option@2@” terminates parsing of page selection flags. Starting with qpf 8.4, the special input file name - “.” can be used as a shortcut for the + “@1@filename@1@.@2@filename@2@” can be used as a shortcut for the primary input filename. @@ -1566,7 +1566,7 @@ make 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 as the + input file. To discard these, use @1@option@1@--empty@2@option@2@ as the primary input. @@ -1576,7 +1576,7 @@ make will implicitly use the range 1-z, meaning that it will include all pages in the file. This makes it possible to easily combine all pages in a set of files with a command like - qpdf --empty out.pdf --pages *.pdf --. + @1@command@1@qpdf --empty out.pdf --pages *.pdf --@2@command@2@. The page range is a set of numbers separated by commas, ranges of @@ -1634,22 +1634,22 @@ make Starting in qpdf version 8.3, you can specify the - option. Note that this option is - specified outside of . - When is specified, it changes the - meaning of so that the specified files, + @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 modified by page ranges, are collated rather than concatenated. - For example, if you add the files odd.pdf and - even.pdf containing odd and even pages of a - document respectively, you could run qpdf --collate - odd.pdf --pages odd.pdf even.pdf -- all.pdf to collate + For example, if you add the files @1@filename@1@odd.pdf@2@filename@2@ and + @1@filename@1@even.pdf@2@filename@2@ containing odd and even pages of a + document respectively, you could run @1@command@1@qpdf --collate + odd.pdf --pages odd.pdf even.pdf -- all.pdf@2@command@2@ to collate the pages. This would pick page 1 from odd, page 1 from even, page 2 from odd, page 2 from even, etc. until all pages have been included. Any number of files and page ranges can be specified. If any file has fewer pages, that file is just skipped when its pages - have all been included. For example, if you ran qpdf + have all been included. For example, if you ran @1@command@1@qpdf --collate --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf r1 -- - out.pdf, you would get the following pages in this + out.pdf@2@command@2@, you would get the following pages in this order: a.pdf page 1 @@ -1665,12 +1665,12 @@ make Starting in qpdf version 10.2, you may specify a numeric argument - to . With - , pull - groups of n pages from each file, + to @1@option@1@--collate@2@option@2@. With + @1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@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 qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4 - c.pdf r1 -- out.pdf, you would get the following pages + ran @1@command@1@qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4 + c.pdf r1 -- out.pdf@2@command@2@, you would get the following pages in this order: a.pdf page 1 @@ -1693,46 +1693,46 @@ make outlines (bookmarks) point to actual page objects, so if you select some pages and not others, bookmarks that point to pages that are in the output file will work, and remaining bookmarks - will not work. A future version of qpdf may do + will not work. A future version of @1@command@1@qpdf@2@command@2@ may do a better job at handling these 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 as the primary input + you can always use @1@option@1@--empty@2@option@2@ 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 - infile.pdf while preserving all metadata + @1@filename@1@infile.pdf@2@filename@2@ while preserving all metadata associated with that file, you could use - qpdf + @1@command@1@qpdf@2@command@2@ @1@option@1@infile.pdf --pages . 1-5 -- outfile.pdf@2@option@2@ If you wanted pages 1 through 5 from - infile.pdf but you wanted the rest of the + @1@filename@1@infile.pdf@2@filename@2@ but you wanted the rest of the metadata to be dropped, you could instead run - qpdf + @1@command@1@qpdf@2@command@2@ @1@option@1@--empty --pages infile.pdf 1-5 -- outfile.pdf@2@option@2@ If you wanted to take pages 1–5 from - file1.pdf and pages 11–15 from - file2.pdf in reverse, taking document-level - metadata from file2.pdf, you would run + @1@filename@1@file1.pdf@2@filename@2@ and pages 11–15 from + @1@filename@1@file2.pdf@2@filename@2@ in reverse, taking document-level + metadata from @1@filename@1@file2.pdf@2@filename@2@, you would run - qpdf + @1@command@1@qpdf@2@command@2@ @1@option@1@file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf@2@option@2@ If, for some reason, you wanted to take the first page of an - encrypted file called encrypted.pdf with + encrypted file called @1@filename@1@encrypted.pdf@2@filename@2@ with password pass and repeat it twice in an output file, and if you wanted to drop document-level metadata but preserve encryption, you would use - qpdf +outfile.pdf@2@option@2@ Note that we had to specify the password all three times because - giving a password as + giving a password as @1@option@1@--encryption-file-password@2@option@2@ doesn't count for page selection, and as far as qpdf is concerned, - encrypted.pdf and - ./encrypted.pdf are separated files. These + @1@filename@1@encrypted.pdf@2@filename@2@ and + @1@filename@1@./encrypted.pdf@2@filename@2@ are separated files. These are all corner cases that most users should hopefully never have to be bothered with. @@ -1746,7 +1746,7 @@ outfile.pdf going to do further manipulation on the file and need the two instances of the same original page to be deep copies, then you can specify the file in two different ways. For example - qpdf in.pdf --pages . 1 ./in.pdf 1 -- out.pdf + @1@command@1@qpdf in.pdf --pages . 1 ./in.pdf 1 -- out.pdf@2@command@2@ would create a file with two copies of the first page of the input, and the two copies would share any objects in common. This includes fonts, images, and anything else the page references. @@ -1759,12 +1759,12 @@ outfile.pdf pages from other files onto the output generated by qpdf. Specify overlay or underlay as follows: - { | } file [ ] + { @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 and underlay options are processed late, so they can be combined with other like merging and will apply to the final - output. The and - options work the same way, except + output. The @1@option@1@--overlay@2@option@2@ and + @1@option@1@--underlay@2@option@2@ 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 applied, possibly @@ -1777,19 +1777,19 @@ outfile.pdf 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 - or flag and - the option. The following options are + @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: - : supply a password if the + @1@option@1@--password=password@2@option@2@: supply a password if the overlay/underlay file is encrypted. - : a range of pages in the same + @1@option@1@--to=page-range@2@option@2@: a range of pages in the same form at described in indicates which pages in the output should have the overlay/underlay applied. If not specified, overlay/underlay @@ -1798,20 +1798,20 @@ outfile.pdf - : a range of pages that + @1@option@1@--from=[page-range]@2@option@2@: 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 - is used. + @1@option@1@--repeat@2@option@2@ is used. - : an optional range of + @1@option@1@--repeat=page-range@2@option@2@: 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 . + beginning, you can explicitly use @1@option@1@--from=@2@option@2@. @@ -1821,20 +1821,20 @@ outfile.pdf - --overlay o.pdf --to=1-5 --from=1-3 - --repeat=4 --: overlay the first three pages from file - o.pdf onto the first three pages of the - output, then overlay page 4 from o.pdf + @1@command@1@--overlay o.pdf --to=1-5 --from=1-3 + --repeat=4 --@2@command@2@: overlay the first three pages from file + @1@filename@1@o.pdf@2@filename@2@ onto the first three pages of the + output, then overlay page 4 from @1@filename@1@o.pdf@2@filename@2@ onto pages 4 and 5 of the output. Leave remaining output pages untouched. - --underlay footer.pdf --from= --repeat=1,2 --: - Underlay page 1 of footer.pdf on all odd + @1@command@1@--underlay footer.pdf --from= --repeat=1,2 --@2@command@2@: + Underlay page 1 of @1@filename@1@footer.pdf@2@filename@2@ on all odd output pages, and underlay page 2 of - footer.pdf on all even output pages. + @1@filename@1@footer.pdf@2@filename@2@ on all even output pages. @@ -1847,11 +1847,11 @@ outfile.pdf files from the command line. The following options are available: - + @1@option@1@--list-attachments@2@option@2@ Show the “key” and stream number for embedded - files. With , additional + files. With @1@option@1@--verbose@2@option@2@, 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 @@ -1860,48 +1860,48 @@ outfile.pdf - + @1@option@1@--show-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@ Write the contents of the specified attachment to standard output as binary data. The key should match one of the keys - shown by . If specified + shown by @1@option@1@--list-attachments@2@option@2@. 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@ Add or replace an attachment with the contents of - file. This may be specified more + @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@ The key to use to register the attachment in the embedded files table. Defaults to the last path element of - file. + @1@replaceable@1@file@2@replaceable@2@. - + @1@option@1@--filename=@1@replaceable@1@name@2@replaceable@2@@2@option@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 file. + 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@ The attachment's creation date in PDF format; defaults to @@ -1910,7 +1910,7 @@ outfile.pdf - + @1@option@1@--moddate=@1@replaceable@1@date@2@replaceable@2@@2@option@2@ The attachment's modification date in PDF format; defaults @@ -1919,7 +1919,7 @@ outfile.pdf - + @1@option@1@--mimetype=@1@replaceable@1@type/subtype@2@replaceable@2@@2@option@2@ The mime type for the attachment, e.g. @@ -1932,7 +1932,7 @@ outfile.pdf - + @1@option@1@--description=@1@replaceable@1@"text"@2@replaceable@2@@2@option@2@ Descriptive text for the attachment, displayed by some PDF @@ -1941,12 +1941,12 @@ outfile.pdf - + @1@option@1@--replace@2@option@2@ Indicates that any existing attachment with the same key should be replaced by the new attachment. Otherwise, - qpdf gives an error if an attachment + @1@command@1@qpdf@2@command@2@ gives an error if an attachment with that key is already present. @@ -1956,20 +1956,20 @@ outfile.pdf - + @1@option@1@--remove-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@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 + specified multiple times. Run with @1@option@1@--verbose@2@option@2@ 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@ Copy attachments from another file. This may be specified more @@ -1977,16 +1977,16 @@ outfile.pdf the -- that ends this option: - + @1@option@1@--password=@1@replaceable@1@password@2@replaceable@2@@2@option@2@ If required, the password needed to open - file + @1@replaceable@1@file@2@replaceable@2@ - + @1@option@1@--prefix=@1@replaceable@1@prefix@2@replaceable@2@@2@option@2@ Only required if the file from which attachments are being @@ -2006,11 +2006,11 @@ outfile.pdf When a date is required, the date should conform to the PDF date format specification, which is - D:yyyymmddhhmmss<z>, - where <z> is either + D:@1@replaceable@1@yyyymmddhhmmss<z>@2@replaceable@2@, + where @1@replaceable@1@<z>@2@replaceable@2@ is either Z for UTC or a timezone offset in the form - -hh'mm' or - +hh'mm'. Examples: + @1@replaceable@1@-hh'mm'@2@replaceable@2@ or + @1@replaceable@1@+hh'mm'@2@replaceable@2@. Examples: D:20210207161528-05'00', D:20210207211528Z. @@ -2024,7 +2024,7 @@ outfile.pdf to solve specific problems. The following options are available: - + @1@option@1@--suppress-recovery@2@option@2@ Prevents qpdf from attempting to recover damaged files. @@ -2032,7 +2032,7 @@ outfile.pdf - + @1@option@1@--ignore-xref-streams@2@option@2@ Tells qpdf to ignore any cross-reference streams. @@ -2048,13 +2048,13 @@ outfile.pdf 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 - option will prevent qpdf from + @1@option@1@--suppress-recovery@2@option@2@ 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 + present in a PDF file. If @1@option@1@--ignore-xref-streams@2@option@2@ 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 @@ -2074,34 +2074,34 @@ outfile.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 , + By default, or with @1@option@1@--compress-streams=y@2@option@2@, 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@. - + @1@option@1@--decode-level=@1@replaceable@1@option@2@replaceable@2@@2@option@2@ Controls which streams qpdf tries to decode. The default is - . The following options are + @1@option@1@generalized@2@option@2@. The following options are available: - : do not attempt to decode any streams + @1@option@1@none@2@option@2@: do not attempt to decode any streams - : decode streams filtered with + @1@option@1@generalized@2@option@2@: decode streams filtered with supported generalized filters: /LZWDecode, /FlateDecode, @@ -2112,12 +2112,12 @@ outfile.pdf 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@. - : in addition to generalized, + @1@option@1@specialized@2@option@2@: in addition to generalized, decode streams with supported non-lossy specialized filters; currently this is just /RunLengthDecode @@ -2125,7 +2125,7 @@ outfile.pdf - : in addition to generalized and + @1@option@1@all@2@option@2@: in addition to generalized and specialized, decode streams with supported lossy filters; currently this is just /DCTDecode (JPEG) @@ -2135,40 +2135,40 @@ outfile.pdf - + @1@option@1@--stream-data=@1@replaceable@1@option@2@replaceable@2@@2@option@2@ Controls transformation of stream data. This option predates - the and - options. Those options can be + the @1@option@1@--compress-streams@2@option@2@ and + @1@option@1@--decode-level@2@option@2@ options. Those options can be used to achieve the same affect with more control. The value - of may be + of @1@option@1@@1@replaceable@1@option@2@replaceable@2@@2@option@2@ may be one of the following: - : recompress stream data when + @1@option@1@compress@2@option@2@: recompress stream data when possible (default); equivalent to - - . Does not + @1@option@1@--compress-streams=y@2@option@2@ + @1@option@1@--decode-level=generalized@2@option@2@. Does not recompress streams already compressed with /FlateDecode unless - is also specified. + @1@option@1@--recompress-flate@2@option@2@ is also specified. - : leave all stream data as is; - equivalent to - + @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@ - : uncompress stream data + @1@option@1@uncompress@2@option@2@: uncompress stream data compressed with generalized filters when possible; - equivalent to - + equivalent to @1@option@1@--compress-streams=n@2@option@2@ + @1@option@1@--decode-level=generalized@2@option@2@ @@ -2176,7 +2176,7 @@ outfile.pdf - + @1@option@1@--recompress-flate@2@option@2@ By default, streams already compressed with @@ -2185,29 +2185,29 @@ outfile.pdf 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@. - + @1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@ When writing new streams that are compressed with /FlateDecode, use the specified compression - level. The value of should be a number + level. The value of @1@option@1@level@2@option@2@ 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 - . If your goal is to shrink + @1@option@1@--recompress-flate@2@option@2@. If your goal is to shrink the size of PDF files, you should also use - . + @1@option@1@--object-streams=generate@2@option@2@. - + @1@option@1@--normalize-content=[yn]@2@option@2@ Enables or disables normalization of content streams. Content @@ -2218,27 +2218,27 @@ outfile.pdf - + @1@option@1@--object-streams=@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ Controls handling of object streams. The value of - may be one of + @1@option@1@@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ may be one of the following: - : preserve original object streams + @1@option@1@preserve@2@option@2@: preserve original object streams (default) - : don't write any object streams + @1@option@1@disable@2@option@2@: don't write any object streams - : use object streams wherever + @1@option@1@generate@2@option@2@: use object streams wherever possible @@ -2247,7 +2247,7 @@ outfile.pdf - + @1@option@1@--preserve-unreferenced@2@option@2@ Tells qpdf to preserve objects that are not referenced when @@ -2266,16 +2266,16 @@ outfile.pdf file, and the original file may have gaps in its numbering. - See also , + See also @1@option@1@--preserve-unreferenced-resources@2@option@2@, which does something completely different. - + @1@option@1@--remove-unreferenced-resources=@1@replaceable@1@option@2@replaceable@2@@2@option@2@ - The option may be + The @1@replaceable@1@option@2@replaceable@2@ may be auto, yes, or no. The default is auto. @@ -2311,20 +2311,20 @@ outfile.pdf - + @1@option@1@--preserve-unreferenced-resources@2@option@2@ This is a synonym for - . + @1@option@1@--remove-unreferenced-resources=no@2@option@2@. - See also , which does + See also @1@option@1@--preserve-unreferenced@2@option@2@, which does something completely different. - + @1@option@1@--newline-before-endstream@2@option@2@ Tells qpdf to insert a newline before the @@ -2339,7 +2339,7 @@ outfile.pdf - + @1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@ Write the first pass of linearization to the named file. The @@ -2354,7 +2354,7 @@ outfile.pdf - + @1@option@1@--coalesce-contents@2@option@2@ When a page's contents are split across multiple streams, this @@ -2368,7 +2368,7 @@ outfile.pdf - + @1@option@1@--flatten-annotations=@1@replaceable@1@option@2@replaceable@2@@2@option@2@ This option collapses annotations into the pages' contents @@ -2380,24 +2380,24 @@ outfile.pdf functionality backing this option was added for the benefit of programs that want to create n-up page layouts and other similar things that don't work well with - annotations. The option parameter + annotations. The @1@replaceable@1@option@2@replaceable@2@ parameter may be any of the following: - : include all annotations that are not + @1@option@1@all@2@option@2@: include all annotations that are not marked invisible or hidden - : only include annotations that + @1@option@1@print@2@option@2@: only include annotations that indicate that they should appear when the page is printed - : omit annotations that indicate + @1@option@1@screen@2@option@2@: omit annotations that indicate they should not appear on the screen @@ -2413,13 +2413,13 @@ outfile.pdf the form field to be lost. This gives you a 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 + limitations. See the @1@option@1@--generate-appearances@2@option@2@ option below. - + @1@option@1@--generate-appearances@2@option@2@ If a file contains interactive form fields and indicates that @@ -2427,7 +2427,7 @@ outfile.pdf 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 - option. Most of these + @1@option@1@--flatten-annotations@2@option@2@ option. Most of these are not a problem with well-behaved PDF files. The limitations are as follows: @@ -2485,7 +2485,7 @@ outfile.pdf - + @1@option@1@--optimize-images@2@option@2@ This flag causes qpdf to recompress all images that are not @@ -2493,19 +2493,19 @@ outfile.pdf 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 - . See also the - , - , and - options. By default, starting + @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 in qpdf 8.4, inline images are converted to regular images and optimized as well. Use - to prevent inline images + @1@option@1@--keep-inline-images@2@option@2@ to prevent inline images from being included. - + @1@option@1@--oi-min-width=@1@replaceable@1@width@2@replaceable@2@@2@option@2@ Avoid optimizing images whose width is below the specified @@ -2515,7 +2515,7 @@ outfile.pdf - + @1@option@1@--oi-min-height=@1@replaceable@1@height@2@replaceable@2@@2@option@2@ Avoid optimizing images whose height is below the specified @@ -2525,7 +2525,7 @@ outfile.pdf - + @1@option@1@--oi-min-area=@1@replaceable@1@area-in-pixels@2@replaceable@2@@2@option@2@ Avoid optimizing images whose pixel count @@ -2535,21 +2535,21 @@ outfile.pdf - + @1@option@1@--externalize-inline-images@2@option@2@ 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 to + option is selected. Use @1@option@1@--ii-min-bytes@2@option@2@ to change the size threshold. This option is implicitly selected - when is selected. Use - to exclude inline images + 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 from image optimization. - + @1@option@1@--ii-min-bytes=@1@replaceable@1@bytes@2@replaceable@2@@2@option@2@ Avoid converting inline images whose size is below the @@ -2559,17 +2559,17 @@ outfile.pdf - + @1@option@1@--keep-inline-images@2@option@2@ Prevent inline images from being included in image optimization. This option has no affect when - is not specified. + @1@option@1@--optimize-images@2@option@2@ is not specified. - + @1@option@1@--remove-page-labels@2@option@2@ Remove page labels from the output file. @@ -2577,21 +2577,21 @@ outfile.pdf - + @1@option@1@--qdf@2@option@2@ Turns on QDF mode. For additional information on QDF, please see . Note that - disables QDF mode. + @1@option@1@--linearize@2@option@2@ disables QDF mode. - + @1@option@1@--min-version=@1@replaceable@1@version@2@replaceable@2@@2@option@2@ Forces the PDF version of the output file to be at least - version. In other words, if the + @1@replaceable@1@version@2@replaceable@2@. In other words, if the input file has a lower version than the specified version, the specified version will be used. If the input file has a higher version, the input file's original version will be @@ -2601,10 +2601,10 @@ outfile.pdf The version number may be expressed in the form - major.minor.extension-level, in + @1@replaceable@1@major.minor.extension-level@2@replaceable@2@, in which case the version is interpreted as - major.minor at extension level - extension-level. For example, + @1@replaceable@1@major.minor@2@replaceable@2@ at extension level + @1@replaceable@1@extension-level@2@replaceable@2@. For example, version 1.7.8 represents version 1.7 at extension level 8. Note that minimal syntax checking is done on the command line. @@ -2612,14 +2612,14 @@ outfile.pdf - + @1@option@1@--force-version=@1@replaceable@1@version@2@replaceable@2@@2@option@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 - so that extension levels can be + @1@option@1@--min-version@2@option@2@ 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, @@ -2653,10 +2653,10 @@ outfile.pdf 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 . + requested with @1@option@1@--stream-data=compress@2@option@2@. - When is specified, qpdf + When @1@option@1@--normalize-content=y@2@option@2@ 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 @@ -2673,10 +2673,10 @@ outfile.pdf 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 for a QDF file without content + uncompressed format, you can always run with @1@option@1@--qdf + --normalize-content=n@2@option@2@ for a QDF file without content normalization, or alternatively - for a regular non-QDF + @1@option@1@--stream-data=uncompress@2@option@2@ 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 @@ -2690,25 +2690,25 @@ outfile.pdf 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: - , , and - . + @1@option@1@preserve@2@option@2@, @1@option@1@disable@2@option@2@, and + @1@option@1@generate@2@option@2@. - In mode, the relationship to objects and + In @1@option@1@preserve@2@option@2@ mode, the relationship to objects and the streams that contain them is preserved from the original file. - In mode, all objects are written as + In @1@option@1@disable@2@option@2@ 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 - mode, qpdf will create its own object + @1@option@1@generate@2@option@2@ 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 flag turns on QDF mode, which changes + The @1@option@1@--qdf@2@option@2@ 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 @@ -2717,7 +2717,7 @@ outfile.pdf indirect objects, objects are laid out in a less efficient but more readable fashion, and the documents are interspersed with comments that make it easier for the user to find things and also - make it possible for fix-qdf to work properly. + make it possible for @1@command@1@fix-qdf@2@command@2@ to work properly. QDF mode is intended for people, mostly developers, who wish to inspect or modify PDF files in a text editor. For details, please see . @@ -2732,7 +2732,7 @@ outfile.pdf file should be given. The following options are available: - + @1@option@1@--deterministic-id@2@option@2@ Causes generation of a deterministic value for /ID. This @@ -2748,19 +2748,19 @@ outfile.pdf - + @1@option@1@--static-id@2@option@2@ 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 - option. + @1@option@1@--deterministic-id@2@option@2@ option. - + @1@option@1@--static-aes-iv@2@option@2@ Causes use of a static initialization vector for AES-CBC. @@ -2772,7 +2772,7 @@ outfile.pdf - + @1@option@1@--no-original-object-ids@2@option@2@ Suppresses inclusion of original object ID comments in QDF @@ -2783,7 +2783,7 @@ outfile.pdf - + @1@option@1@--show-encryption@2@option@2@ Shows document encryption parameters. Also shows the @@ -2792,16 +2792,16 @@ outfile.pdf - + @1@option@1@--show-encryption-key@2@option@2@ When encryption information is being displayed, as when - or + @1@option@1@--check@2@option@2@ or @1@option@1@--show-encryption@2@option@2@ 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 - if the - is specified. Note + @1@option@1@--password@2@option@2@ if the + @1@option@1@--password-is-hex-key@2@option@2@ 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 @@ -2810,7 +2810,7 @@ outfile.pdf - + @1@option@1@--check-linearization@2@option@2@ Checks file integrity and linearization status. @@ -2818,7 +2818,7 @@ outfile.pdf - + @1@option@1@--show-linearization@2@option@2@ Checks and displays all data in the linearization hint tables. @@ -2826,7 +2826,7 @@ outfile.pdf - + @1@option@1@--show-xref@2@option@2@ Shows the contents of the cross-reference table in a @@ -2836,7 +2836,7 @@ outfile.pdf - + @1@option@1@--show-object=trailer|obj[,gen]@2@option@2@ Show the contents of the given object. This is especially @@ -2846,20 +2846,20 @@ outfile.pdf - + @1@option@1@--raw-stream-data@2@option@2@ - When used along with the + When used along with the @1@option@1@--show-object@2@option@2@ 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 + When used along with the @1@option@1@--show-object@2@option@2@ 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 @@ -2868,7 +2868,7 @@ outfile.pdf - + @1@option@1@--show-npages@2@option@2@ Prints the number of pages in the input file on a line by @@ -2879,7 +2879,7 @@ outfile.pdf - + @1@option@1@--show-pages@2@option@2@ Shows the object and generation number for each page @@ -2890,10 +2890,10 @@ outfile.pdf - + @1@option@1@--with-images@2@option@2@ - When used along with , also shows + When used along with @1@option@1@--show-pages@2@option@2@, 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 @@ -2902,7 +2902,7 @@ outfile.pdf - + @1@option@1@--json@2@option@2@ Generate a JSON representation of the file. This is described @@ -2911,7 +2911,7 @@ outfile.pdf - + @1@option@1@--json-help@2@option@2@ Describe the format of the JSON output. @@ -2919,7 +2919,7 @@ outfile.pdf - + @1@option@1@--json-key=key@2@option@2@ This option is repeatable. If specified, only top-level keys @@ -2929,7 +2929,7 @@ outfile.pdf - + @1@option@1@--json-object=trailer|obj[,gen]@2@option@2@ This option is repeatable. If specified, only specified @@ -2940,30 +2940,30 @@ outfile.pdf - + @1@option@1@--check@2@option@2@ Checks file structure and well as encryption, linearization, and encoding of stream data. A file for which - reports no errors may still have + @1@option@1@--check@2@option@2@ reports no errors may still have errors in stream data content but should otherwise be - structurally sound. If any errors, + structurally sound. If @1@option@1@--check@2@option@2@ any errors, qpdf will exit with a status of 2. There are some recoverable - conditions that detects. These are + conditions that @1@option@1@--check@2@option@2@ 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 is combined + version 2.0.4). When @1@option@1@--check@2@option@2@ is combined with other options, checks are always performed before any other options are processed. For erroneous files, - will cause qpdf to attempt to + @1@option@1@--check@2@option@2@ will cause qpdf to attempt to recover, after which other options are effectively operating - on the recovered file. Combining with + on the recovered file. Combining @1@option@1@--check@2@option@2@ with other options in this way can be useful for manually recovering severely damaged files. Note that - produces no output to standard output + @1@option@1@--check@2@option@2@ 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 /dev/null + without output redirected to @1@filename@1@/dev/null@2@filename@2@ and just check for a 0 exit code. @@ -2971,17 +2971,17 @@ outfile.pdf - The and - options are ignored unless - is given. Either of these options + 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 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 is given and - is also given, qpdf will + 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 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. @@ -3029,7 +3029,7 @@ outfile.pdf the supplied password is not a valid UTF-8 string, qpdf will fall back to the behavior of interpreting the password as a string of bytes. If you have old scripts that encrypt files by passing the - output of iconv to qpdf, you no longer need to + output of @1@command@1@iconv@2@command@2@ to qpdf, you no longer need to do that, but if you do, qpdf should still work. The only exception would be for the extremely unlikely case of a password that is encoded with a single-byte encoding but also happens to be valid @@ -3037,24 +3037,24 @@ outfile.pdf 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 to suppress + you can use @1@option@1@--password-mode=bytes@2@option@2@ to suppress qpdf's automatic behavior. - The option, as described earlier + The @1@option@1@--password-mode@2@option@2@ 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 - . Another reason to use - would be to intentionally + @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 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 password mode can + similar purposes, the @1@option@1@bytes@2@option@2@ password mode can enable you to do this. @@ -3064,7 +3064,7 @@ outfile.pdf handful of different coding systems and then transcode them to the required format. This helps to compensate for the supplied password being given in the wrong coding system, such as would - happen if you used the iconv workaround that + happen if you used the @1@command@1@iconv@2@command@2@ workaround that was previously needed. It also generates passwords by doing the reverse operation: translating from correct in incorrect encoding of the password. This would enable qpdf to decrypt files using @@ -3075,7 +3075,7 @@ outfile.pdf 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 - option. One reason + @1@option@1@--suppress-password-recovery@2@option@2@ option. One reason to do that is to ensure that you know the exact password that was used to encrypt the file. @@ -3094,7 +3094,7 @@ outfile.pdf bytes. - Please note that the option + Please note that the @1@option@1@--password-is-hex-key@2@option@2@ 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 @@ -3106,8 +3106,8 @@ outfile.pdf QDF Mode - In QDF mode, qpdf creates PDF files in what we call QDF - form. A PDF file in QDF form, sometimes called a QDF + In QDF mode, qpdf creates PDF files in what we call @1@firstterm@1@QDF + form@2@firstterm@2@. A PDF file in QDF form, sometimes called a QDF file, is a completely valid PDF file that has %QDF-1.0 as its third line (after the pdf header and binary characters) and has certain other characteristics. The @@ -3125,9 +3125,9 @@ outfile.pdf and PDF files are full of offset and length information that makes it hard to add or remove data. A QDF file is organized in a manner such that, if edits are kept within certain constraints, the - fix-qdf program, distributed with qpdf, is able + @1@command@1@fix-qdf@2@command@2@ program, distributed with qpdf, is able to restore edited files to a correct state. The - fix-qdf program takes no command-line + @1@command@1@fix-qdf@2@command@2@ program takes no command-line arguments. It reads a possibly edited QDF file from standard input and writes a repaired file to standard output. @@ -3218,11 +3218,11 @@ outfile.pdf It is not generally practical to remove objects from QDF files without messing up object numbering, but if you remove all references to an object, you can run qpdf on the file (after - running fix-qdf), and qpdf will omit the + running @1@command@1@fix-qdf@2@command@2@), and qpdf will omit the now-orphaned object. - When fix-qdf is run, it goes through the file + When @1@command@1@fix-qdf@2@command@2@ is run, it goes through the file and recomputes the following parts of the file: @@ -3262,26 +3262,26 @@ outfile.pdf Using QPDF from C++ The source tree for the qpdf package has an - examples directory that contains a few - example programs. The qpdf/qpdf.cc source + @1@filename@1@examples@2@filename@2@ directory that contains a few + example programs. The @1@filename@1@qpdf/qpdf.cc@2@filename@2@ source file also serves as a useful example since it exercises almost all of the qpdf library's public interface. The best source of documentation on the library itself is reading comments in - include/qpdf/QPDF.hh, - include/qpdf/QPDFWriter.hh, and - include/qpdf/QPDFObjectHandle.hh. + @1@filename@1@include/qpdf/QPDF.hh@2@filename@2@, + @1@filename@1@include/qpdf/QPDFWriter.hh@2@filename@2@, and + @1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@. - All header files are installed in the include/qpdf directory. It + All header files are installed in the @1@filename@1@include/qpdf@2@filename@2@ directory. It is recommend that you use #include <qpdf/QPDF.hh> rather than adding - include/qpdf to your include path. + @1@filename@1@include/qpdf@2@filename@2@ to your include path. When linking against the qpdf static library, you may also need to specify -lz -ljpeg on your link command. If your system understands how to read libtool - .la files, this may not be necessary. + @1@filename@1@.la@2@filename@2@ files, this may not be necessary. The qpdf library is safe to use in a multithreaded program, but no @@ -3305,7 +3305,7 @@ outfile.pdf The qpdf library includes a “C” language interface that provides a subset of the overall capabilities. The header - file qpdf/qpdf-c.h includes information + file @1@filename@1@qpdf/qpdf-c.h@2@filename@2@ includes information about its use. As long as you use a C++ linker, you can link C programs with qpdf and use the C API. For languages that can directly load methods from a shared library, the C API can also @@ -3333,7 +3333,7 @@ outfile.pdf Other Languages - Starting with version 8.3.0, the qpdf + Starting with version 8.3.0, the @1@command@1@qpdf@2@command@2@ command-line tool can produce a JSON representation of the PDF file's non-content data. This can facilitate interacting programmatically with PDF files through qpdf's command line @@ -3384,13 +3384,13 @@ outfile.pdf 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 - option. + @1@option@1@--allow-weak-crypto@2@option@2@ 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 - flag and also to require + @1@option@1@--allow-weak-crypto@2@option@2@ flag and also to require explicit steps when using the C++ library to enable use of insecure cryptography. @@ -3412,7 +3412,7 @@ outfile.pdf Overview - Beginning with qpdf version 8.3.0, the qpdf + Beginning with qpdf version 8.3.0, the @1@command@1@qpdf@2@command@2@ command-line program can produce a JSON representation of the non-content data in a PDF file. It includes a dump in JSON format of all objects in the PDF file excluding the content of streams. @@ -3466,8 +3466,8 @@ outfile.pdf Documentation - The qpdf command can be invoked with the - option. This will output a JSON + The @1@command@1@qpdf@2@command@2@ command can be invoked with the + @1@option@1@--json-help@2@option@2@ 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 @@ -3585,7 +3585,7 @@ outfile.pdf 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 - option does not have this + @1@option@1@--show-object@2@option@2@ option does not have this limitation and will reveal the string as encoded in the original file. @@ -3605,9 +3605,9 @@ outfile.pdf 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 , the keys that are not + specify @1@option@1@--json-keys@2@option@2@, the keys that are not listed will be excluded entirely except for those that - says are always present. + @1@option@1@--json-help@2@option@2@ says are always present. @@ -3633,13 +3633,13 @@ outfile.pdf section of the JSON output includes the key “filterable”. Note that the value of this field may depend on the - that you invoke qpdf with. The + @1@option@1@--decode-level@2@option@2@ 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 shown as not filterable by default, but they will be shown as filterable if - you run qpdf --json --decode-level=all. + you run @1@command@1@qpdf --json --decode-level=all@2@command@2@. @@ -3748,7 +3748,7 @@ outfile.pdf object from a string representation of the object. Existing instances of QPDFObjectHandle can also be modified in several ways. See comments in - QPDFObjectHandle.hh for details. + @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for details. An instance of QPDF is constructed by using @@ -3785,8 +3785,8 @@ outfile.pdf There are some convenience routines for very common operations such as walking the page tree and returning a vector of all page objects. For full details, please see the header files - QPDF.hh and - QPDFObjectHandle.hh. There are also some + @1@filename@1@QPDF.hh@2@filename@2@ and + @1@filename@1@QPDFObjectHandle.hh@2@filename@2@. There are also some additional helper classes that provide higher level API functions for certain document constructions. These are discussed in . @@ -3868,8 +3868,8 @@ outfile.pdf are derived from QPDFObjectHelper. For details on specific helpers, please see their header files. You can find them by looking at - include/qpdf/QPDF*DocumentHelper.hh and - include/qpdf/QPDF*ObjectHelper.hh. + @1@filename@1@include/qpdf/QPDF*DocumentHelper.hh@2@filename@2@ and + @1@filename@1@include/qpdf/QPDF*ObjectHelper.hh@2@filename@2@. In order to avoid creation of circular dependencies, the following @@ -3999,7 +3999,7 @@ outfile.pdf The QPDF class checks the beginning of - a.pdf for a PDF header. It then reads the + @1@filename@1@a.pdf@2@filename@2@ for a PDF header. It then reads the cross reference table mentioned at the end of the file, ensuring that it is looking before the last %%EOF. After getting to @@ -4107,7 +4107,7 @@ outfile.pdf The QIntC namespace, provided by - include/qpdf/QIntC.hh, implements safe + @1@filename@1@include/qpdf/QIntC.hh@2@filename@2@, implements safe functions for converting between integer types. These functions do range checking and throw a std::range_error, which is subclass of std::runtime_error, if conversion from one @@ -4263,7 +4263,7 @@ outfile.pdf dependency on Microsoft's cryptography API. You can also supply your own random data provider. For details on how to do this, please refer to the top-level README.md file in the source - distribution and to comments in QUtil.hh. + distribution and to comments in @1@filename@1@QUtil.hh@2@filename@2@. @@ -4276,7 +4276,7 @@ outfile.pdf /Pages tree down to individual pages and manipulation of the /Pages tree itself. For details, see addPage and surrounding methods - in QPDF.hh. + in @1@filename@1@QPDF.hh@2@filename@2@. @@ -4294,7 +4294,7 @@ outfile.pdf QPDF object prior to version 3.0 would be to add the new objects first and then make them refer to each other after adding them. Now it is possible to create a - reserved object using + @1@firstterm@1@reserved object@2@firstterm@2@ using QPDFObjectHandle::newReserved. This is an indirect object that stays “unresolved” even if it is queried for its type. So now, if you want to create a set of @@ -4307,7 +4307,7 @@ outfile.pdf when copying objects from other PDF files, as discussed in . For an example of how to use reserved objects, search for newReserved in - test_driver.cc in qpdf's sources. + @1@filename@1@test_driver.cc@2@filename@2@ in qpdf's sources. @@ -4316,10 +4316,10 @@ outfile.pdf Version 3.0 of qpdf introduced the ability to copy objects into a QPDF object from a different QPDF object, which we refer to as - foreign objects. This allows arbitrary + @1@firstterm@1@foreign objects@2@firstterm@2@. This allows arbitrary merging of PDF files. The “from” QPDF object must remain valid after the - copy as discussed in the note below. The qpdf + copy as discussed in the note below. The @1@command@1@qpdf@2@command@2@ command-line tool provides limited support for basic page selection, including merging in pages from other files, but the library's API makes it possible to implement arbitrarily complex @@ -4447,7 +4447,7 @@ outfile.pdf - Write n 0 obj. + Write @1@replaceable@1@n@2@replaceable@2@ 0 obj. @@ -4540,7 +4540,7 @@ outfile.pdf pipeline may be an end-of-the-line pipeline that does something like store its output to a file or a memory buffer ignoring a successor. For additional details, look at - Pipeline.hh. + @1@filename@1@Pipeline.hh@2@filename@2@. QPDF can read raw or filtered streams. @@ -4558,7 +4558,7 @@ outfile.pdf For general information about how to access instances of QPDFObjectHandle, please see the comments - in QPDFObjectHandle.hh. Search for + in @1@filename@1@QPDFObjectHandle.hh@2@filename@2@. Search for “Accessor methods”. This section provides a more in-depth discussion of the behavior and the rationale for the behavior. @@ -4655,9 +4655,9 @@ outfile.pdf To avoid the incestuous problem of having the qpdf library validate its own linearized files, we have a special linearized - file checking mode which can be invoked via qpdf - --check-linearization (or qpdf - --check). This mode reads the linearization parameter + file checking mode which can be invoked via @1@command@1@qpdf + --check-linearization@2@command@2@ (or @1@command@1@qpdf + --check@2@command@2@). This mode reads the linearization parameter dictionary and the hint streams and validates that object ordering, parameters, and hint stream contents are correct. The validation code was first tested against linearized files created @@ -4674,10 +4674,10 @@ outfile.pdf in the /Pages tree). We also have to know which objects refer to which other objects, being concerned with page boundaries and a few other cases. We refer to this part of - preparing the PDF file as optimization, + preparing the PDF file as @1@firstterm@1@optimization@2@firstterm@2@, discussed in . Note the, in - this context, the term optimization is a - qpdf term, and the term linearization is a + this context, the term @1@firstterm@1@optimization@2@firstterm@2@ is a + qpdf term, and the term @1@firstterm@1@linearization@2@firstterm@2@ is a term from the PDF specification. Do not be confused by the fact that many applications refer to linearization as optimization or web optimization. @@ -4716,14 +4716,14 @@ outfile.pdf We refer to the process of enforcing these constraints as - optimization. As mentioned above, note + @1@firstterm@1@optimization@2@firstterm@2@. As mentioned above, note that some applications refer to linearization as optimization. Although this optimization was initially motivated by the need to create linearized files, we are using these terms separately. PDF file optimization is implemented in the - QPDF_optimization.cc source file. That file + @1@filename@1@QPDF_optimization.cc@2@filename@2@ source file. That file is richly commented and serves as the primary reference for the optimization process. @@ -4857,11 +4857,11 @@ outfile.pdf Debugging Note - The qpdf --show-linearization command can show + The @1@command@1@qpdf --show-linearization@2@command@2@ command can show the complete contents of linearization hint streams. To look at the raw data, you can extract the filtered contents of the - linearization hint tables using qpdf --show-object=n - --filtered-stream-data. Then, to convert this into a + linearization hint tables using @1@command@1@qpdf --show-object=n + --filtered-stream-data@2@command@2@. Then, to convert this into a bit stream (since linearization tables are bit streams written without regard to byte boundaries), you can pipe the resulting data through the following perl code: @@ -5022,7 +5022,7 @@ print "\n"; /Index (optional): value - [n count ...] + [@1@replaceable@1@n count@2@replaceable@2@ ...] used to determine which objects' information is stored in this stream. The default is [0 /Size]. @@ -5030,7 +5030,7 @@ print "\n"; /Prev: value - offset: byte offset of previous xref + @1@replaceable@1@offset@2@replaceable@2@: byte offset of previous xref stream (same as /Prev in the trailer dictionary) @@ -5127,8 +5127,8 @@ print "\n"; Implementation Notes There are three modes for writing object streams: - , , and - . In disable mode, we do not generate + @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 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 @@ -5139,7 +5139,7 @@ print "\n"; 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 . + the other modes. The default is @1@option@1@preserve@2@option@2@. We do not support creation of hybrid files. When we write files, @@ -5152,7 +5152,7 @@ print "\n"; Release Notes For a detailed list of changes, please see the file - ChangeLog in the source distribution. + @1@filename@1@ChangeLog@2@filename@2@ in the source distribution.