octoleo/qpdf
2
1
Fork 0
mirror of https://github.com/qpdf/qpdf.git synced 2025-01-03 07:12:28 +00:00
Code Issues Releases Wiki Activity

Replace command|application with :command:...

Browse Source 
Replace @1@...@2@ stuff from prior to the conversion with new
representation.
This commit is contained in:
Jay Berkenbilt 2021-12-11 19:01:40 -05:00
parent cf3b9a7783
commit 15b87d769e
2 changed files with 141 additions and 142 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
TODO
View File

@ -36,7 +36,6 @@ Make sure the information from <book> is in there
<xref> -- find #ref. in converted rst <xref> -- find #ref. in converted rst
Correct placement of comment: <!-- This section is referenced in QPDFObjectHandle.hh --> Correct placement of comment: <!-- This section is referenced in QPDFObjectHandle.hh -->
<application>, <command> -> :command:
<filename> -> :file: (allows {x}) <filename> -> :file: (allows {x})
<option> -> :samp: (allows {x}) <option> -> :samp: (allows {x})
<firstterm> -> just use literal <firstterm> -> just use literal

282
manual/index.rst
View File

@ -116,7 +116,7 @@ the following packages are required:
- GNU diffutils (any version): http://www.gnu.org/software/diffutils/ - GNU diffutils (any version): http://www.gnu.org/software/diffutils/
is required to run the test suite. Note that this is the version of 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 diff present on virtually all GNU/Linux systems. This is required
because the test suite uses @1@command@1@diff -u@2@command@2@. because the test suite uses :command:`diff -u`.
Part of qpdf's test suite does comparisons of the contents PDF files by Part of qpdf's test suite does comparisons of the contents PDF files by
converting them images and comparing the images. The image comparison converting them images and comparing the images. The image comparison
@ -130,7 +130,7 @@ off by default and are only provided to help developers look into the
contents of PDF files. If you are making deep changes to the library 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, that cause changes in the contents of the files that qpdf generates,
then you should enable the image comparison tests. Enable them by then you should enable the image comparison tests. Enable them by
running @1@command@1@configure@2@command@2@ with the running :command:`configure` with the
@1@option@1@--enable-test-compare-images@2@option@2@ flag. If you enable @1@option@1@--enable-test-compare-images@2@option@2@ flag. If you enable
this, the following additional requirements are required by the test this, the following additional requirements are required by the test
suite. Note that in no case are these items required to use qpdf. suite. Note that in no case are these items required to use qpdf.
@ -161,9 +161,9 @@ Building qpdf on UNIX is generally just a matter of running
./configure ./configure
make make
You can also run @1@command@1@make check@2@command@2@ to run the test You can also run :command:`make check` to run the test
suite and @1@command@1@make install@2@command@2@ to install. Please run suite and :command:`make install` to install. Please run
@1@command@1@./configure --help@2@command@2@ for options on what can be :command:`./configure --help` for options on what can be
configured. You can also set the value of ``DESTDIR`` during configured. You can also set the value of ``DESTDIR`` during
installation to install to a temporary location, as is common with many installation to install to a temporary location, as is common with many
open source packages. Please see also the open source packages. Please see also the
@ -187,8 +187,8 @@ very unusual situation. For a detailed discussion, please see the
top-level README.md file in qpdf's source distribution. top-level README.md file in qpdf's source distribution.
There are some other things you can do with the build. Although qpdf There are some other things you can do with the build. Although qpdf
uses @1@application@1@autoconf@2@application@2@, it does not use uses :command:`autoconf`, it does not use
@1@application@1@automake@2@application@2@ but instead uses a :command:`automake` but instead uses a
hand-crafted non-recursive Makefile that requires gnu make. If you're hand-crafted non-recursive Makefile that requires gnu make. If you're
really interested, please read the comments in the top-level really interested, please read the comments in the top-level
@1@filename@1@Makefile@2@filename@2@. @1@filename@1@Makefile@2@filename@2@.
@ -218,13 +218,13 @@ Build Support For Crypto Providers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When building with qpdf's build system, crypto providers can be enabled When building with qpdf's build system, crypto providers can be enabled
at build time using various @1@command@1@./configure@2@command@2@ at build time using various :command:`./configure`
options. The default behavior is for options. The default behavior is for
@1@command@1@./configure@2@command@2@ to discover which crypto providers :command:`./configure` to discover which crypto providers
can be supported based on available external libraries, to build all can be supported based on available external libraries, to build all
available crypto providers, and to use an external provider as the available crypto providers, and to use an external provider as the
default over the native one. This behavior can be changed with the default over the native one. This behavior can be changed with the
following flags to @1@command@1@./configure@2@command@2@: following flags to :command:`./configure`:
- @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@ - @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 (where @1@replaceable@1@x@2@replaceable@2@ is a supported crypto
@ -246,8 +246,8 @@ following flags to @1@command@1@./configure@2@command@2@:
For example, if you want to guarantee that the gnutls crypto provider is 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 used and that the native provider is not built, you could run
@1@command@1@./configure --enable-crypto-gnutls :command:`./configure --enable-crypto-gnutls
--disable-implicit-crypto@2@command@2@. --disable-implicit-crypto`.
If you build qpdf using your own build system, in order for qpdf to work 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 at all, you need to enable at least one crypto provider. The file
@ -279,7 +279,7 @@ Runtime Crypto Provider Selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use the @1@option@1@--show-crypto@2@option@2@ option to 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 :command:`qpdf` to get a list of available crypto
providers. The default provider is always listed first, and the rest are 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 listed in lexical order. Each crypto provider is listed on a line by
itself with no other text, enabling the output of this command to be itself with no other text, enabling the output of this command to be
@ -396,7 +396,7 @@ some things you may want to keep in mind:
Providers <#ref.crypto.build>`__ for details. Providers <#ref.crypto.build>`__ for details.
- Passing @1@option@1@--enable-show-failed-test-output@2@option@2@ to - 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 :command:`./configure` will cause any failed test
output to be written to the console. This can be very useful for output to be written to the console. This can be very useful for
seeing test failures generated by autobuilders where you can't access seeing test failures generated by autobuilders where you can't access
qtest.log after the fact. qtest.log after the fact.
@ -409,11 +409,11 @@ some things you may want to keep in mind:
their sources. If your packaging environment automatically refreshes their sources. If your packaging environment automatically refreshes
automatic files, it can cause this check to fail. Suppress qpdf's automatic files, it can cause this check to fail. Suppress qpdf's
checks by passing @1@option@1@--disable-check-autofiles@2@option@2@ checks by passing @1@option@1@--disable-check-autofiles@2@option@2@
to @1@command@1@/.configure@2@command@2@. This is safe since qpdf's to :command:`/.configure`. This is safe since qpdf's
@1@command@1@autogen.sh@2@command@2@ just runs autotools in the :command:`autogen.sh` just runs autotools in the
normal way. normal way.
- QPDF's @1@command@1@make install@2@command@2@ does not install - QPDF's :command:`make install` does not install
completion files by default, but as a packager, it's good if you completion files by default, but as a packager, it's good if you
install them wherever your distribution expects such files to go. You install them wherever your distribution expects such files to go. You
can find completion files to install in the can find completion files to install in the
@ -440,7 +440,7 @@ When running qpdf, the basic invocation is as follows:
:: ::
@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@ :command:`qpdf`@1@option@1@ [ @1@replaceable@1@options@2@replaceable@2@ ] { @1@replaceable@1@infilename@2@replaceable@2@ | @1@option@1@--empty@2@option@2@ } [ @1@replaceable@1@page_selection_options@2@replaceable@2@ ] @1@replaceable@1@outfilename@2@replaceable@2@@2@option@2@
This converts PDF file @1@option@1@infilename@2@option@2@ to PDF file 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 @1@option@1@outfilename@2@option@2@. The output file is functionally
@ -484,7 +484,7 @@ commands do not. These are specifically noted.
Exit Status Exit Status
~~~~~~~~~~~ ~~~~~~~~~~~
The exit status of @1@command@1@qpdf@2@command@2@ may be interpreted as The exit status of :command:`qpdf` may be interpreted as
follows: follows:
- ``0``: no errors or warnings were found. The file may still have - ``0``: no errors or warnings were found. The file may still have
@ -502,9 +502,9 @@ follows:
@1@option@1@--warning-exit-0@2@option@2@, warnings without errors @1@option@1@--warning-exit-0@2@option@2@, warnings without errors
exit with status 0 instead of 3. exit with status 0 instead of 3.
Note that @1@command@1@qpdf@2@command@2@ never exists with status ``1``. Note that :command:`qpdf` never exists with status ``1``.
If you get an exit status of ``1``, it was something else, like the If you get an exit status of ``1``, it was something else, like the
shell not being able to find or execute @1@command@1@qpdf@2@command@2@. shell not being able to find or execute :command:`qpdf`.
.. _ref.shell-completion: .. _ref.shell-completion:
@ -512,10 +512,10 @@ Shell Completion
---------------- ----------------
Starting in qpdf version 8.3.0, qpdf provides its own completion support Starting in qpdf version 8.3.0, qpdf provides its own completion support
for zsh and bash. You can enable bash completion with @1@command@1@eval for zsh and bash. You can enable bash completion with :command:`eval
$(qpdf --completion-bash)@2@command@2@ and zsh completion with $(qpdf --completion-bash)` and zsh completion with
@1@command@1@eval $(qpdf --completion-zsh)@2@command@2@. If :command:`eval $(qpdf --completion-zsh)`. If
@1@command@1@qpdf@2@command@2@ is not in your path, you should invoke it :command:`qpdf` is not in your path, you should invoke it
above with an absolute path. If you invoke it with a relative path, 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 will warn you, and the completion won't work if you're in a different
directory. directory.
@ -610,13 +610,13 @@ needed transformations.
@1@option@1@--no-warn@2@option@2@ @1@option@1@--no-warn@2@option@2@
Suppress writing of warnings to stderr. If warnings were detected and Suppress writing of warnings to stderr. If warnings were detected and
suppressed, @1@command@1@qpdf@2@command@2@ will still exit with exit suppressed, :command:`qpdf` will still exit with exit
code 3. See also @1@option@1@--warning-exit-0@2@option@2@. code 3. See also @1@option@1@--warning-exit-0@2@option@2@.
@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. If warnings are found but no errors, exit with exit code 0 instead 3.
When combined with @1@option@1@--no-warn@2@option@2@, the effect is When combined with @1@option@1@--no-warn@2@option@2@, the effect is
for @1@command@1@qpdf@2@command@2@ to completely ignore warnings. for :command:`qpdf` to completely ignore warnings.
@1@option@1@--linearize@2@option@2@ @1@option@1@--linearize@2@option@2@
Causes generation of a linearized (web-optimized) output file. Causes generation of a linearized (web-optimized) output file.
@ -749,12 +749,12 @@ needed transformations.
original rotations. This is almost always what you want. Otherwise original rotations. This is almost always what you want. Otherwise
the pages' rotations are set to the exact value, which may cause the the pages' rotations are set to the exact value, which may cause the
appearances of the pages to be inconsistent, especially for scans. appearances of the pages to be inconsistent, especially for scans.
For example, the command @1@command@1@qpdf in.pdf out.pdf For example, the command :command:`qpdf in.pdf out.pdf
--rotate=+90:2,4,6 --rotate=180:7-8@2@command@2@ would rotate pages --rotate=+90:2,4,6 --rotate=180:7-8` would rotate pages
2, 4, and 6 90 degrees clockwise from their original rotation and 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 force the rotation of pages 7 through 8 to 180 degrees regardless of
their original rotation, and the command @1@command@1@qpdf in.pdf their original rotation, and the command :command:`qpdf in.pdf
out.pdf --rotate=+180@2@command@2@ would rotate all pages by 180 out.pdf --rotate=+180` would rotate all pages by 180
degrees. degrees.
@1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@ @1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@
@ -826,17 +826,17 @@ needed transformations.
two numbers separated by a dash otherwise. For example, if two numbers separated by a dash otherwise. For example, if
@1@filename@1@infile.pdf@2@filename@2@ has 12 pages @1@filename@1@infile.pdf@2@filename@2@ has 12 pages
- @1@command@1@qpdf --split-pages infile.pdf %d-out@2@command@2@ - :command:`qpdf --split-pages infile.pdf %d-out`
would generate files @1@filename@1@01-out@2@filename@2@ through would generate files @1@filename@1@01-out@2@filename@2@ through
@1@filename@1@12-out@2@filename@2@ @1@filename@1@12-out@2@filename@2@
- @1@command@1@qpdf --split-pages=2 infile.pdf - :command:`qpdf --split-pages=2 infile.pdf
outfile.pdf@2@command@2@ would generate files outfile.pdf` would generate files
@1@filename@1@outfile-01-02.pdf@2@filename@2@ through @1@filename@1@outfile-01-02.pdf@2@filename@2@ through
@1@filename@1@outfile-11-12.pdf@2@filename@2@ @1@filename@1@outfile-11-12.pdf@2@filename@2@
- @1@command@1@qpdf --split-pages infile.pdf - :command:`qpdf --split-pages infile.pdf
something.else@2@command@2@ would generate files something.else` would generate files
@1@filename@1@something.else-01@2@filename@2@ through @1@filename@1@something.else-01@2@filename@2@ through
@1@filename@1@something.else-12@2@filename@2@ @1@filename@1@something.else-12@2@filename@2@
@ -844,7 +844,7 @@ needed transformations.
original PDF file are not preserved. For each page of output, this 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 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 into it. If you require the global data, you will have to run
@1@command@1@qpdf@2@command@2@ with the :command:`qpdf` with the
@1@option@1@--pages@2@option@2@ option once for each file. Using @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 @1@option@1@--split-pages@2@option@2@ is much faster if you don't
require the global data. require the global data.
@ -878,7 +878,7 @@ properly encoded encryption and decryption passwords to the user.
Starting in qpdf 8.4.0, qpdf does this automatically in most cases. For Starting in qpdf 8.4.0, qpdf does this automatically in most cases. For
an in-depth discussion, please see `Unicode an in-depth discussion, please see `Unicode
Passwords <#ref.unicode-passwords>`__. Previous versions of this manual Passwords <#ref.unicode-passwords>`__. Previous versions of this manual
described workarounds using the @1@command@1@iconv@2@command@2@ command. described workarounds using the :command:`iconv` command.
Such workarounds are no longer required or recommended with qpdf 8.4.0. Such workarounds are no longer required or recommended with qpdf 8.4.0.
However, for backward compatibility, qpdf attempts to detect those However, for backward compatibility, qpdf attempts to detect those
workarounds and do the right thing in most cases. workarounds and do the right thing in most cases.
@ -1084,8 +1084,8 @@ sees a value in the place where it expects a page range and that value
is not a valid range but is a valid file name, qpdf will implicitly use is not a valid range but is a valid file name, qpdf will implicitly use
the range ``1-z``, meaning that it will include all pages in the file. 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 This makes it possible to easily combine all pages in a set of files
with a command like @1@command@1@qpdf --empty out.pdf --pages \*.pdf with a command like :command:`qpdf --empty out.pdf --pages \*.pdf
--@2@command@2@. --`.
The page range is a set of numbers separated by commas, ranges of The page range is a set of numbers separated by commas, ranges of
numbers separated dashes, or combinations of those. The character "z" numbers separated dashes, or combinations of those. The character "z"
@ -1124,14 +1124,14 @@ of @1@option@1@--pages@2@option@2@ so that the specified files, as
modified by page ranges, are collated rather than concatenated. For modified by page ranges, are collated rather than concatenated. For
example, if you add the files @1@filename@1@odd.pdf@2@filename@2@ and 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 @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 document respectively, you could run :command:`qpdf --collate odd.pdf
--pages odd.pdf even.pdf -- all.pdf@2@command@2@ to collate the pages. --pages odd.pdf even.pdf -- all.pdf` to collate the pages.
This would pick page 1 from odd, page 1 from even, page 2 from odd, page 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 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, 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 that file is just skipped when its pages have all been included. For
example, if you ran @1@command@1@qpdf --collate --empty --pages a.pdf example, if you ran :command:`qpdf --collate --empty --pages a.pdf
1-5 b.pdf 6-4 c.pdf r1 -- out.pdf@2@command@2@, you would get the 1-5 b.pdf 6-4 c.pdf r1 -- out.pdf`, you would get the
following pages in this order: following pages in this order:
- a.pdf page 1 - a.pdf page 1
@ -1157,8 +1157,8 @@ Starting in qpdf version 10.2, you may specify a numeric argument to
@1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@, @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, 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 again, stopping when there are no more pages. For example, if you ran
@1@command@1@qpdf --collate=2 --empty --pages a.pdf 1-5 b.pdf 6-4 c.pdf :command:`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 r1 -- out.pdf`, you would get the following pages in this
order: order:
- a.pdf page 1 - a.pdf page 1
@ -1187,7 +1187,7 @@ features. For example, the document's outlines (bookmarks) point to
actual page objects, so if you select some pages and not others, 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 bookmarks that point to pages that are in the output file will work, and
remaining bookmarks will not work. A future version of remaining bookmarks will not work. A future version of
@1@command@1@qpdf@2@command@2@ may do a better job at handling these :command:`qpdf` may do a better job at handling these
issues. (Note that the qpdf library already contains all of the APIs 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 required in order to implement this in your own application if you need
it.) In the mean time, you can always use it.) In the mean time, you can always use
@ -1198,7 +1198,7 @@ all metadata associated with that file, you could use
:: ::
@1@command@1@qpdf@2@command@2@ @1@option@1@infile.pdf --pages . 1-5 -- outfile.pdf@2@option@2@ :command:`qpdf` @1@option@1@infile.pdf --pages . 1-5 -- outfile.pdf@2@option@2@
If you wanted pages 1 through 5 from If you wanted pages 1 through 5 from
@1@filename@1@infile.pdf@2@filename@2@ but you wanted the rest of the @1@filename@1@infile.pdf@2@filename@2@ but you wanted the rest of the
@ -1206,7 +1206,7 @@ metadata to be dropped, you could instead run
:: ::
@1@command@1@qpdf@2@command@2@ @1@option@1@--empty --pages infile.pdf 1-5 -- outfile.pdf@2@option@2@ :command:`qpdf` @1@option@1@--empty --pages infile.pdf 1-5 -- outfile.pdf@2@option@2@
If you wanted to take pages 1 through 5 from If you wanted to take pages 1 through 5 from
@1@filename@1@file1.pdf@2@filename@2@ and pages 11 through 15 from @1@filename@1@file1.pdf@2@filename@2@ and pages 11 through 15 from
@ -1215,7 +1215,7 @@ metadata from @1@filename@1@file2.pdf@2@filename@2@, you would run
:: ::
@1@command@1@qpdf@2@command@2@ @1@option@1@file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf@2@option@2@ :command:`qpdf` @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 If, for some reason, you wanted to take the first page of an encrypted
file called @1@filename@1@encrypted.pdf@2@filename@2@ with password file called @1@filename@1@encrypted.pdf@2@filename@2@ with password
@ -1224,7 +1224,7 @@ drop document-level metadata but preserve encryption, you would use
:: ::
@1@command@1@qpdf@2@command@2@ @1@option@1@--empty --copy-encryption=encrypted.pdf --encryption-file-password=pass :command:`qpdf` @1@option@1@--empty --copy-encryption=encrypted.pdf --encryption-file-password=pass
--pages encrypted.pdf --password=pass 1 ./encrypted.pdf --password=pass 1 -- --pages encrypted.pdf --password=pass 1 ./encrypted.pdf --password=pass 1 --
outfile.pdf@2@option@2@ outfile.pdf@2@option@2@
@ -1244,7 +1244,7 @@ the same page from the same file more than once, qpdf will share objects
between the pages. If you are going to do further manipulation on the between the pages. If you are going to do further manipulation on the
file and need the two instances of the same original page to be deep 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 copies, then you can specify the file in two different ways. For example
@1@command@1@qpdf in.pdf --pages . 1 ./in.pdf 1 -- out.pdf@2@command@2@ :command:`qpdf in.pdf --pages . 1 ./in.pdf 1 -- out.pdf`
would create a file with two copies of the first page of the input, and 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, the two copies would share any objects in common. This includes fonts,
images, and anything else the page references. images, and anything else the page references.
@ -1302,15 +1302,15 @@ between the @1@option@1@--overlay@2@option@2@ or
Here are some examples. Here are some examples.
- @1@command@1@--overlay o.pdf --to=1-5 --from=1-3 --repeat=4 - :command:`--overlay o.pdf --to=1-5 --from=1-3 --repeat=4
--@2@command@2@: overlay the first three pages from file --`: overlay the first three pages from file
@1@filename@1@o.pdf@2@filename@2@ onto the first three pages of the @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@ 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 onto pages 4 and 5 of the output. Leave remaining output pages
untouched. untouched.
- @1@command@1@--underlay footer.pdf --from= --repeat=1,2 - :command:`--underlay footer.pdf --from= --repeat=1,2
--@2@command@2@: Underlay page 1 of --`: Underlay page 1 of
@1@filename@1@footer.pdf@2@filename@2@ on all odd output pages, and @1@filename@1@footer.pdf@2@filename@2@ on all odd output pages, and
underlay page 2 of @1@filename@1@footer.pdf@2@filename@2@ on all even underlay page 2 of @1@filename@1@footer.pdf@2@filename@2@ on all even
output pages. output pages.
@ -1374,7 +1374,7 @@ from the command line. The following options are available:
@1@option@1@--replace@2@option@2@ @1@option@1@--replace@2@option@2@
Indicates that any existing attachment with the same key should be Indicates that any existing attachment with the same key should be
replaced by the new attachment. Otherwise, replaced by the new attachment. Otherwise,
@1@command@1@qpdf@2@command@2@ gives an error if an attachment :command:`qpdf` gives an error if an attachment
with that key is already present. with that key is already present.
@1@option@1@--remove-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@ @1@option@1@--remove-attachment=@1@replaceable@1@key@2@replaceable@2@@2@option@2@
@ -1848,7 +1848,7 @@ QDF mode, stream lengths are stored as indirect objects, objects are
laid out in a less efficient but more readable fashion, and the laid out in a less efficient but more readable fashion, and the
documents are interspersed with comments that make it easier for the documents are interspersed with comments that make it easier for the
user to find things and also make it possible for user to find things and also make it possible for
@1@command@1@fix-qdf@2@command@2@ to work properly. QDF mode is intended :command:`fix-qdf` to work properly. QDF mode is intended
for people, mostly developers, who wish to inspect or modify PDF files for people, mostly developers, who wish to inspect or modify PDF files
in a text editor. For details, please see `QDF Mode <#ref.qdf>`__. in a text editor. For details, please see `QDF Mode <#ref.qdf>`__.
@ -2047,7 +2047,7 @@ If a file is being encrypted with 40-bit or 128-bit encryption and the
supplied password is not a valid UTF-8 string, qpdf will fall back to 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 the behavior of interpreting the password as a string of bytes. If you
have old scripts that encrypt files by passing the output of have old scripts that encrypt files by passing the output of
@1@command@1@iconv@2@command@2@ to qpdf, you no longer need to do that, :command:`iconv` to qpdf, you no longer need to do that,
but if you do, qpdf should still work. The only exception would be for 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 the extremely unlikely case of a password that is encoded with a
single-byte encoding but also happens to be valid UTF-8. Such a password single-byte encoding but also happens to be valid UTF-8. Such a password
@ -2079,7 +2079,7 @@ by attempting to interpret the password as each of a handful of
different coding systems and then transcode them to the required format. different coding systems and then transcode them to the required format.
This helps to compensate for the supplied password being given in the This helps to compensate for the supplied password being given in the
wrong coding system, such as would happen if you used the wrong coding system, such as would happen if you used the
@1@command@1@iconv@2@command@2@ workaround that was previously needed. :command:`iconv` workaround that was previously needed.
It also generates passwords by doing the reverse operation: translating It also generates passwords by doing the reverse operation: translating
from correct in incorrect encoding of the password. This would enable from correct in incorrect encoding of the password. This would enable
qpdf to decrypt files using passwords that were improperly encoded by qpdf to decrypt files using passwords that were improperly encoded by
@ -2133,9 +2133,9 @@ two reasons: most meaningful data in PDF files is compressed, and PDF
files are full of offset and length information that makes it hard to 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 add or remove data. A QDF file is organized in a manner such that, if
edits are kept within certain constraints, the edits are kept within certain constraints, the
@1@command@1@fix-qdf@2@command@2@ program, distributed with qpdf, is :command:`fix-qdf` program, distributed with qpdf, is
able to restore edited files to a correct state. The able to restore edited files to a correct state. The
@1@command@1@fix-qdf@2@command@2@ program takes no command-line :command:`fix-qdf` program takes no command-line
arguments. It reads a possibly edited QDF file from standard input and arguments. It reads a possibly edited QDF file from standard input and
writes a repaired file to standard output. writes a repaired file to standard output.
@ -2189,10 +2189,10 @@ nothing generally ever references it by number.
It is not generally practical to remove objects from QDF files without It is not generally practical to remove objects from QDF files without
messing up object numbering, but if you remove all references to an messing up object numbering, but if you remove all references to an
object, you can run qpdf on the file (after running object, you can run qpdf on the file (after running
@1@command@1@fix-qdf@2@command@2@), and qpdf will omit the now-orphaned :command:`fix-qdf`), and qpdf will omit the now-orphaned
object. object.
When @1@command@1@fix-qdf@2@command@2@ is run, it goes through the file When :command:`fix-qdf` is run, it goes through the file
and recomputes the following parts of the file: and recomputes the following parts of the file:
- the ``/N``, ``/W``, and ``/First`` keys of all object stream - the ``/N``, ``/W``, and ``/First`` keys of all object stream
@ -2271,7 +2271,7 @@ Python
rich standard library and available modules. rich standard library and available modules.
Other Languages Other Languages
Starting with version 8.3.0, the @1@command@1@qpdf@2@command@2@ Starting with version 8.3.0, the :command:`qpdf`
command-line tool can produce a JSON representation of the PDF file's command-line tool can produce a JSON representation of the PDF file's
non-content data. This can facilitate interacting programmatically non-content data. This can facilitate interacting programmatically
with PDF files through qpdf's command line interface. For more with PDF files through qpdf's command line interface. For more
@ -2344,7 +2344,7 @@ QPDF JSON
Overview Overview
-------- --------
Beginning with qpdf version 8.3.0, the @1@command@1@qpdf@2@command@2@ Beginning with qpdf version 8.3.0, the :command:`qpdf`
command-line program can produce a JSON representation of the 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 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. This JSON objects in the PDF file excluding the content of streams. This JSON
@ -2386,7 +2386,7 @@ Compatibility
strong effort will be made to avoid breaking compatibility. strong effort will be made to avoid breaking compatibility.
Documentation Documentation
The @1@command@1@qpdf@2@command@2@ command can be invoked with the The :command:`qpdf` command can be invoked with the
@1@option@1@--json-help@2@option@2@ option. This will output a JSON @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 structure that has the same structure as the JSON output that qpdf
generates, except that each field in the help output is a description generates, except that each field in the help output is a description
@ -2509,8 +2509,8 @@ be aware of:
"``parameters``" that indicates the decode level used for computing "``parameters``" that indicates the decode level used for computing
whether a stream was filterable. For example, jpeg images will be whether a stream was filterable. For example, jpeg images will be
shown as not filterable by default, but they will be shown as shown as not filterable by default, but they will be shown as
filterable if you run @1@command@1@qpdf --json filterable if you run :command:`qpdf --json
--decode-level=all@2@command@2@. --decode-level=all`.
.. _ref.design: .. _ref.design:
@ -3050,7 +3050,7 @@ Version 3.0 of qpdf introduced the ability to copy objects into a
@1@firstterm@1@foreign objects@2@firstterm@2@. 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 merging of PDF files. The "from" ``QPDF`` object must remain valid after
the copy as discussed in the note below. The the copy as discussed in the note below. The
@1@command@1@qpdf@2@command@2@ command-line tool provides limited :command:`qpdf` command-line tool provides limited
support for basic page selection, including merging in pages from other support for basic page selection, including merging in pages from other
files, but the library's API makes it possible to implement arbitrarily files, but the library's API makes it possible to implement arbitrarily
complex merging operations. The main method for copying foreign objects complex merging operations. The main method for copying foreign objects
@ -3277,9 +3277,9 @@ Basic Strategy for Linearization
To avoid the incestuous problem of having the qpdf library validate its To avoid the incestuous problem of having the qpdf library validate its
own linearized files, we have a special linearized file checking mode own linearized files, we have a special linearized file checking mode
which can be invoked via @1@command@1@qpdf which can be invoked via :command:`qpdf
--check-linearization@2@command@2@ (or @1@command@1@qpdf --check-linearization` (or :command:`qpdf
--check@2@command@2@). This mode reads the linearization parameter --check`). This mode reads the linearization parameter
dictionary and the hint streams and validates that object ordering, dictionary and the hint streams and validates that object ordering,
parameters, and hint stream contents are correct. The validation code parameters, and hint stream contents are correct. The validation code
was first tested against linearized files created by external tools was first tested against linearized files created by external tools
@ -3441,11 +3441,11 @@ linearization appendix of the PDF specification.
Debugging Note Debugging Note
-------------- --------------
The @1@command@1@qpdf --show-linearization@2@command@2@ command can show The :command:`qpdf --show-linearization` command can show
the complete contents of linearization hint streams. To look at the raw the complete contents of linearization hint streams. To look at the raw
data, you can extract the filtered contents of the linearization hint data, you can extract the filtered contents of the linearization hint
tables using @1@command@1@qpdf --show-object=n tables using :command:`qpdf --show-object=n
--filtered-stream-data@2@command@2@. Then, to convert this into a bit --filtered-stream-data`. Then, to convert this into a bit
stream (since linearization tables are bit streams written without stream (since linearization tables are bit streams written without
regard to byte boundaries), you can pipe the resulting data through the regard to byte boundaries), you can pipe the resulting data through the
following perl code: following perl code:
@ -3818,7 +3818,7 @@ For a detailed list of changes, please see the file
the original input file, unused form fields are removed, which the original input file, unused form fields are removed, which
prevents lots of unused annotations from being retained. prevents lots of unused annotations from being retained.
- By default, @1@command@1@qpdf@2@command@2@ no longer allows - By default, :command:`qpdf` no longer allows
creation of encrypted PDF files whose user password is creation of encrypted PDF files whose user password is
non-empty and owner password is empty when a 256-bit key is in non-empty and owner password is empty when a 256-bit key is in
use. The @1@option@1@--allow-insecure@2@option@2@ option, use. The @1@option@1@--allow-insecure@2@option@2@ option,
@ -4082,7 +4082,7 @@ For a detailed list of changes, please see the file
performance while allowing indirect objects to appear in performance while allowing indirect objects to appear in
``/DecodeParms``. ``/DecodeParms``.
- When extracting pages, the @1@command@1@qpdf@2@command@2@ CLI - When extracting pages, the :command:`qpdf` CLI
only removes unreferenced resources from the pages that are only removes unreferenced resources from the pages that are
being kept, resulting in a significant performance improvement being kept, resulting in a significant performance improvement
when extracting small numbers of pages from large, complex when extracting small numbers of pages from large, complex
@ -4164,7 +4164,7 @@ For a detailed list of changes, please see the file
- Build Changes - Build Changes
- The option @1@option@1@--disable-rpath@2@option@2@ is now - The option @1@option@1@--disable-rpath@2@option@2@ is now
supported by qpdf's @1@command@1@./configure@2@command@2@ supported by qpdf's :command:`./configure`
script. Some distributions' packaging standards recommended the script. Some distributions' packaging standards recommended the
use of this option. use of this option.
@ -4262,7 +4262,7 @@ For a detailed list of changes, please see the file
and, if so, what its length and filters are. Without this, it and, if so, what its length and filters are. Without this, it
was not possible to tell conclusively from the JSON output was not possible to tell conclusively from the JSON output
alone whether or not an object was a stream. Run alone whether or not an object was a stream. Run
@1@command@1@qpdf --json-help@2@command@2@ for details. :command:`qpdf --json-help` for details.
- Add new option - Add new option
@1@option@1@--remove-unreferenced-resources@2@option@2@ which @1@option@1@--remove-unreferenced-resources@2@option@2@ which
@ -4281,12 +4281,12 @@ For a detailed list of changes, please see the file
@1@option@1@--remove-unreferenced-resources=no@2@option@2@. @1@option@1@--remove-unreferenced-resources=no@2@option@2@.
- If the ``QPDF_EXECUTABLE`` environment variable is set when - If the ``QPDF_EXECUTABLE`` environment variable is set when
invoking @1@command@1@qpdf --bash-completion@2@command@2@ or invoking :command:`qpdf --bash-completion` or
@1@command@1@qpdf --zsh-completion@2@command@2@, the completion :command:`qpdf --zsh-completion`, the completion
command that it outputs will refer to qpdf using the value of command that it outputs will refer to qpdf using the value of
that variable rather than what @1@command@1@qpdf@2@command@2@ that variable rather than what :command:`qpdf`
determines its executable path to be. This can be useful when determines its executable path to be. This can be useful when
wrapping @1@command@1@qpdf@2@command@2@ with a script, working wrapping :command:`qpdf` with a script, working
with a version in the source tree, using an AppImage, or other with a version in the source tree, using an AppImage, or other
situations where there is some indirection. situations where there is some indirection.
@ -4381,15 +4381,15 @@ For a detailed list of changes, please see the file
the reconstructed user password for older encryption formats, the reconstructed user password for older encryption formats,
this provides the same information as this provides the same information as
@1@option@1@--show-encryption@2@option@2@ but in a consistent, @1@option@1@--show-encryption@2@option@2@ but in a consistent,
parseable format. See output of @1@command@1@qpdf parseable format. See output of :command:`qpdf
--json-help@2@command@2@ for details. --json-help` for details.
- Bug Fixes - Bug Fixes
- In QDF mode, be sure not to write more than one XRef stream to - In QDF mode, be sure not to write more than one XRef stream to
a file, even when a file, even when
@1@option@1@--preserve-unreferenced@2@option@2@ is used. @1@option@1@--preserve-unreferenced@2@option@2@ is used.
@1@command@1@fix-qdf@2@command@2@ assumes that there is only :command:`fix-qdf` assumes that there is only
one XRef stream, and that it appears at the end of the file. one XRef stream, and that it appears at the end of the file.
- When externalizing inline images, properly handle images whose - When externalizing inline images, properly handle images whose
@ -4446,7 +4446,7 @@ For a detailed list of changes, please see the file
specified in the range. specified in the range.
- Fix shell wildcard expansion behavior (``*`` and ``?``) of the - Fix shell wildcard expansion behavior (``*`` and ``?``) of the
@1@command@1@qpdf.exe@2@command@2@ as built my MSVC. :command:`qpdf.exe` as built my MSVC.
9.0.2: October 12, 2019 9.0.2: October 12, 2019
- Bug Fix - Bug Fix
@ -4512,7 +4512,7 @@ For a detailed list of changes, please see the file
Options <#ref.basic-options>`__ for more details. Options <#ref.basic-options>`__ for more details.
- The @1@option@1@--recompress-flate@2@option@2@ instructs - The @1@option@1@--recompress-flate@2@option@2@ instructs
@1@command@1@qpdf@2@command@2@ to recompress streams that are :command:`qpdf` to recompress streams that are
already compressed with ``/FlateDecode``. Useful with already compressed with ``/FlateDecode``. Useful with
@1@option@1@--compression-level@2@option@2@. @1@option@1@--compression-level@2@option@2@.
@ -4570,8 +4570,8 @@ For a detailed list of changes, please see the file
``QPDF::ownerPasswordMatched`` have been added to enable a ``QPDF::ownerPasswordMatched`` have been added to enable a
caller to determine whether the supplied password was the user caller to determine whether the supplied password was the user
password, the owner password, or both. This information is also password, the owner password, or both. This information is also
displayed by @1@command@1@qpdf --show-encryption@2@command@2@ displayed by :command:`qpdf --show-encryption`
and @1@command@1@qpdf --check@2@command@2@. and :command:`qpdf --check`.
- Static method ``Pl_Flate::setCompressionLevel`` can be called - Static method ``Pl_Flate::setCompressionLevel`` can be called
to set the zlib compression level globally used by all to set the zlib compression level globally used by all
@ -4609,8 +4609,8 @@ For a detailed list of changes, please see the file
files have been fixed. Most of these problems were found by files have been fixed. Most of these problems were found by
Google's OSS-Fuzz project. Google's OSS-Fuzz project.
- When @1@command@1@qpdf --check@2@command@2@ or - When :command:`qpdf --check` or
@1@command@1@qpdf --check-linearization@2@command@2@ encounters :command:`qpdf --check-linearization` encounters
a file with linearization warnings but not errors, it now a file with linearization warnings but not errors, it now
properly exits with exit code 3 instead of 2. properly exits with exit code 3 instead of 2.
@ -4648,12 +4648,12 @@ For a detailed list of changes, please see the file
conversion warnings enabled. Numerous changes were made to the conversion warnings enabled. Numerous changes were made to the
library to make this safe. library to make this safe.
- QPDF's @1@command@1@make install@2@command@2@ target explicitly - QPDF's :command:`make install` target explicitly
specifies the mode to use when installing files instead of specifies the mode to use when installing files instead of
relying the user's umask. It was previously doing this for some relying the user's umask. It was previously doing this for some
files but not others. files but not others.
- If @1@command@1@pkg-config@2@command@2@ is available, use it to - If :command:`pkg-config` is available, use it to
locate @1@filename@1@libjpeg@2@filename@2@ and locate @1@filename@1@libjpeg@2@filename@2@ and
@1@filename@1@zlib@2@filename@2@ dependencies, falling back on @1@filename@1@zlib@2@filename@2@ dependencies, falling back on
old behavior if unsuccessful. old behavior if unsuccessful.
@ -4674,15 +4674,15 @@ For a detailed list of changes, please see the file
8.4.1: April 27, 2019 8.4.1: April 27, 2019
- Enhancements - Enhancements
- When @1@command@1@qpdf --version@2@command@2@ is run, it will - When :command:`qpdf --version` is run, it will
detect if the qpdf CLI was built with a different version of detect if the qpdf CLI was built with a different version of
qpdf than the library, which may indicate a problem with the qpdf than the library, which may indicate a problem with the
installation. installation.
- New option @1@option@1@--remove-page-labels@2@option@2@ will - New option @1@option@1@--remove-page-labels@2@option@2@ will
remove page labels before generating output. This used to remove page labels before generating output. This used to
happen if you ran @1@command@1@qpdf --empty --pages .. happen if you ran :command:`qpdf --empty --pages ..
--@2@command@2@, but the behavior changed in qpdf 8.3.0. This --`, but the behavior changed in qpdf 8.3.0. This
option enables people who were relying on the old behavior to option enables people who were relying on the old behavior to
get it again. get it again.
@ -4795,7 +4795,7 @@ For a detailed list of changes, please see the file
- In the @1@option@1@--pages@2@option@2@ option, allow use of "." - In the @1@option@1@--pages@2@option@2@ option, allow use of "."
as a shortcut for the primary input file. That way, you can do as a shortcut for the primary input file. That way, you can do
@1@command@1@qpdf in.pdf --pages . 1-2 -- out.pdf@2@command@2@ :command:`qpdf in.pdf --pages . 1-2 -- out.pdf`
instead of having to repeat @1@filename@1@in.pdf@2@filename@2@ instead of having to repeat @1@filename@1@in.pdf@2@filename@2@
in the command. in the command.
@ -4868,7 +4868,7 @@ For a detailed list of changes, please see the file
resulting object is an indirect object ready to be passed to resulting object is an indirect object ready to be passed to
``QPDFPageDocumentHelper::addPage()`` for either the original ``QPDFPageDocumentHelper::addPage()`` for either the original
``QPDF`` object or a different one. This is what the ``QPDF`` object or a different one. This is what the
@1@command@1@qpdf@2@command@2@ command-line tool uses to copy :command:`qpdf` command-line tool uses to copy
the same page multiple times from the same file during the same page multiple times from the same file during
splitting and merging operations. splitting and merging operations.
@ -4931,15 +4931,15 @@ For a detailed list of changes, please see the file
``WINDOWS_WMAIN`` to be defined. If you do your own builds with ``WINDOWS_WMAIN`` to be defined. If you do your own builds with
other compilers, you can define this symbol to cause ``wmain`` other compilers, you can define this symbol to cause ``wmain``
to be used. This is needed to allow the Windows to be used. This is needed to allow the Windows
@1@command@1@qpdf@2@command@2@ command to receive Unicode :command:`qpdf` command to receive Unicode
command-line options. command-line options.
8.3.0: January 7, 2019 8.3.0: January 7, 2019
- Command-line Enhancements - Command-line Enhancements
- Shell completion: you can now use eval @1@command@1@$(qpdf - Shell completion: you can now use eval :command:`$(qpdf
--completion-bash)@2@command@2@ and eval @1@command@1@$(qpdf --completion-bash)` and eval :command:`$(qpdf
--completion-zsh)@2@command@2@ to enable shell completion for --completion-zsh)` to enable shell completion for
bash and zsh. bash and zsh.
- Page numbers (also known as page labels) are now preserved when - Page numbers (also known as page labels) are now preserved when
@ -4968,8 +4968,8 @@ For a detailed list of changes, please see the file
options @1@option@1@--json@2@option@2@, options @1@option@1@--json@2@option@2@,
@1@option@1@--json-key@2@option@2@, and @1@option@1@--json-key@2@option@2@, and
@1@option@1@--json-object@2@option@2@ to generate a JSON @1@option@1@--json-object@2@option@2@ to generate a JSON
representation of the PDF file. Run @1@command@1@qpdf representation of the PDF file. Run :command:`qpdf
--json-help@2@command@2@ to get a description of the JSON --json-help` to get a description of the JSON
format. For more information, see `QPDF JSON <#ref.json>`__. format. For more information, see `QPDF JSON <#ref.json>`__.
- The @1@option@1@--generate-appearances@2@option@2@ flag will - The @1@option@1@--generate-appearances@2@option@2@ flag will
@ -5109,11 +5109,11 @@ For a detailed list of changes, please see the file
- Build Improvements - Build Improvements
- It is no longer necessary to run - It is no longer necessary to run
@1@command@1@autogen.sh@2@command@2@ to build from a pristine :command:`autogen.sh` to build from a pristine
checkout. Automatically generated files are now committed so checkout. Automatically generated files are now committed so
that it is possible to build on platforms without autoconf that it is possible to build on platforms without autoconf
directly from a clean checkout of the repository. The directly from a clean checkout of the repository. The
@1@command@1@configure@2@command@2@ script detects if the files :command:`configure` script detects if the files
are out of date when it also determines that the tools are are out of date when it also determines that the tools are
present to regenerate them. present to regenerate them.
@ -5136,7 +5136,7 @@ For a detailed list of changes, please see the file
autoconf files, it could cause this check to fail. To avoid autoconf files, it could cause this check to fail. To avoid
this problem, pass this problem, pass
@1@option@1@--disable-check-autofiles@2@option@2@ to @1@option@1@--disable-check-autofiles@2@option@2@ to
@1@command@1@configure@2@command@2@. :command:`configure`.
- If you would like to have qpdf completion enabled - If you would like to have qpdf completion enabled
automatically, you can install completion files in the automatically, you can install completion files in the
@ -5293,7 +5293,7 @@ For a detailed list of changes, please see the file
called by ``QPDFWriter`` to update your idea of the percentage called by ``QPDFWriter`` to update your idea of the percentage
it thinks it is through writing its output. Client programs can it thinks it is through writing its output. Client programs can
use this to implement reasonably accurate progress meters. The use this to implement reasonably accurate progress meters. The
@1@command@1@qpdf@2@command@2@ command line tool uses this to :command:`qpdf` command line tool uses this to
implement its @1@option@1@--progress@2@option@2@ option. implement its @1@option@1@--progress@2@option@2@ option.
- New methods ``QPDFObjectHandle::newUnicodeString`` and - New methods ``QPDFObjectHandle::newUnicodeString`` and
@ -5347,7 +5347,7 @@ For a detailed list of changes, please see the file
type". This situation should be mostly or entirely eliminated type". This situation should be mostly or entirely eliminated
now. now.
- Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line - Enhancements to the :command:`qpdf` Command-line
Tool. All new options listed here are documented in more detail in Tool. All new options listed here are documented in more detail in
`Running QPDF <#ref.using>`__. `Running QPDF <#ref.using>`__.
@ -5364,8 +5364,8 @@ For a detailed list of changes, please see the file
changes to the API. changes to the API.
- Add function ``qpdf_check_pdf`` to the C API. This function - Add function ``qpdf_check_pdf`` to the C API. This function
does basic checking that is a subset of what @1@command@1@qpdf does basic checking that is a subset of what :command:`qpdf
--check@2@command@2@ performs. --check` performs.
- Major enhancements to the lexical layer of qpdf. For a complete - Major enhancements to the lexical layer of qpdf. For a complete
list of enhancements, please refer to the list of enhancements, please refer to the
@ -5461,7 +5461,7 @@ For a detailed list of changes, please see the file
specialized and is only useful to applications that already specialized and is only useful to applications that already
know how to create PCLm files. know how to create PCLm files.
- Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line - Enhancements to the :command:`qpdf` Command-line
Tool. All new options listed here are documented in more detail in Tool. All new options listed here are documented in more detail in
`Running QPDF <#ref.using>`__. `Running QPDF <#ref.using>`__.
@ -5492,14 +5492,14 @@ For a detailed list of changes, please see the file
The @1@option@1@--stream-data@2@option@2@ option will remain The @1@option@1@--stream-data@2@option@2@ option will remain
available. available.
- When running @1@command@1@qpdf --check@2@command@2@ with other - When running :command:`qpdf --check` with other
options, checks are always run first. This enables qpdf to options, checks are always run first. This enables qpdf to
perform its full recovery logic before outputting other perform its full recovery logic before outputting other
information. This can be especially useful when manually information. This can be especially useful when manually
recovering broken files, looking at qpdf's regenerated cross recovering broken files, looking at qpdf's regenerated cross
reference table, or other similar operations. reference table, or other similar operations.
- Process @1@command@1@--pages@2@command@2@ earlier so that other - Process :command:`--pages` earlier so that other
options like @1@option@1@--show-pages@2@option@2@ or options like @1@option@1@--show-pages@2@option@2@ or
@1@option@1@--split-pages@2@option@2@ can operate on the file @1@option@1@--split-pages@2@option@2@ can operate on the file
after page splitting/merging has occurred. after page splitting/merging has occurred.
@ -5573,10 +5573,10 @@ For a detailed list of changes, please see the file
- Bug fix: qpdf would fail to write files that had streams with - Bug fix: qpdf would fail to write files that had streams with
decode parameters referencing other streams. decode parameters referencing other streams.
- New example program: @1@command@1@pdf-split-pages@2@command@2@: - New example program: :command:`pdf-split-pages`:
efficiently split PDF files into individual pages. The example efficiently split PDF files into individual pages. The example
program does this more efficiently than using @1@command@1@qpdf program does this more efficiently than using :command:`qpdf
--pages@2@command@2@ to do it. --pages` to do it.
- Packaging fix: Visual C++ binaries did not support Windows XP. - Packaging fix: Visual C++ binaries did not support Windows XP.
This has been rectified by updating the compilers used to generate This has been rectified by updating the compilers used to generate
@ -5619,9 +5619,9 @@ For a detailed list of changes, please see the file
cryptography API. To disable the OS-specific cryptography and use cryptography API. To disable the OS-specific cryptography and use
the old version, pass the the old version, pass the
@1@option@1@--enable-insecure-random@2@option@2@ option to @1@option@1@--enable-insecure-random@2@option@2@ option to
@1@command@1@./configure@2@command@2@. :command:`./configure`.
- The @1@command@1@qpdf@2@command@2@ command-line tool now issues a - The :command:`qpdf` command-line tool now issues a
warning when @1@option@1@-accessibility=n@2@option@2@ is specified warning when @1@option@1@-accessibility=n@2@option@2@ is specified
for newer encryption versions stating that the option is ignored. for newer encryption versions stating that the option is ignored.
qpdf, per the spec, has always ignored this flag, but it qpdf, per the spec, has always ignored this flag, but it
@ -5648,12 +5648,12 @@ For a detailed list of changes, please see the file
notes. notes.
- Add @1@option@1@--show-npages@2@option@2@ command-line option to - Add @1@option@1@--show-npages@2@option@2@ command-line option to
the @1@command@1@qpdf@2@command@2@ command to show the number of the :command:`qpdf` command to show the number of
pages in a file. pages in a file.
- Allow omission of the page range within - Allow omission of the page range within
@1@option@1@--pages@2@option@2@ for the @1@option@1@--pages@2@option@2@ for the
@1@command@1@qpdf@2@command@2@ command. When omitted, the page :command:`qpdf` command. When omitted, the page
range is implicitly taken to be all the pages in the file. range is implicitly taken to be all the pages in the file.
- Various enhancements were made to support different types of - Various enhancements were made to support different types of
@ -5663,7 +5663,7 @@ For a detailed list of changes, please see the file
4.1.0: April 14, 2013 4.1.0: April 14, 2013
- Note to people including qpdf in distributions: the - Note to people including qpdf in distributions: the
@1@filename@1@.la@2@filename@2@ files generated by libtool are now @1@filename@1@.la@2@filename@2@ files generated by libtool are now
installed by qpdf's @1@command@1@make install@2@command@2@ target. installed by qpdf's :command:`make install` target.
Before, they were not installed. This means that if your Before, they were not installed. This means that if your
distribution does not want to include distribution does not want to include
@1@filename@1@.la@2@filename@2@ files, you must remove them as @1@filename@1@.la@2@filename@2@ files, you must remove them as
@ -5689,7 +5689,7 @@ For a detailed list of changes, please see the file
``QPDFObjectHandle`` object. These methods can be used for more ``QPDFObjectHandle`` object. These methods can be used for more
efficient parsing and debugging/diagnostic messages. efficient parsing and debugging/diagnostic messages.
- @1@command@1@qpdf --check@2@command@2@ now parses all pages' - :command:`qpdf --check` now parses all pages'
content streams in addition to doing other checks. While there are content streams in addition to doing other checks. While there are
still many types of errors that cannot be detected, syntactic still many types of errors that cannot be detected, syntactic
errors in content streams will now be reported. errors in content streams will now be reported.
@ -5735,7 +5735,7 @@ For a detailed list of changes, please see the file
was loss of filled in form values for certain files. was loss of filled in form values for certain files.
- Installation no longer uses GNU/Linux-specific versions of some - Installation no longer uses GNU/Linux-specific versions of some
commands, so @1@command@1@make install@2@command@2@ works on commands, so :command:`make install` works on
Solaris with native tools. Solaris with native tools.
- The 64-bit mingw Windows binary package no longer includes a - The 64-bit mingw Windows binary package no longer includes a
@ -5838,7 +5838,7 @@ For a detailed list of changes, please see the file
- Removed the method ``decodeStreams``. This method was used by - Removed the method ``decodeStreams``. This method was used by
the @1@option@1@--check@2@option@2@ option of the the @1@option@1@--check@2@option@2@ option of the
@1@command@1@qpdf@2@command@2@ command-line tool to force all :command:`qpdf` command-line tool to force all
streams in the file to be decoded, but it also suffered from streams in the file to be decoded, but it also suffered from
the problem of opening otherwise unreferenced streams and thus the problem of opening otherwise unreferenced streams and thus
could report false positive. The could report false positive. The
@ -5859,9 +5859,9 @@ For a detailed list of changes, please see the file
- Allow the PDF header to appear anywhere in the first 1024 bytes of - Allow the PDF header to appear anywhere in the first 1024 bytes of
the file. This is consistent with what other readers do. the file. This is consistent with what other readers do.
- Fix the @1@command@1@pkg-config@2@command@2@ files to list zlib - Fix the :command:`pkg-config` files to list zlib
and pcre in ``Requires.private`` to better support static linking and pcre in ``Requires.private`` to better support static linking
using @1@command@1@pkg-config@2@command@2@. using :command:`pkg-config`.
3.0.2: September 6, 2012 3.0.2: September 6, 2012
- Bug fix: ``QPDFWriter::setOutputMemory`` did not work when not - Bug fix: ``QPDFWriter::setOutputMemory`` did not work when not
@ -5875,7 +5875,7 @@ For a detailed list of changes, please see the file
3.0.1: August 11, 2012 3.0.1: August 11, 2012
- Version 3.0.0 included addition of files for - Version 3.0.0 included addition of files for
@1@command@1@pkg-config@2@command@2@, but this was not mentioned :command:`pkg-config`, but this was not mentioned
in the release notes. The release notes for 3.0.0 were updated to in the release notes. The release notes for 3.0.0 were updated to
mention this. mention this.
@ -5909,10 +5909,10 @@ For a detailed list of changes, please see the file
as the compiler and underlying platforms support it. as the compiler and underlying platforms support it.
- Support for page selection (splitting and merging PDF files) has - Support for page selection (splitting and merging PDF files) has
been added to the @1@command@1@qpdf@2@command@2@ command-line been added to the :command:`qpdf` command-line
tool. See `Page Selection Options <#ref.page-selection>`__. tool. See `Page Selection Options <#ref.page-selection>`__.
- Options have been added to the @1@command@1@qpdf@2@command@2@ - Options have been added to the :command:`qpdf`
command-line tool for copying encryption parameters from another command-line tool for copying encryption parameters from another
file. See `Basic Options <#ref.basic-options>`__. file. See `Basic Options <#ref.basic-options>`__.
@ -5952,10 +5952,10 @@ For a detailed list of changes, please see the file
(such as Linux), symbol versions are enabled by default. They can (such as Linux), symbol versions are enabled by default. They can
be disabled by passing be disabled by passing
@1@option@1@--disable-ld-version-script@2@option@2@ to @1@option@1@--disable-ld-version-script@2@option@2@ to
@1@command@1@./configure@2@command@2@. :command:`./configure`.
- The file @1@filename@1@libqpdf.pc@2@filename@2@ is now installed - The file @1@filename@1@libqpdf.pc@2@filename@2@ is now installed
to support @1@command@1@pkg-config@2@command@2@. to support :command:`pkg-config`.
- Image comparison tests are off by default now since they are not - Image comparison tests are off by default now since they are not
needed to verify a correct build or port of qpdf. They are needed needed to verify a correct build or port of qpdf. They are needed
@ -5964,7 +5964,7 @@ For a detailed list of changes, please see the file
See @1@filename@1@README.md@2@filename@2@ for details. See @1@filename@1@README.md@2@filename@2@ for details.
- Large file tests are off by default but can be turned on with - Large file tests are off by default but can be turned on with
@1@command@1@./configure@2@command@2@ or by setting an environment :command:`./configure` or by setting an environment
variable before running the test suite. See variable before running the test suite. See
@1@filename@1@README.md@2@filename@2@ for details. @1@filename@1@README.md@2@filename@2@ for details.
@ -5973,7 +5973,7 @@ For a detailed list of changes, please see the file
@1@filename@1@build/qtest.log@2@filename@2@. For packagers who are @1@filename@1@build/qtest.log@2@filename@2@. For packagers who are
building with an autobuilder, you can add the building with an autobuilder, you can add the
@1@option@1@--enable-show-failed-test-output@2@option@2@ option to @1@option@1@--enable-show-failed-test-output@2@option@2@ option to
@1@command@1@./configure@2@command@2@ to restore the old behavior. :command:`./configure` to restore the old behavior.
2.3.1: December 28, 2011 2.3.1: December 28, 2011
- Fix thread-safety problem resulting from non-thread-safe use of - Fix thread-safety problem resulting from non-thread-safe use of
@ -6090,8 +6090,8 @@ For a detailed list of changes, please see the file
stream's data is filterable. stream's data is filterable.
- Provide two new examples: - Provide two new examples:
@1@command@1@pdf-double-page-size@2@command@2@ and :command:`pdf-double-page-size` and
@1@command@1@pdf-invert-images@2@command@2@ that illustrate the :command:`pdf-invert-images` that illustrate the
newly added interfaces. newly added interfaces.
- Fix a memory leak that would cause loss of a few bytes for every - Fix a memory leak that would cause loss of a few bytes for every
@ -6109,7 +6109,7 @@ For a detailed list of changes, please see the file
- Apply the same padding calculation fix from version 2.1.2 to the - Apply the same padding calculation fix from version 2.1.2 to the
main cross reference stream as well. main cross reference stream as well.
- Since @1@command@1@qpdf --check@2@command@2@ only performs limited - Since :command:`qpdf --check` only performs limited
checks, clarify the output to make it clear that there still may checks, clarify the output to make it clear that there still may
be errors that qpdf can't check. This should make it less be errors that qpdf can't check. This should make it less
surprising to people when another PDF reader is unable to read a surprising to people when another PDF reader is unable to read a
@ -6181,7 +6181,7 @@ For a detailed list of changes, please see the file
use qpdf can enforce permissions. use qpdf can enforce permissions.
- The @1@option@1@--check@2@option@2@ option to - The @1@option@1@--check@2@option@2@ option to
@1@command@1@qpdf@2@command@2@ has been extended to include some :command:`qpdf` has been extended to include some
additional information. additional information.
- There have been a handful of non-compatible API changes. For - There have been a handful of non-compatible API changes. For
@ -6213,7 +6213,7 @@ For a detailed list of changes, please see the file
2.0.2: June 30, 2008 2.0.2: June 30, 2008
- Update test suite to work properly with a - Update test suite to work properly with a
non-@1@command@1@bash@2@command@2@ non-:command:`bash`
@1@filename@1@/bin/sh@2@filename@2@ and with Perl 5.10. No changes @1@filename@1@/bin/sh@2@filename@2@ and with Perl 5.10. No changes
were made to the actual qpdf source code itself for this release. were made to the actual qpdf source code itself for this release.