octoleo
/
qpdf
mirror of https://github.com/qpdf/qpdf.git
2
1
Fork 0
Code Issues Releases Wiki Activity

Replace things previously marked with <filename> with :file:`...`

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
Correct placement of comment: <!-- This section is referenced in QPDFObjectHandle.hh -->
<filename> -> :file: (allows {x})
<option> -> :samp: (allows {x})
<firstterm> -> just use literal
<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
the @1@filename@1@README.md@2@filename@2@ and
@1@filename@1@INSTALL@2@filename@2@ files in the source distribution.
the :file:`README.md` and
:file:`INSTALL` files in the source distribution.
.. _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
installation to install to a temporary location, as is common with many
open source packages. Please see also the
@1@filename@1@README.md@2@filename@2@ and
@1@filename@1@INSTALL@2@filename@2@ files in the source distribution.
:file:`README.md` and
:file:`INSTALL` files in the source distribution.
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.
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
@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
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
hand-crafted non-recursive Makefile that requires gnu make. If you're
really interested, please read the comments in the top-level
@1@filename@1@Makefile@2@filename@2@.
:file:`Makefile`.
.. _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
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
default crypto provider, and various symbols starting with
``USE_CRYPTO_``, at least one of which has to be enabled. Additionally,
you must compile the source files that implement a crypto provider. To
get a list of those files, look at
@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
undefined, you can completely ignore the source files that belong to a
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,
some of which were added or renamed from earlier versions, to your
build, and you can ignore
@1@filename@1@QPDFCrypto_gnutls.cc@2@filename@2@. Always consult
@1@filename@1@libqpdf/build.mk@2@filename@2@ to get the list of source
:file:`QPDFCrypto_gnutls.cc`. Always consult
:file:`libqpdf/build.mk` to get the list of source
files you need to build.
.. _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
provider, you have to create a class derived from ``QPDFCryptoImpl`` and
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:
@ -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
install them wherever your distribution expects such files to go. You
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
@1@filename@1@examples@2@filename@2@ directory along with qpdf
:file:`examples` directory along with qpdf
development packages.
.. _ref.using:
@ -625,10 +625,10 @@ needed transformations.
If specified, the output file name should be omitted. This option
tells qpdf to replace the input file with the output. It does this by
writing to
@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.
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@
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.
- 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
extension.
@ -824,21 +824,21 @@ needed transformations.
Page ranges are a single number in the case of single-page groups or
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`
would generate files @1@filename@1@01-out@2@filename@2@ through
@1@filename@1@12-out@2@filename@2@
would generate files :file:`01-out` through
:file:`12-out`
- :command:`qpdf --split-pages=2 infile.pdf
outfile.pdf` would generate files
@1@filename@1@outfile-01-02.pdf@2@filename@2@ through
@1@filename@1@outfile-11-12.pdf@2@filename@2@
:file:`outfile-01-02.pdf` through
:file:`outfile-11-12.pdf`
- :command:`qpdf --split-pages infile.pdf
something.else` would generate files
@1@filename@1@something.else-01@2@filename@2@ through
@1@filename@1@something.else-12@2@filename@2@
:file:`something.else-01` through
:file:`something.else-12`
Note that outlines, threads, and other global features of the
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.
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.
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
of @1@option@1@--pages@2@option@2@ so that the specified files, as
modified by page ranges, are collated rather than concatenated. For
example, if you add the files @1@filename@1@odd.pdf@2@filename@2@ and
@1@filename@1@even.pdf@2@filename@2@ containing odd and even pages of a
example, if you add the files :file:`odd.pdf` and
:file:`even.pdf` containing odd and even pages of a
document respectively, you could run :command:`qpdf --collate odd.pdf
--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
@ -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
@1@option@1@--empty@2@option@2@ as the primary input file to avoid
copying all of that from the first file. For example, to take pages 1
through 5 from a @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
::
@ -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@
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
::
@ -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@
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@file2.pdf@2@filename@2@ in reverse, taking document-level
metadata from @1@filename@1@file2.pdf@2@filename@2@, you would run
:file:`file1.pdf` and pages 11 through 15 from
:file:`file2.pdf` in reverse, taking document-level
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@
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
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
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,
@1@filename@1@encrypted.pdf@2@filename@2@ and
@1@filename@1@./encrypted.pdf@2@filename@2@ are separated files. These
:file:`encrypted.pdf` and
:file:`./encrypted.pdf` are separated files. These
are all corner cases that most users should hopefully never have to be
bothered with.
@ -1304,15 +1304,15 @@ Here are some examples.
- :command:`--overlay o.pdf --to=1-5 --from=1-3 --repeat=4
--`: overlay the first three pages from file
@1@filename@1@o.pdf@2@filename@2@ onto the first three pages of the
output, then overlay page 4 from @1@filename@1@o.pdf@2@filename@2@
:file:`o.pdf` onto the first three pages of the
output, then overlay page 4 from :file:`o.pdf`
onto pages 4 and 5 of the output. Leave remaining output pages
untouched.
- :command:`--underlay footer.pdf --from= --repeat=1,2
--`: Underlay page 1 of
@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
:file:`footer.pdf` on all odd output pages, and
underlay page 2 of :file:`footer.pdf` on all even
output pages.
.. _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
when everything is valid, so if you are using this to
programmatically validate files in bulk, it is safe to run without
output redirected to @1@filename@1@/dev/null@2@filename@2@ and just
output redirected to :file:`/dev/null` and just
check for a 0 exit code.
The @1@option@1@--raw-stream-data@2@option@2@ and
@ -2219,23 +2219,23 @@ Using QPDF from C++
-------------------
The source tree for the qpdf package has an
@1@filename@1@examples@2@filename@2@ directory that contains a few
example programs. The @1@filename@1@qpdf/qpdf.cc@2@filename@2@ source
:file:`examples` directory that contains a few
example programs. The :file:`qpdf/qpdf.cc` source
file also serves as a useful example since it exercises almost all of
the qpdf library's public interface. The best source of documentation on
the library itself is reading comments in
@1@filename@1@include/qpdf/QPDF.hh@2@filename@2@,
@1@filename@1@include/qpdf/QPDFWriter.hh@2@filename@2@, and
@1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@.
:file:`include/qpdf/QPDF.hh`,
:file:`include/qpdf/QPDFWriter.hh`, and
:file:`include/qpdf/QPDFObjectHandle.hh`.
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
@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
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.
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"
The qpdf library includes a "C" language interface that provides a
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
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
@ -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
representation of the object. Existing instances of ``QPDFObjectHandle``
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
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
walking the page tree and returning a vector of all page objects. For
full details, please see the header files
@1@filename@1@QPDF.hh@2@filename@2@ and
@1@filename@1@QPDFObjectHandle.hh@2@filename@2@. There are also some
:file:`QPDF.hh` and
:file:`QPDFObjectHandle.hh`. There are also some
additional helper classes that provide higher level API functions for
certain document constructions. These are discussed in `Helper
Classes <#ref.helper-classes>`__.
@ -2697,8 +2697,8 @@ By Convention, document helpers are called
``QPDFSomethingObjectHelper`` and are derived from ``QPDFObjectHelper``.
For details on specific helpers, please see their header files. You can
find them by looking at
@1@filename@1@include/qpdf/QPDF*DocumentHelper.hh@2@filename@2@ and
@1@filename@1@include/qpdf/QPDF*ObjectHelper.hh@2@filename@2@.
:file:`include/qpdf/QPDF*DocumentHelper.hh` and
:file:`include/qpdf/QPDF*ObjectHelper.hh`.
In order to avoid creation of circular dependencies, the following
general guidelines are followed with helper classes:
@ -2790,7 +2790,7 @@ file.
``pdf.processFile("a.pdf");``.
- 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
it is looking before the last ``%%EOF``. After getting to ``trailer``
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.
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
checking and throw a ``std::range_error``, which is subclass of
``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
details on how to do this, please refer to the top-level README.md file
in the source distribution and to comments in
@1@filename@1@QUtil.hh@2@filename@2@.
:file:`QUtil.hh`.
.. _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
individual pages and manipulation of the ``/Pages`` tree itself. For
details, see ``addPage`` and surrounding methods in
@1@filename@1@QPDF.hh@2@filename@2@.
:file:`QPDF.hh`.
.. _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
Files <#ref.foreign-objects>`__. For an example of how to use reserved
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:
@ -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
something like store its output to a file or a memory buffer ignoring a
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
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
``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
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.
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
optimization process.
@ -3654,7 +3654,7 @@ Release Notes
=============
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
- 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
error code of ``qpdf_e_object`` instead of
``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
Methods <#ref.object-accessors>`__ for a more in-depth
discussion.
- Overhaul error handling for the object handle functions in the
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
when calling object accessors are caught and converted into
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
instead of throwing an exception. This makes the library
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
- 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
methods most people would never call and that will hopefully be
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.
- 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
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.
- Add ``QPDFObjectHandle::ditems()`` and
``QPDFObjectHandle::aitems()`` that enable C++-style iteration,
including range-for iteration, over dictionary and array
QPDFObjectHandles. See comments in
@1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@
:file:`include/qpdf/QPDFObjectHandle.hh`
and
@1@filename@1@examples/pdf-name-number-tree.cc@2@filename@2@
:file:`examples/pdf-name-number-tree.cc`
for details.
- Add ``QPDFObjectHandle::copyStream`` for making a copy of a
@ -3925,13 +3925,13 @@ For a detailed list of changes, please see the file
``QPDFEmbeddedFileDocumentHelper``,
``QPDFFileSpecObjectHelper``, and ``QPDFEFStreamObjectHelper``.
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.
- Add a version of ``QPDFObjectHandle::parse`` that takes a
``QPDF`` pointer as context so that it can parse strings
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
``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,
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
matrices. Some methods in ``QPDFPageObjectHelper`` make use of
this to make information about transformation matrices
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
``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,
including those used by ``QPDFWriter``, can decode streams with
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.
- 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
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
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
test. If you are using your own build system, you will need to
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,
``"%I64d"``.
@ -4215,7 +4215,7 @@ For a detailed list of changes, please see the file
- 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
same time.
@ -4525,7 +4525,7 @@ For a detailed list of changes, please see the file
- Library Enhancements
- 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 do range checking to ensure that the cast
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
properly handled by the library: a warning is generated, and
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.
- Bug Fixes
@ -4654,8 +4654,8 @@ For a detailed list of changes, please see the file
files but not others.
- If :command:`pkg-config` is available, use it to
locate @1@filename@1@libjpeg@2@filename@2@ and
@1@filename@1@zlib@2@filename@2@ dependencies, falling back on
locate :file:`libjpeg` and
:file:`zlib` dependencies, falling back on
old behavior if unsuccessful.
- 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 "."
as a shortcut for the primary input file. That way, you can do
:command:`qpdf in.pdf --pages . 1-2 -- out.pdf`
instead of having to repeat @1@filename@1@in.pdf@2@filename@2@
instead of having to repeat :file:`in.pdf`
in the command.
- 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
``QPDFWriter::setR{3,4,5,6}EncryptionParameters`` that allow
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
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
memory but allows the source object to go out of scope before
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
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
@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
@1@filename@1@file@2@filename@2@ does not exist but
@1@filename@1@@file@2@filename@2@ does, qpdf will treat
@1@filename@1@@file@2@filename@2@ as a regular option. This
should be read from :file:`file`. Now, if
:file:`file` does not exist but
:file:`@file` does, qpdf will treat
:file:`@file` as a regular option. This
makes it possible to work more easily with PDF files whose
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
QPDFObjectHandle::StreamDataProvider. For a more in-depth
discussion, see comments around ``copyForeignObject`` in
@1@filename@1@QPDF.hh@2@filename@2@.
:file:`QPDF.hh`.
- Add new method ``QPDFWriter::getFinalVersion()``, which returns
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.
- 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
``QPDFFormFieldObjectHelper`` for querying flags and
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.
- Add new methods
``QPDFAcroFormDocumentHelper::generateAppearancesIfNeeded`` and
``QPDFFormFieldObjectHelper::generateAppearance`` for
generating appearance streams. See discussion in
@1@filename@1@QPDFFormFieldObjectHelper.hh@2@filename@2@ for
:file:`QPDFFormFieldObjectHelper.hh` for
limitations.
- 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
automatically, you can install completion files in the
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.
8.2.1: August 18, 2018
@ -5195,8 +5195,8 @@ For a detailed list of changes, please see the file
- Build Changes
- For the mingw builds, change the name of the DLL import library
from @1@filename@1@libqpdf.a@2@filename@2@ to
@1@filename@1@libqpdf.dll.a@2@filename@2@ to more accurately
from :file:`libqpdf.a` to
:file:`libqpdf.dll.a` to more accurately
reflect that it is an import library rather than a static
library. This potentially clears the way for supporting a
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
methods in ``QPDFObjectHandle`` and ``QPDF`` directly. Comments
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.
- 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.
- 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
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
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
files. It is also possible for programs to handle whitespace,
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
used with several different methods in ``QPDFObjectHandle`` as
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
@1@filename@1@examples/pdf-filter-tokens.cc@2@filename@2@ and
@1@filename@1@examples/pdf-count-strings.cc@2@filename@2@ for
:file:`examples/pdf-filter-tokens.cc` and
:file:`examples/pdf-count-strings.cc` for
details.
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
`Basic Options <#ref.basic-options>`__ or the comments around
``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
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
available for developers who wish to produce or consume
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.
- ``QPDFWriter::setCompressStreams`` and
@ -5643,8 +5643,8 @@ For a detailed list of changes, please see the file
preferred over ``QPDFObjectHandle::getObjectID()`` and
``QPDFObjectHandle::getGeneration()`` as it makes it less likely
for people to accidentally write code that ignores the generation
number. See @1@filename@1@QPDF.hh@2@filename@2@ and
@1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for additional
number. See :file:`QPDF.hh` and
:file:`QPDFObjectHandle.hh` for additional
notes.
- 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
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
- 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.
Before, they were not installed. This means that if your
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.
- 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
in a content stream and calls handlers in a callback class. The
example
@1@filename@1@examples/pdf-parse-content.cc@2@filename@2@
:file:`examples/pdf-parse-content.cc`
illustrates how this may be used.
- ``QPDFObjectHandle`` can now represent operators and inline
@ -5699,7 +5699,7 @@ For a detailed list of changes, please see the file
versions.
- 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
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
numbers to strings. This is largely invisible to users, but it
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
copy of the DLL distributed with qpdf's binary distribution is
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
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
longer possible with newer encryption formats to recover the user
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
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.
- Several methods to take ``PointerHolder<Buffer>`` can now also
accept ``std::string`` arguments.
- 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.
- 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
: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`.
- 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
only when changing the actual PDF output generated by qpdf. You
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
:command:`./configure` or by setting an environment
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
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
@1@option@1@--enable-show-failed-test-output@2@option@2@ option to
: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
does not write to ``std::cout`` (or the specified output stream)
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
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.
For programming to the C interface, please see the header file
@1@filename@1@qpdf/qpdf-c.h@2@filename@2@ and the example
@1@filename@1@examples/pdf-linearize.c@2@filename@2@.
:file:`qpdf/qpdf-c.h` and the example
:file:`examples/pdf-linearize.c`.
- Žarko Gajić has written a Delphi wrapper for qpdf, which can be
downloaded from qpdf's download side. Žarko's Delphi wrapper is
released with the same licensing terms as qpdf itself and comes
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
purpose you want. No support is provided. Sample code is
provided."
@ -6214,14 +6214,14 @@ For a detailed list of changes, please see the file
2.0.2: June 30, 2008
- Update test suite to work properly with a
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.
2.0.1: May 6, 2008
- No changes in functionality or interface. This release includes
fixes to the source code so that qpdf compiles properly and passes
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.
2.0: April 29, 2008
@ -6244,7 +6244,7 @@ files.
internal errors and ``std::runtime_error`` for runtime errors in
favor of the now removed ``QEXC`` classes used in previous versions.
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
itself are still of type ``QPDFExc`` which is now derived from
``std::runtime_error``. Programs that caught an instance of
@ -6255,7 +6255,7 @@ files.
error condition and provides interfaces for querying them. Among the
fields is a numeric error code that can help applications act
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``
instead of strings.
@ -6278,7 +6278,7 @@ files.
- The enumerated types that used to be nested in ``QPDFWriter`` have
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.
.. _ref.upgrading-to-3.0: