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 things previously marked with <filename> with :file:...

Browse Source
This commit is contained in:
Jay Berkenbilt 2021-12-11 19:02:42 -05:00
parent 15b87d769e
commit b764ba95ed
2 changed files with 129 additions and 130 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 -->
<filename> -> :file: (allows {x})
<option> -> :samp: (allows {x}) <option> -> :samp: (allows {x})
<firstterm> -> just use literal <firstterm> -> just use literal
<replaceable> -> Make sure in :file: or :samp:, then use {} <replaceable> -> Make sure in :file: or :samp:, then use {}

258
manual/index.rst
View File

@ -86,8 +86,8 @@ Building and Installing QPDF
============================ ============================
This chapter describes how to build and install qpdf. Please see also This chapter describes how to build and install qpdf. Please see also
the @1@filename@1@README.md@2@filename@2@ and the :file:`README.md` and
@1@filename@1@INSTALL@2@filename@2@ files in the source distribution. :file:`INSTALL` files in the source distribution.
.. _ref.prerequisites: .. _ref.prerequisites:
@ -167,16 +167,16 @@ suite and :command:`make install` to install. Please run
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
@1@filename@1@README.md@2@filename@2@ and :file:`README.md` and
@1@filename@1@INSTALL@2@filename@2@ files in the source distribution. :file:`INSTALL` files in the source distribution.
Building on Windows is a little bit more complicated. For details, Building on Windows is a little bit more complicated. For details,
please see @1@filename@1@README-windows.md@2@filename@2@ in the source please see :file:`README-windows.md` in the source
distribution. You can also download a binary distribution for Windows. distribution. You can also download a binary distribution for Windows.
There is a port of qpdf to Visual C++ version 6 in the There is a port of qpdf to Visual C++ version 6 in the
@1@filename@1@contrib@2@filename@2@ area generously contributed by Jian :file:`contrib` area generously contributed by Jian
Ma. This is also discussed in more detail in Ma. This is also discussed in more detail in
@1@filename@1@README-windows.md@2@filename@2@. :file:`README-windows.md`.
While ``wchar_t`` is part of the C++ standard, qpdf uses it in only one While ``wchar_t`` is part of the C++ standard, qpdf uses it in only one
place in the public API, and it's just in a helper function. It is place in the public API, and it's just in a helper function. It is
@ -191,7 +191,7 @@ uses :command:`autoconf`, it does not use
:command:`automake` 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@. :file:`Makefile`.
.. _ref.crypto: .. _ref.crypto:
@ -251,13 +251,13 @@ used and that the native provider is not built, you could run
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
@1@filename@1@libqpdf/qpdf/qpdf-config.h.in@2@filename@2@ provides :file:`libqpdf/qpdf/qpdf-config.h.in` provides
macros ``DEFAULT_CRYPTO``, whose value must be a string naming the macros ``DEFAULT_CRYPTO``, whose value must be a string naming the
default crypto provider, and various symbols starting with default crypto provider, and various symbols starting with
``USE_CRYPTO_``, at least one of which has to be enabled. Additionally, ``USE_CRYPTO_``, at least one of which has to be enabled. Additionally,
you must compile the source files that implement a crypto provider. To you must compile the source files that implement a crypto provider. To
get a list of those files, look at get a list of those files, look at
@1@filename@1@libqpdf/build.mk@2@filename@2@. If you want to omit a :file:`libqpdf/build.mk`. If you want to omit a
particular crypto provider, as long as its ``USE_CRYPTO_`` symbol is particular crypto provider, as long as its ``USE_CRYPTO_`` symbol is
undefined, you can completely ignore the source files that belong to a undefined, you can completely ignore the source files that belong to a
particular crypto provider. Additionally, crypto providers may have particular crypto provider. Additionally, crypto providers may have
@ -269,8 +269,8 @@ is not defined, and ``DEFAULT_CRYPTO`` is defined to ``"native"``. Then
you must include the source files used in the native implementation, you must include the source files used in the native implementation,
some of which were added or renamed from earlier versions, to your some of which were added or renamed from earlier versions, to your
build, and you can ignore build, and you can ignore
@1@filename@1@QPDFCrypto_gnutls.cc@2@filename@2@. Always consult :file:`QPDFCrypto_gnutls.cc`. Always consult
@1@filename@1@libqpdf/build.mk@2@filename@2@ to get the list of source :file:`libqpdf/build.mk` to get the list of source
files you need to build. files you need to build.
.. _ref.crypto.runtime: .. _ref.crypto.runtime:
@ -303,7 +303,7 @@ certain crypto provider to be used, you can call the method
a built-in or developer-supplied provider. To add your own crypto a built-in or developer-supplied provider. To add your own crypto
provider, you have to create a class derived from ``QPDFCryptoImpl`` and provider, you have to create a class derived from ``QPDFCryptoImpl`` and
register it with ``QPDFCryptoProvider``. For additional information, see register it with ``QPDFCryptoProvider``. For additional information, see
comments in @1@filename@1@include/qpdf/QPDFCryptoImpl.hh@2@filename@2@. comments in :file:`include/qpdf/QPDFCryptoImpl.hh`.
.. _ref.crypto.design: .. _ref.crypto.design:
@ -417,10 +417,10 @@ some things you may want to keep in mind:
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
@1@filename@1@completions@2@filename@2@ directory. :file:`completions` directory.
- Packagers are encouraged to install the source files from the - Packagers are encouraged to install the source files from the
@1@filename@1@examples@2@filename@2@ directory along with qpdf :file:`examples` directory along with qpdf
development packages. development packages.
.. _ref.using: .. _ref.using:
@ -625,10 +625,10 @@ needed transformations.
If specified, the output file name should be omitted. This option 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 tells qpdf to replace the input file with the output. It does this by
writing to writing to
@1@filename@1@@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-temp#@2@filename@2@ :file:`@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-temp#`
and, when done, overwriting the input file with the temporary file. and, when done, overwriting the input file with the temporary file.
If there were any warnings, the original input is saved as If there were any warnings, the original input is saved as
@1@filename@1@@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-orig@2@filename@2@. :file:`@1@replaceable@1@infilename@2@replaceable@2@.~qpdf-orig`.
@1@option@1@--copy-encryption=file@2@option@2@ @1@option@1@--copy-encryption=file@2@option@2@
Encrypt the file using the same encryption parameters, including user Encrypt the file using the same encryption parameters, including user
@ -815,7 +815,7 @@ needed transformations.
replaced with a range of zero-padded page numbers starting from 1. replaced with a range of zero-padded page numbers starting from 1.
- Otherwise, if the output file name ends in - Otherwise, if the output file name ends in
@1@filename@1@.pdf@2@filename@2@ (case insensitive), a zero-padded :file:`.pdf` (case insensitive), a zero-padded
page range, preceded by a dash, is inserted before the file page range, preceded by a dash, is inserted before the file
extension. extension.
@ -824,21 +824,21 @@ needed transformations.
Page ranges are a single number in the case of single-page groups or Page ranges are a single number in the case of single-page groups or
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 :file:`infile.pdf` has 12 pages
- :command:`qpdf --split-pages infile.pdf %d-out` - :command:`qpdf --split-pages infile.pdf %d-out`
would generate files @1@filename@1@01-out@2@filename@2@ through would generate files :file:`01-out` through
@1@filename@1@12-out@2@filename@2@ :file:`12-out`
- :command:`qpdf --split-pages=2 infile.pdf - :command:`qpdf --split-pages=2 infile.pdf
outfile.pdf` would generate files outfile.pdf` would generate files
@1@filename@1@outfile-01-02.pdf@2@filename@2@ through :file:`outfile-01-02.pdf` through
@1@filename@1@outfile-11-12.pdf@2@filename@2@ :file:`outfile-11-12.pdf`
- :command:`qpdf --split-pages infile.pdf - :command:`qpdf --split-pages infile.pdf
something.else` would generate files something.else` would generate files
@1@filename@1@something.else-01@2@filename@2@ through :file:`something.else-01` through
@1@filename@1@something.else-12@2@filename@2@ :file:`something.else-12`
Note that outlines, threads, and other global features of the Note that outlines, threads, and other global features of the
original PDF file are not preserved. For each page of output, this original PDF file are not preserved. For each page of output, this
@ -1065,7 +1065,7 @@ the range of pages. Note that "@1@option@1@--@2@option@2@" terminates
parsing of page selection flags. parsing of page selection flags.
Starting with qpf 8.4, the special input file name Starting with qpf 8.4, the special input file name
"@1@filename@1@.@2@filename@2@" can be used as a shortcut for the ":file:`.`" can be used as a shortcut for the
primary input filename. primary input filename.
For each file that pages should be taken from, specify the file, a For each file that pages should be taken from, specify the file, a
@ -1122,8 +1122,8 @@ specified outside of @1@option@1@--pages ... --@2@option@2@. When
@1@option@1@--collate@2@option@2@ is specified, it changes the meaning @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 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 :file:`odd.pdf` and
@1@filename@1@even.pdf@2@filename@2@ containing odd and even pages of a :file:`even.pdf` containing odd and even pages of a
document respectively, you could run :command:`qpdf --collate odd.pdf document respectively, you could run :command:`qpdf --collate odd.pdf
--pages odd.pdf even.pdf -- all.pdf` 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
@ -1193,7 +1193,7 @@ 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
@1@option@1@--empty@2@option@2@ as the primary input file to avoid @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 copying all of that from the first file. For example, to take pages 1
through 5 from a @1@filename@1@infile.pdf@2@filename@2@ while preserving through 5 from a :file:`infile.pdf` while preserving
all metadata associated with that file, you could use all metadata associated with that file, you could use
:: ::
@ -1201,7 +1201,7 @@ all metadata associated with that file, you could use
:command:`qpdf` @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 :file:`infile.pdf` but you wanted the rest of the
metadata to be dropped, you could instead run metadata to be dropped, you could instead run
:: ::
@ -1209,16 +1209,16 @@ metadata to be dropped, you could instead run
:command:`qpdf` @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 :file:`file1.pdf` and pages 11 through 15 from
@1@filename@1@file2.pdf@2@filename@2@ in reverse, taking document-level :file:`file2.pdf` in reverse, taking document-level
metadata from @1@filename@1@file2.pdf@2@filename@2@, you would run metadata from :file:`file2.pdf`, you would run
:: ::
:command:`qpdf` @1@option@1@file2.pdf --pages file1.pdf 1-5 . 15-11 -- outfile.pdf@2@option@2@ :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 :file:`encrypted.pdf` with password
``pass`` and repeat it twice in an output file, and if you wanted to ``pass`` and repeat it twice in an output file, and if you wanted to
drop document-level metadata but preserve encryption, you would use drop document-level metadata but preserve encryption, you would use
@ -1231,8 +1231,8 @@ drop document-level metadata but preserve encryption, you would use
Note that we had to specify the password all three times because giving Note that we had to specify the password all three times because giving
a password as @1@option@1@--encryption-file-password@2@option@2@ doesn't a password as @1@option@1@--encryption-file-password@2@option@2@ doesn't
count for page selection, and as far as qpdf is concerned, count for page selection, and as far as qpdf is concerned,
@1@filename@1@encrypted.pdf@2@filename@2@ and :file:`encrypted.pdf` and
@1@filename@1@./encrypted.pdf@2@filename@2@ are separated files. These :file:`./encrypted.pdf` are separated files. These
are all corner cases that most users should hopefully never have to be are all corner cases that most users should hopefully never have to be
bothered with. bothered with.
@ -1304,15 +1304,15 @@ Here are some examples.
- :command:`--overlay o.pdf --to=1-5 --from=1-3 --repeat=4 - :command:`--overlay o.pdf --to=1-5 --from=1-3 --repeat=4
--`: 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 :file:`o.pdf` 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 :file:`o.pdf`
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.
- :command:`--underlay footer.pdf --from= --repeat=1,2 - :command:`--underlay footer.pdf --from= --repeat=1,2
--`: Underlay page 1 of --`: Underlay page 1 of
@1@filename@1@footer.pdf@2@filename@2@ on all odd output pages, and :file:`footer.pdf` 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 :file:`footer.pdf` on all even
output pages. output pages.
.. _ref.attachments: .. _ref.attachments:
@ -1991,7 +1991,7 @@ given. The following options are available:
@1@option@1@--check@2@option@2@ 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 when everything is valid, so if you are using this to
programmatically validate files in bulk, it is safe to run without programmatically validate files in bulk, it is safe to run without
output redirected to @1@filename@1@/dev/null@2@filename@2@ and just output redirected to :file:`/dev/null` and just
check for a 0 exit code. check for a 0 exit code.
The @1@option@1@--raw-stream-data@2@option@2@ and The @1@option@1@--raw-stream-data@2@option@2@ and
@ -2219,23 +2219,23 @@ Using QPDF from C++
------------------- -------------------
The source tree for the qpdf package has an The source tree for the qpdf package has an
@1@filename@1@examples@2@filename@2@ directory that contains a few :file:`examples` directory that contains a few
example programs. The @1@filename@1@qpdf/qpdf.cc@2@filename@2@ source example programs. The :file:`qpdf/qpdf.cc` source
file also serves as a useful example since it exercises almost all of 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 qpdf library's public interface. The best source of documentation on
the library itself is reading comments in the library itself is reading comments in
@1@filename@1@include/qpdf/QPDF.hh@2@filename@2@, :file:`include/qpdf/QPDF.hh`,
@1@filename@1@include/qpdf/QPDFWriter.hh@2@filename@2@, and :file:`include/qpdf/QPDFWriter.hh`, and
@1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@. :file:`include/qpdf/QPDFObjectHandle.hh`.
All header files are installed in the All header files are installed in the
@1@filename@1@include/qpdf@2@filename@2@ directory. It is recommend that :file:`include/qpdf` directory. It is recommend that
you use ``#include <qpdf/QPDF.hh>`` rather than adding you use ``#include <qpdf/QPDF.hh>`` rather than adding
@1@filename@1@include/qpdf@2@filename@2@ to your include path. :file:`include/qpdf` to your include path.
When linking against the qpdf static library, you may also need to When linking against the qpdf static library, you may also need to
specify ``-lz -ljpeg`` on your link command. If your system understands specify ``-lz -ljpeg`` on your link command. If your system understands
how to read libtool @1@filename@1@.la@2@filename@2@ files, this may not how to read libtool :file:`.la` files, this may not
be necessary. be necessary.
The qpdf library is safe to use in a multithreaded program, but no The qpdf library is safe to use in a multithreaded program, but no
@ -2255,7 +2255,7 @@ directly in other languages. There are a few things that can help.
"C" "C"
The qpdf library includes a "C" language interface that provides a The qpdf library includes a "C" language interface that provides a
subset of the overall capabilities. The header file subset of the overall capabilities. The header file
@1@filename@1@qpdf/qpdf-c.h@2@filename@2@ includes information about :file:`qpdf/qpdf-c.h` includes information about
its use. As long as you use a C++ linker, you can link C programs 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 with qpdf and use the C API. For languages that can directly load
methods from a shared library, the C API can also be useful. People methods from a shared library, the C API can also be useful. People
@ -2600,7 +2600,7 @@ are factory methods for each type of object as well as a convenience
method ``QPDFObjectHandle::parse`` that creates an object from a string method ``QPDFObjectHandle::parse`` that creates an object from a string
representation of the object. Existing instances of ``QPDFObjectHandle`` representation of the object. Existing instances of ``QPDFObjectHandle``
can also be modified in several ways. See comments in can also be modified in several ways. See comments in
@1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for details. :file:`QPDFObjectHandle.hh` for details.
An instance of ``QPDF`` is constructed by using the class's default An instance of ``QPDF`` is constructed by using the class's default
constructor. If desired, the ``QPDF`` object may be configured with constructor. If desired, the ``QPDF`` object may be configured with
@ -2629,8 +2629,8 @@ instead.
There are some convenience routines for very common operations such as There are some convenience routines for very common operations such as
walking the page tree and returning a vector of all page objects. For walking the page tree and returning a vector of all page objects. For
full details, please see the header files full details, please see the header files
@1@filename@1@QPDF.hh@2@filename@2@ and :file:`QPDF.hh` and
@1@filename@1@QPDFObjectHandle.hh@2@filename@2@. There are also some :file:`QPDFObjectHandle.hh`. There are also some
additional helper classes that provide higher level API functions for additional helper classes that provide higher level API functions for
certain document constructions. These are discussed in `Helper certain document constructions. These are discussed in `Helper
Classes <#ref.helper-classes>`__. Classes <#ref.helper-classes>`__.
@ -2697,8 +2697,8 @@ By Convention, document helpers are called
``QPDFSomethingObjectHelper`` and are derived from ``QPDFObjectHelper``. ``QPDFSomethingObjectHelper`` and are derived from ``QPDFObjectHelper``.
For details on specific helpers, please see their header files. You can For details on specific helpers, please see their header files. You can
find them by looking at find them by looking at
@1@filename@1@include/qpdf/QPDF*DocumentHelper.hh@2@filename@2@ and :file:`include/qpdf/QPDF*DocumentHelper.hh` and
@1@filename@1@include/qpdf/QPDF*ObjectHelper.hh@2@filename@2@. :file:`include/qpdf/QPDF*ObjectHelper.hh`.
In order to avoid creation of circular dependencies, the following In order to avoid creation of circular dependencies, the following
general guidelines are followed with helper classes: general guidelines are followed with helper classes:
@ -2790,7 +2790,7 @@ file.
``pdf.processFile("a.pdf");``. ``pdf.processFile("a.pdf");``.
- The ``QPDF`` class checks the beginning of - The ``QPDF`` class checks the beginning of
@1@filename@1@a.pdf@2@filename@2@ for a PDF header. It then reads the :file:`a.pdf` for a PDF header. It then reads the
cross reference table mentioned at the end of the file, ensuring that cross reference table mentioned at the end of the file, ensuring that
it is looking before the last ``%%EOF``. After getting to ``trailer`` it is looking before the last ``%%EOF``. After getting to ``trailer``
keyword, it invokes the parser. keyword, it invokes the parser.
@ -2859,7 +2859,7 @@ warnings about the use of old-style casts in code that is shared between
C and C++ code. C and C++ code.
The ``QIntC`` namespace, provided by The ``QIntC`` namespace, provided by
@1@filename@1@include/qpdf/QIntC.hh@2@filename@2@, implements safe :file:`include/qpdf/QIntC.hh`, implements safe
functions for converting between integer types. These functions do range functions for converting between integer types. These functions do range
checking and throw a ``std::range_error``, which is subclass of checking and throw a ``std::range_error``, which is subclass of
``std::runtime_error``, if conversion from one integer type to another ``std::runtime_error``, if conversion from one integer type to another
@ -2997,7 +2997,7 @@ useful on Windows if you want to avoid a dependency on Microsoft's
cryptography API. You can also supply your own random data provider. For 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 details on how to do this, please refer to the top-level README.md file
in the source distribution and to comments in in the source distribution and to comments in
@1@filename@1@QUtil.hh@2@filename@2@. :file:`QUtil.hh`.
.. _ref.adding-and-remove-pages: .. _ref.adding-and-remove-pages:
@ -3010,7 +3010,7 @@ pages. These are largely convenience routines that handle two tricky
issues: pushing inheritable resources from the ``/Pages`` tree down to issues: pushing inheritable resources from the ``/Pages`` tree down to
individual pages and manipulation of the ``/Pages`` tree itself. For individual pages and manipulation of the ``/Pages`` tree itself. For
details, see ``addPage`` and surrounding methods in details, see ``addPage`` and surrounding methods in
@1@filename@1@QPDF.hh@2@filename@2@. :file:`QPDF.hh`.
.. _ref.reserved-objects: .. _ref.reserved-objects:
@ -3038,7 +3038,7 @@ it is used internally by QPDF when copying objects from other PDF files,
as discussed in `Copying Objects From Other PDF as discussed in `Copying Objects From Other PDF
Files <#ref.foreign-objects>`__. For an example of how to use reserved Files <#ref.foreign-objects>`__. For an example of how to use reserved
objects, search for ``newReserved`` in objects, search for ``newReserved`` in
@1@filename@1@test_driver.cc@2@filename@2@ in qpdf's sources. :file:`test_driver.cc` in qpdf's sources.
.. _ref.foreign-objects: .. _ref.foreign-objects:
@ -3178,7 +3178,7 @@ and then writes the data (possibly modified) to its successor.
Alternatively, a pipeline may be an end-of-the-line pipeline that does Alternatively, a 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 something like store its output to a file or a memory buffer ignoring a
successor. For additional details, look at successor. For additional details, look at
@1@filename@1@Pipeline.hh@2@filename@2@. :file:`Pipeline.hh`.
``QPDF`` can read raw or filtered streams. When reading a filtered ``QPDF`` can read raw or filtered streams. When reading a filtered
stream, the ``QPDF`` class creates a ``Pipeline`` object for one of each stream, the ``QPDF`` class creates a ``Pipeline`` object for one of each
@ -3196,7 +3196,7 @@ Object Accessor Methods
For general information about how to access instances of For general information about how to access instances of
``QPDFObjectHandle``, please see the comments in ``QPDFObjectHandle``, please see the comments in
@1@filename@1@QPDFObjectHandle.hh@2@filename@2@. Search for "Accessor :file:`QPDFObjectHandle.hh`. Search for "Accessor
methods". This section provides a more in-depth discussion of the methods". This section provides a more in-depth discussion of the
behavior and the rationale for the behavior. behavior and the rationale for the behavior.
@ -3332,7 +3332,7 @@ this optimization was initially motivated by the need to create
linearized files, we are using these terms separately. linearized files, we are using these terms separately.
PDF file optimization is implemented in the PDF file optimization is implemented in the
@1@filename@1@QPDF_optimization.cc@2@filename@2@ source file. That file :file:`QPDF_optimization.cc` source file. That file
is richly commented and serves as the primary reference for the is richly commented and serves as the primary reference for the
optimization process. optimization process.
@ -3654,7 +3654,7 @@ Release Notes
============= =============
For a detailed list of changes, please see the file For a detailed list of changes, please see the file
@1@filename@1@ChangeLog@2@filename@2@ in the source distribution. :file:`ChangeLog` in the source distribution.
10.5.0: XXX Month dd, YYYY 10.5.0: XXX Month dd, YYYY
- Library Enhancements - Library Enhancements
@ -3664,14 +3664,14 @@ For a detailed list of changes, please see the file
object is not of the expected type. These warnings now have an object is not of the expected type. These warnings now have an
error code of ``qpdf_e_object`` instead of error code of ``qpdf_e_object`` instead of
``qpdf_e_damaged_pdf``. Also, comments have been added to ``qpdf_e_damaged_pdf``. Also, comments have been added to
@1@filename@1@QPDFObjectHandle.hh@2@filename@2@ to explain in :file:`QPDFObjectHandle.hh` to explain in
more detail what the behavior is. See `Object Accessor more detail what the behavior is. See `Object Accessor
Methods <#ref.object-accessors>`__ for a more in-depth Methods <#ref.object-accessors>`__ for a more in-depth
discussion. discussion.
- Overhaul error handling for the object handle functions in the - Overhaul error handling for the object handle functions in the
C API. See comments in the "Object handling" section of C API. See comments in the "Object handling" section of
@1@filename@1@include/qpdf/qpdf-c.h@2@filename@2@ for details. :file:`include/qpdf/qpdf-c.h` for details.
In particular, exceptions thrown by the underlying C++ code In particular, exceptions thrown by the underlying C++ code
when calling object accessors are caught and converted into when calling object accessors are caught and converted into
errors. The errors can be trapped by registering an error errors. The errors can be trapped by registering an error
@ -3754,7 +3754,7 @@ For a detailed list of changes, please see the file
- When adding a page that already exists, make a shallow copy - When adding a page that already exists, make a shallow copy
instead of throwing an exception. This makes the library instead of throwing an exception. This makes the library
behavior consistent with the CLI behavior. See behavior consistent with the CLI behavior. See
@1@filename@1@ChangeLog@2@filename@2@ for additional notes. :file:`ChangeLog` for additional notes.
10.3.1: March 11, 2021 10.3.1: March 11, 2021
- Bug Fixes - Bug Fixes
@ -3799,7 +3799,7 @@ For a detailed list of changes, please see the file
method added in 10.2.0. The majority of the API changes are in method added in 10.2.0. The majority of the API changes are in
methods most people would never call and that will hopefully be methods most people would never call and that will hopefully be
superseded by higher-level interfaces for handling page copies. superseded by higher-level interfaces for handling page copies.
Please see the @1@filename@1@ChangeLog@2@filename@2@ file for Please see the :file:`ChangeLog` file for
details. details.
- The method ``QPDF::numWarnings`` was added so that you can tell - The method ``QPDF::numWarnings`` was added so that you can tell
@ -3905,16 +3905,16 @@ For a detailed list of changes, please see the file
- This release includes numerous additions to the API. Not all - This release includes numerous additions to the API. Not all
changes are listed here. Please see the changes are listed here. Please see the
@1@filename@1@ChangeLog@2@filename@2@ file in the source :file:`ChangeLog` file in the source
distribution for a comprehensive list. Highlights appear below. distribution for a comprehensive list. Highlights appear below.
- Add ``QPDFObjectHandle::ditems()`` and - Add ``QPDFObjectHandle::ditems()`` and
``QPDFObjectHandle::aitems()`` that enable C++-style iteration, ``QPDFObjectHandle::aitems()`` that enable C++-style iteration,
including range-for iteration, over dictionary and array including range-for iteration, over dictionary and array
QPDFObjectHandles. See comments in QPDFObjectHandles. See comments in
@1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@ :file:`include/qpdf/QPDFObjectHandle.hh`
and and
@1@filename@1@examples/pdf-name-number-tree.cc@2@filename@2@ :file:`examples/pdf-name-number-tree.cc`
for details. for details.
- Add ``QPDFObjectHandle::copyStream`` for making a copy of a - Add ``QPDFObjectHandle::copyStream`` for making a copy of a
@ -3925,13 +3925,13 @@ For a detailed list of changes, please see the file
``QPDFEmbeddedFileDocumentHelper``, ``QPDFEmbeddedFileDocumentHelper``,
``QPDFFileSpecObjectHelper``, and ``QPDFEFStreamObjectHelper``. ``QPDFFileSpecObjectHelper``, and ``QPDFEFStreamObjectHelper``.
See their respective headers for details and See their respective headers for details and
@1@filename@1@examples/pdf-attach-file.cc@2@filename@2@ for an :file:`examples/pdf-attach-file.cc` for an
example. example.
- Add a version of ``QPDFObjectHandle::parse`` that takes a - Add a version of ``QPDFObjectHandle::parse`` that takes a
``QPDF`` pointer as context so that it can parse strings ``QPDF`` pointer as context so that it can parse strings
containing indirect object references. This is illustrated in containing indirect object references. This is illustrated in
@1@filename@1@examples/pdf-attach-file.cc@2@filename@2@. :file:`examples/pdf-attach-file.cc`.
- Re-implement ``QPDFNameTreeObjectHelper`` and - Re-implement ``QPDFNameTreeObjectHelper`` and
``QPDFNumberTreeObjectHelper`` to be more efficient, add an ``QPDFNumberTreeObjectHelper`` to be more efficient, add an
@ -3948,12 +3948,12 @@ For a detailed list of changes, please see the file
- The ``QPDFMatrix`` class, formerly a private, internal class, - The ``QPDFMatrix`` class, formerly a private, internal class,
has been added to the public API. See has been added to the public API. See
@1@filename@1@include/qpdf/QPDFMatrix.hh@2@filename@2@ for :file:`include/qpdf/QPDFMatrix.hh` for
details. This class is for working with transformation details. This class is for working with transformation
matrices. Some methods in ``QPDFPageObjectHelper`` make use of matrices. Some methods in ``QPDFPageObjectHelper`` make use of
this to make information about transformation matrices this to make information about transformation matrices
available. For an example, see available. For an example, see
@1@filename@1@examples/pdf-overlay-page.cc@2@filename@2@. :file:`examples/pdf-overlay-page.cc`.
- Several new methods were added to - Several new methods were added to
``QPDFAcroFormDocumentHelper`` for adding, removing, getting ``QPDFAcroFormDocumentHelper`` for adding, removing, getting
@ -4013,7 +4013,7 @@ For a detailed list of changes, please see the file
and register it with ``QPDF`` so that regular library methods, and register it with ``QPDF`` so that regular library methods,
including those used by ``QPDFWriter``, can decode streams with including those used by ``QPDFWriter``, can decode streams with
filters not directly supported by the library. The example filters not directly supported by the library. The example
@1@filename@1@examples/pdf-custom-filter.cc@2@filename@2@ :file:`examples/pdf-custom-filter.cc`
illustrates how to use this capability. illustrates how to use this capability.
- Add methods to ``QPDFPageObjectHelper`` to iterate through - Add methods to ``QPDFPageObjectHelper`` to iterate through
@ -4023,7 +4023,7 @@ For a detailed list of changes, please see the file
- Enhance several methods in ``QPDFPageObjectHelper`` to work - Enhance several methods in ``QPDFPageObjectHelper`` to work
with form XObjects as well as pages, as noted in comments. See with form XObjects as well as pages, as noted in comments. See
@1@filename@1@ChangeLog@2@filename@2@ for a full list. :file:`ChangeLog` for a full list.
- Rename some functions in ``QPDFPageObjectHelper``, while - Rename some functions in ``QPDFPageObjectHelper``, while
keeping old names for compatibility: keeping old names for compatibility:
@ -4172,7 +4172,7 @@ For a detailed list of changes, please see the file
been moved from ``ifdefs`` to an autoconf been moved from ``ifdefs`` to an autoconf
test. If you are using your own build system, you will need to test. If you are using your own build system, you will need to
provide a value for ``LL_FMT`` in provide a value for ``LL_FMT`` in
@1@filename@1@libqpdf/qpdf/qpdf-config.h@2@filename@2@, which :file:`libqpdf/qpdf/qpdf-config.h`, which
would typically be ``"%lld"`` or, for some Windows compilers, would typically be ``"%lld"`` or, for some Windows compilers,
``"%I64d"``. ``"%I64d"``.
@ -4215,7 +4215,7 @@ For a detailed list of changes, please see the file
- Enhancements - Enhancements
- Improve the @1@filename@1@pdf-invert-images@2@filename@2@ - Improve the :file:`pdf-invert-images`
example to avoid having to load all the images into RAM at the example to avoid having to load all the images into RAM at the
same time. same time.
@ -4525,7 +4525,7 @@ For a detailed list of changes, please see the file
- Library Enhancements - Library Enhancements
- A new namespace ``QIntC``, provided by - A new namespace ``QIntC``, provided by
@1@filename@1@qpdf/QIntC.hh@2@filename@2@, provides safe :file:`qpdf/QIntC.hh`, provides safe
conversion methods between different integer types. These conversion methods between different integer types. These
conversion methods do range checking to ensure that the cast conversion methods do range checking to ensure that the cast
can be performed with no loss of information. Every use of can be performed with no loss of information. Every use of
@ -4599,7 +4599,7 @@ For a detailed list of changes, please see the file
hexadecimal digits, which is invalid in PDF 1.2 and above, are hexadecimal digits, which is invalid in PDF 1.2 and above, are
properly handled by the library: a warning is generated, and properly handled by the library: a warning is generated, and
the name token is properly preserved, even if invalid, in the the name token is properly preserved, even if invalid, in the
output. See @1@filename@1@ChangeLog@2@filename@2@ for a more output. See :file:`ChangeLog` for a more
complete description of this change. complete description of this change.
- Bug Fixes - Bug Fixes
@ -4654,8 +4654,8 @@ For a detailed list of changes, please see the file
files but not others. files but not others.
- If :command:`pkg-config` is available, use it to - If :command:`pkg-config` is available, use it to
locate @1@filename@1@libjpeg@2@filename@2@ and locate :file:`libjpeg` and
@1@filename@1@zlib@2@filename@2@ dependencies, falling back on :file:`zlib` dependencies, falling back on
old behavior if unsuccessful. old behavior if unsuccessful.
- Other Notes - Other Notes
@ -4796,7 +4796,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
:command:`qpdf in.pdf --pages . 1-2 -- out.pdf` :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 :file:`in.pdf`
in the command. in the command.
- When encrypting with 128-bit and 256-bit encryption, new - When encrypting with 128-bit and 256-bit encryption, new
@ -4853,7 +4853,7 @@ For a detailed list of changes, please see the file
- Add new versions of - Add new versions of
``QPDFWriter::setR{3,4,5,6}EncryptionParameters`` that allow ``QPDFWriter::setR{3,4,5,6}EncryptionParameters`` that allow
more granular setting of permissions bits. See more granular setting of permissions bits. See
@1@filename@1@QPDFWriter.hh@2@filename@2@ for details. :file:`QPDFWriter.hh` for details.
- Add new versions of the transcoders from UTF-8 to single-byte - Add new versions of the transcoders from UTF-8 to single-byte
coding systems in ``QUtil`` that report success or failure coding systems in ``QUtil`` that report success or failure
@ -4885,7 +4885,7 @@ For a detailed list of changes, please see the file
copied immediately instead of lazily. This option uses more copied immediately instead of lazily. This option uses more
memory but allows the source object to go out of scope before memory but allows the source object to go out of scope before
the destination object is written in all cases. See comments in the destination object is written in all cases. See comments in
@1@filename@1@QPDF.hh@2@filename@2@ for details. :file:`QPDF.hh` for details.
- Add method ``QPDFPageObjectHelper::getAttribute`` for - Add method ``QPDFPageObjectHelper::getAttribute`` for
retrieving an attribute from the page dictionary taking retrieving an attribute from the page dictionary taking
@ -5025,10 +5025,10 @@ For a detailed list of changes, please see the file
- Ordinarily qpdf treats an argument of the form - Ordinarily qpdf treats an argument of the form
@1@option@1@@file@2@option@2@ to mean that command-line options @1@option@1@@file@2@option@2@ to mean that command-line options
should be read from @1@filename@1@file@2@filename@2@. Now, if should be read from :file:`file`. Now, if
@1@filename@1@file@2@filename@2@ does not exist but :file:`file` does not exist but
@1@filename@1@@file@2@filename@2@ does, qpdf will treat :file:`@file` does, qpdf will treat
@1@filename@1@@file@2@filename@2@ as a regular option. This :file:`@file` as a regular option. This
makes it possible to work more easily with PDF files whose makes it possible to work more easily with PDF files whose
names happen to start with the ``@`` character. names happen to start with the ``@`` character.
@ -5040,11 +5040,11 @@ For a detailed list of changes, please see the file
case is when the source stream gets is data using a case is when the source stream gets is data using a
QPDFObjectHandle::StreamDataProvider. For a more in-depth QPDFObjectHandle::StreamDataProvider. For a more in-depth
discussion, see comments around ``copyForeignObject`` in discussion, see comments around ``copyForeignObject`` in
@1@filename@1@QPDF.hh@2@filename@2@. :file:`QPDF.hh`.
- Add new method ``QPDFWriter::getFinalVersion()``, which returns - Add new method ``QPDFWriter::getFinalVersion()``, which returns
the PDF version that will ultimately be written to the final the PDF version that will ultimately be written to the final
file. See comments in @1@filename@1@QPDFWriter.hh@2@filename@2@ file. See comments in :file:`QPDFWriter.hh`
for some restrictions on its use. for some restrictions on its use.
- Add several methods for transcoding strings to some of the - Add several methods for transcoding strings to some of the
@ -5057,14 +5057,14 @@ For a detailed list of changes, please see the file
- Add new methods to ``QPDFAnnotationObjectHelper`` and - Add new methods to ``QPDFAnnotationObjectHelper`` and
``QPDFFormFieldObjectHelper`` for querying flags and ``QPDFFormFieldObjectHelper`` for querying flags and
interpretation of different field types. Define constants in interpretation of different field types. Define constants in
@1@filename@1@qpdf/Constants.h@2@filename@2@ to help with :file:`qpdf/Constants.h` to help with
interpretation of flag values. interpretation of flag values.
- Add new methods - Add new methods
``QPDFAcroFormDocumentHelper::generateAppearancesIfNeeded`` and ``QPDFAcroFormDocumentHelper::generateAppearancesIfNeeded`` and
``QPDFFormFieldObjectHelper::generateAppearance`` for ``QPDFFormFieldObjectHelper::generateAppearance`` for
generating appearance streams. See discussion in generating appearance streams. See discussion in
@1@filename@1@QPDFFormFieldObjectHelper.hh@2@filename@2@ for :file:`QPDFFormFieldObjectHelper.hh` for
limitations. limitations.
- Add two new helper functions for dealing with resource - Add two new helper functions for dealing with resource
@ -5141,7 +5141,7 @@ For a detailed list of changes, please see the file
- 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
distribution's default location. You can find sample completion distribution's default location. You can find sample completion
files to install in the @1@filename@1@completions@2@filename@2@ files to install in the :file:`completions`
directory. directory.
8.2.1: August 18, 2018 8.2.1: August 18, 2018
@ -5195,8 +5195,8 @@ For a detailed list of changes, please see the file
- Build Changes - Build Changes
- For the mingw builds, change the name of the DLL import library - For the mingw builds, change the name of the DLL import library
from @1@filename@1@libqpdf.a@2@filename@2@ to from :file:`libqpdf.a` to
@1@filename@1@libqpdf.dll.a@2@filename@2@ to more accurately :file:`libqpdf.dll.a` to more accurately
reflect that it is an import library rather than a static reflect that it is an import library rather than a static
library. This potentially clears the way for supporting a library. This potentially clears the way for supporting a
static library in the future, though presently, the qpdf static library in the future, though presently, the qpdf
@ -5274,7 +5274,7 @@ For a detailed list of changes, please see the file
way to perform operations on pages rather than calling the old way to perform operations on pages rather than calling the old
methods in ``QPDFObjectHandle`` and ``QPDF`` directly. Comments methods in ``QPDFObjectHandle`` and ``QPDF`` directly. Comments
in the header files direct you to the new interfaces. Please in the header files direct you to the new interfaces. Please
see the header files and @1@filename@1@ChangeLog@2@filename@2@ see the header files and :file:`ChangeLog`
for additional details. for additional details.
- Add three new object helper class: ``QPDFPageObjectHelper`` for - Add three new object helper class: ``QPDFPageObjectHelper`` for
@ -5284,7 +5284,7 @@ For a detailed list of changes, please see the file
some useful, basic functionality. some useful, basic functionality.
- A new example program - A new example program
@1@filename@1@examples/pdf-set-form-values.cc@2@filename@2@ has :file:`examples/pdf-set-form-values.cc` has
been added that illustrates use of the new document and object been added that illustrates use of the new document and object
helpers. helpers.
@ -5369,7 +5369,7 @@ For a detailed list of changes, please see the file
- 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
@1@filename@1@ChangeLog@2@filename@2@ file. Most of the changes :file:`ChangeLog` file. Most of the changes
result in improvements to qpdf's ability handle erroneous result in improvements to qpdf's ability handle erroneous
files. It is also possible for programs to handle whitespace, files. It is also possible for programs to handle whitespace,
comments, and inline images as tokens. comments, and inline images as tokens.
@ -5379,10 +5379,10 @@ For a detailed list of changes, please see the file
the developer to provide token handlers. Token filters can be the developer to provide token handlers. Token filters can be
used with several different methods in ``QPDFObjectHandle`` as used with several different methods in ``QPDFObjectHandle`` as
well as with a lower-level interface. See comments in well as with a lower-level interface. See comments in
@1@filename@1@QPDFObjectHandle.hh@2@filename@2@ as well as the :file:`QPDFObjectHandle.hh` as well as the
new examples new examples
@1@filename@1@examples/pdf-filter-tokens.cc@2@filename@2@ and :file:`examples/pdf-filter-tokens.cc` and
@1@filename@1@examples/pdf-count-strings.cc@2@filename@2@ for :file:`examples/pdf-count-strings.cc` for
details. details.
7.1.1: February 4, 2018 7.1.1: February 4, 2018
@ -5407,7 +5407,7 @@ For a detailed list of changes, please see the file
the discussion of @1@option@1@--password-is-hex-key@2@option@2@ in the discussion of @1@option@1@--password-is-hex-key@2@option@2@ in
`Basic Options <#ref.basic-options>`__ or the comments around `Basic Options <#ref.basic-options>`__ or the comments around
``QPDF::setPasswordIsHexKey`` in ``QPDF::setPasswordIsHexKey`` in
@1@filename@1@QPDF.hh@2@filename@2@ for additional details. :file:`QPDF.hh` for additional details.
- Bug fix: numbers ending with a trailing decimal point are now - Bug fix: numbers ending with a trailing decimal point are now
properly recognized as numbers. properly recognized as numbers.
@ -5520,7 +5520,7 @@ For a detailed list of changes, please see the file
- New ``Pipeline`` types ``Pl_RunLength`` and ``Pl_DCT`` are - New ``Pipeline`` types ``Pl_RunLength`` and ``Pl_DCT`` are
available for developers who wish to produce or consume available for developers who wish to produce or consume
RunLength or DCT stream data directly. The RunLength or DCT stream data directly. The
@1@filename@1@examples/pdf-create.cc@2@filename@2@ example :file:`examples/pdf-create.cc` example
illustrates their use. illustrates their use.
- ``QPDFWriter::setCompressStreams`` and - ``QPDFWriter::setCompressStreams`` and
@ -5643,8 +5643,8 @@ For a detailed list of changes, please see the file
preferred over ``QPDFObjectHandle::getObjectID()`` and preferred over ``QPDFObjectHandle::getObjectID()`` and
``QPDFObjectHandle::getGeneration()`` as it makes it less likely ``QPDFObjectHandle::getGeneration()`` as it makes it less likely
for people to accidentally write code that ignores the generation for people to accidentally write code that ignores the generation
number. See @1@filename@1@QPDF.hh@2@filename@2@ and number. See :file:`QPDF.hh` and
@1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for additional :file:`QPDFObjectHandle.hh` for additional
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
@ -5658,15 +5658,15 @@ For a detailed list of changes, please see the file
- Various enhancements were made to support different types of - Various enhancements were made to support different types of
broken files or broken readers. Details can be found in broken files or broken readers. Details can be found in
@1@filename@1@ChangeLog@2@filename@2@. :file:`ChangeLog`.
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 :file:`.la` files generated by libtool are now
installed by qpdf's :command:`make install` 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 :file:`.la` files, you must remove them as
part of your packaging process. part of your packaging process.
- Major enhancement: API enhancements have been made to support - Major enhancement: API enhancements have been made to support
@ -5676,7 +5676,7 @@ For a detailed list of changes, please see the file
- ``QPDFObjectHandle::parseContentStream`` method parses objects - ``QPDFObjectHandle::parseContentStream`` method parses objects
in a content stream and calls handlers in a callback class. The in a content stream and calls handlers in a callback class. The
example example
@1@filename@1@examples/pdf-parse-content.cc@2@filename@2@ :file:`examples/pdf-parse-content.cc`
illustrates how this may be used. illustrates how this may be used.
- ``QPDFObjectHandle`` can now represent operators and inline - ``QPDFObjectHandle`` can now represent operators and inline
@ -5699,7 +5699,7 @@ For a detailed list of changes, please see the file
versions. versions.
- Warning flags have been moved into a separate variable in - Warning flags have been moved into a separate variable in
@1@filename@1@autoconf.mk@2@filename@2@ :file:`autoconf.mk`
- The configure flag @1@option@1@--enable-werror@2@option@2@ work - The configure flag @1@option@1@--enable-werror@2@option@2@ work
for Microsoft compilers for Microsoft compilers
@ -5718,7 +5718,7 @@ For a detailed list of changes, please see the file
- Some internal limits have been removed in code that converts - Some internal limits have been removed in code that converts
numbers to strings. This is largely invisible to users, but it numbers to strings. This is largely invisible to users, but it
does trigger a bug in some older versions of mingw-w64's C++ does trigger a bug in some older versions of mingw-w64's C++
library. See @1@filename@1@README-windows.md@2@filename@2@ in library. See :file:`README-windows.md` in
the source distribution if you think this may affect you. The the source distribution if you think this may affect you. The
copy of the DLL distributed with qpdf's binary distribution is copy of the DLL distributed with qpdf's binary distribution is
not affected by this problem. not affected by this problem.
@ -5745,7 +5745,7 @@ For a detailed list of changes, please see the file
- Fix detection of binary attachments in test suite to avoid false - Fix detection of binary attachments in test suite to avoid false
test failures on some platforms. test failures on some platforms.
- Add clarifying comment in @1@filename@1@QPDF.hh@2@filename@2@ to - Add clarifying comment in :file:`QPDF.hh` to
methods that return the user password explaining that it is no methods that return the user password explaining that it is no
longer possible with newer encryption formats to recover the user longer possible with newer encryption formats to recover the user
password knowing the owner password. In earlier encryption password knowing the owner password. In earlier encryption
@ -5938,14 +5938,14 @@ For a detailed list of changes, please see the file
- The ``QPDF::emptyPDF`` can be used to allow creation of PDF files - The ``QPDF::emptyPDF`` can be used to allow creation of PDF files
from scratch. The example from scratch. The example
@1@filename@1@examples/pdf-create.cc@2@filename@2@ illustrates how :file:`examples/pdf-create.cc` illustrates how
it can be used. it can be used.
- Several methods to take ``PointerHolder<Buffer>`` can now also - Several methods to take ``PointerHolder<Buffer>`` can now also
accept ``std::string`` arguments. accept ``std::string`` arguments.
- Many new convenience methods have been added to the library, most - Many new convenience methods have been added to the library, most
in ``QPDFObjectHandle``. See @1@filename@1@ChangeLog@2@filename@2@ in ``QPDFObjectHandle``. See :file:`ChangeLog`
for a full list. for a full list.
- When building on a platform that supports ELF shared libraries - When building on a platform that supports ELF shared libraries
@ -5954,23 +5954,23 @@ For a detailed list of changes, please see the file
@1@option@1@--disable-ld-version-script@2@option@2@ to @1@option@1@--disable-ld-version-script@2@option@2@ to
:command:`./configure`. :command:`./configure`.
- The file @1@filename@1@libqpdf.pc@2@filename@2@ is now installed - The file :file:`libqpdf.pc` is now installed
to support :command:`pkg-config`. 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
only when changing the actual PDF output generated by qpdf. You only when changing the actual PDF output generated by qpdf. You
should enable them if you are making deep changes to qpdf itself. should enable them if you are making deep changes to qpdf itself.
See @1@filename@1@README.md@2@filename@2@ for details. See :file:`README.md` 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
:command:`./configure` 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. :file:`README.md` for details.
- When qpdf's test suite fails, failures are not printed to the - When qpdf's test suite fails, failures are not printed to the
terminal anymore by default. Instead, find them in terminal anymore by default. Instead, find them in
@1@filename@1@build/qtest.log@2@filename@2@. For packagers who are :file:`build/qtest.log`. 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
:command:`./configure` to restore the old behavior. :command:`./configure` to restore the old behavior.
@ -6046,7 +6046,7 @@ For a detailed list of changes, please see the file
library to present to the user in some other way. Note that QPDF library to present to the user in some other way. Note that QPDF
does not write to ``std::cout`` (or the specified output stream) does not write to ``std::cout`` (or the specified output stream)
except where explicitly mentioned in except where explicitly mentioned in
@1@filename@1@QPDF.hh@2@filename@2@, and that the only use of the :file:`QPDF.hh`, and that the only use of the
error stream is for warnings. Note also that output of warnings is error stream is for warnings. Note also that output of warnings is
suppressed when ``setSuppressWarnings(true)`` is called. suppressed when ``setSuppressWarnings(true)`` is called.
@ -6143,14 +6143,14 @@ For a detailed list of changes, please see the file
excellent suggestions on improving the interface. excellent suggestions on improving the interface.
For programming to the C interface, please see the header file For programming to the C interface, please see the header file
@1@filename@1@qpdf/qpdf-c.h@2@filename@2@ and the example :file:`qpdf/qpdf-c.h` and the example
@1@filename@1@examples/pdf-linearize.c@2@filename@2@. :file:`examples/pdf-linearize.c`.
- Žarko Gajić has written a Delphi wrapper for qpdf, which can be - Žarko Gajić has written a Delphi wrapper for qpdf, which can be
downloaded from qpdf's download side. Žarko's Delphi wrapper is downloaded from qpdf's download side. Žarko's Delphi wrapper is
released with the same licensing terms as qpdf itself and comes released with the same licensing terms as qpdf itself and comes
with this disclaimer: "Delphi wrapper unit with this disclaimer: "Delphi wrapper unit
@1@filename@1@qpdf.pas@2@filename@2@ created by Žarko Gajić :file:`qpdf.pas` created by Žarko Gajić
(http://zarko-gajic.iz.hr/). Use at your own risk and for whatever (http://zarko-gajic.iz.hr/). Use at your own risk and for whatever
purpose you want. No support is provided. Sample code is purpose you want. No support is provided. Sample code is
provided." provided."
@ -6214,14 +6214,14 @@ 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-:command:`bash` non-:command:`bash`
@1@filename@1@/bin/sh@2@filename@2@ and with Perl 5.10. No changes :file:`/bin/sh` 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.
2.0.1: May 6, 2008 2.0.1: May 6, 2008
- No changes in functionality or interface. This release includes - No changes in functionality or interface. This release includes
fixes to the source code so that qpdf compiles properly and passes fixes to the source code so that qpdf compiles properly and passes
its test suite on a broader range of platforms. See its test suite on a broader range of platforms. See
@1@filename@1@ChangeLog@2@filename@2@ in the source distribution :file:`ChangeLog` in the source distribution
for details. for details.
2.0: April 29, 2008 2.0: April 29, 2008
@ -6244,7 +6244,7 @@ files.
internal errors and ``std::runtime_error`` for runtime errors in internal errors and ``std::runtime_error`` for runtime errors in
favor of the now removed ``QEXC`` classes used in previous versions. favor of the now removed ``QEXC`` classes used in previous versions.
The ``QEXC`` exception classes predated the addition of the The ``QEXC`` exception classes predated the addition of the
@1@filename@1@<stdexcept>@2@filename@2@ header file to the C++ :file:`<stdexcept>` header file to the C++
standard library. Most of the exceptions thrown by the qpdf library standard library. Most of the exceptions thrown by the qpdf library
itself are still of type ``QPDFExc`` which is now derived from itself are still of type ``QPDFExc`` which is now derived from
``std::runtime_error``. Programs that caught an instance of ``std::runtime_error``. Programs that caught an instance of
@ -6255,7 +6255,7 @@ files.
error condition and provides interfaces for querying them. Among the error condition and provides interfaces for querying them. Among the
fields is a numeric error code that can help applications act fields is a numeric error code that can help applications act
differently on (a small number of) different error conditions. See differently on (a small number of) different error conditions. See
@1@filename@1@QPDFExc.hh@2@filename@2@ for details. :file:`QPDFExc.hh` for details.
- Warnings can be retrieved from qpdf as instances of ``QPDFExc`` - Warnings can be retrieved from qpdf as instances of ``QPDFExc``
instead of strings. instead of strings.
@ -6278,7 +6278,7 @@ files.
- The enumerated types that used to be nested in ``QPDFWriter`` have - The enumerated types that used to be nested in ``QPDFWriter`` have
moved to top-level enumerated types and are now defined in the file moved to top-level enumerated types and are now defined in the file
@1@filename@1@qpdf/Constants.h@2@filename@2@. This enables them to be :file:`qpdf/Constants.h`. This enables them to be
shared by both the C and C++ interfaces. shared by both the C and C++ interfaces.
.. _ref.upgrading-to-3.0: .. _ref.upgrading-to-3.0: