mirror of
https://github.com/qpdf/qpdf.git
synced 2024-09-22 01:59:10 +00:00
Update documentation and version numbers
3.0.rc1
This commit is contained in:
parent
5878d17f0d
commit
2280c4f6d1
71
README
71
README
@ -15,11 +15,20 @@ Prerequisites
|
|||||||
|
|
||||||
QPDF depends on external libraries "zlib" and "pcre". These are part
|
QPDF depends on external libraries "zlib" and "pcre". These are part
|
||||||
of virtually all Linux distributions and are readily available;
|
of virtually all Linux distributions and are readily available;
|
||||||
download information appears in the documentation. You can also
|
download information appears in the documentation. For Windows, you
|
||||||
download the external library distributions in source from from qpdf's
|
can download pre-built binary verisons of those libraries for some
|
||||||
download site. For Windows, you can download pre-built binary
|
compilers; see README-windows.txt for additional details.
|
||||||
verisons of those libraries for some compilers; see README-windows.txt
|
|
||||||
for additional details.
|
QPDF requires a C++ compiler that works with STL. Your compiler must
|
||||||
|
also support "long long". Almost all modern compilers do. If you are
|
||||||
|
trying to port qpdf to a compiler that doesn't support long long, you
|
||||||
|
could change all occurrences of "long long" to "long" in the source
|
||||||
|
code, noting that this would break binary compatibility with other
|
||||||
|
builds of qpdf. Doing so would certainly prevent qpdf from working
|
||||||
|
with files larger than 2 GB, but remaining functionality would most
|
||||||
|
likely work fine. If you built qpdf this way and it passed its test
|
||||||
|
suite with large file support disabled, you could be confident that
|
||||||
|
you had an otherwise working qpdf.
|
||||||
|
|
||||||
|
|
||||||
Licensing terms of embedded software
|
Licensing terms of embedded software
|
||||||
@ -49,20 +58,23 @@ For UNIX and UNIX-like systems, you can usually get by with just
|
|||||||
make
|
make
|
||||||
make install
|
make install
|
||||||
|
|
||||||
For more detailed general information, see the "INSTALL" file in this
|
Packagers may set DESTDIR, in which case make install will install
|
||||||
directory.
|
inside of DESTDIR, as is customary with many packages. For more
|
||||||
|
detailed general information, see the "INSTALL" file in this
|
||||||
|
directory. If you are already accustomed to building and installing
|
||||||
|
software that uses autoconf, there's nothing new for you in the
|
||||||
|
INSTALL file.
|
||||||
|
|
||||||
|
|
||||||
Building on Windows
|
Building on Windows
|
||||||
===================
|
===================
|
||||||
|
|
||||||
QPDF is known to build and pass its test suite with mingw (gcc 4.4.0)
|
QPDF is known to build and pass its test suite with mingw (latest
|
||||||
and Microsoft Visual C++ .NET 2008 Express. Either cygwin or MSYS
|
version tested: gcc 4.6.2), mingw64 (latest version tested: 4.7.0) and
|
||||||
plus ActivateState Perl is required to build as well in order to get
|
Microsoft Visual C++ 2010, both 32-bit and 64-bit versions. MSYS plus
|
||||||
make and other related tools. The MSVC works with either cygwin or
|
ActivateState Perl is required to build as well in order to get make
|
||||||
MSYS. The mingw build requires MSYS and will probably not work with
|
and other related tools. See README-windows.txt for details on how to
|
||||||
cygwin.
|
build under Windows, see README-windows.txt.
|
||||||
|
|
||||||
For details on how to build under Windows, see README-windows.txt.
|
|
||||||
|
|
||||||
|
|
||||||
Additional Notes on Build
|
Additional Notes on Build
|
||||||
@ -94,7 +106,10 @@ To learn about using the library, please read comments in the header
|
|||||||
files in include/qpdf, especially QPDF.hh, QPDFObjectHandle.hh, and
|
files in include/qpdf, especially QPDF.hh, QPDFObjectHandle.hh, and
|
||||||
QPDFWriter.hh. You can also study the code of qpdf/qpdf.cc, which
|
QPDFWriter.hh. You can also study the code of qpdf/qpdf.cc, which
|
||||||
exercises most of the public interface. There are additional example
|
exercises most of the public interface. There are additional example
|
||||||
programs in the examples directory.
|
programs in the examples directory. Reading all the source files in
|
||||||
|
the qpdf directory (including the qpdf command-line tool and some test
|
||||||
|
drivers) along with the code in the examples directory will give you a
|
||||||
|
complete picture of every aspect of the public interface.
|
||||||
|
|
||||||
|
|
||||||
Additional Notes on Test Suite
|
Additional Notes on Test Suite
|
||||||
@ -102,15 +117,21 @@ Additional Notes on Test Suite
|
|||||||
|
|
||||||
By default, slow tests are disabled. Slow tests include image
|
By default, slow tests are disabled. Slow tests include image
|
||||||
comparison tests and large file tests. Image comparison tests can be
|
comparison tests and large file tests. Image comparison tests can be
|
||||||
enabled by passing --enable-test-compare-images to ./configure. Large
|
enabled by passing --enable-test-compare-images to ./configure. This
|
||||||
file tests can be enabled by passing --with-large-file-test-path=path
|
was on by default in qpdf versions prior to 3.0, but is now off by
|
||||||
to ./configure or by setting the LARGE_FILE_TEST_PATH environment
|
default. Large file tests can be enabled by passing
|
||||||
variable. Run ./configure --help for additional options. The test
|
--with-large-file-test-path=path to ./configure or by setting the
|
||||||
suite provides nearly full coverage even without these tests. Unless
|
QPDF_LARGE_FILE_TEST_PATH environment variable. Run ./configure
|
||||||
you are making deep changes to the library or testing this on a new
|
--help for additional options. The test suite provides nearly full
|
||||||
platform for the first time, there is no real reason to run these
|
coverage even without these tests. Unless you are making deep changes
|
||||||
tests. If you're just running the test suite to make sure that qpdf
|
to the library that would impact the contents of the generated PDF
|
||||||
works for your build, the default tests are adequate.
|
files or testing this on a new platform for the first time, there is
|
||||||
|
no real reason to run these tests. If you're just running the test
|
||||||
|
suite to make sure that qpdf works for your build, the default tests
|
||||||
|
are adequate. The configure rules for these tests do nothing other
|
||||||
|
than setting variables in autoconf.mk, so you can feel free to turn
|
||||||
|
these on and off directly in autoconf.mk rather than rerunning
|
||||||
|
configure.
|
||||||
|
|
||||||
If you are packaging qpdf for a distribution and preparing a build
|
If you are packaging qpdf for a distribution and preparing a build
|
||||||
that is run by an autobuilder, you may want to add the
|
that is run by an autobuilder, you may want to add the
|
||||||
|
@ -5,24 +5,41 @@ file.
|
|||||||
For Windows, there are several additional files that you might want to
|
For Windows, there are several additional files that you might want to
|
||||||
download.
|
download.
|
||||||
|
|
||||||
* qpdf-<version>-bin-mingw.zip
|
* qpdf-<version>-bin-mingw32.zip
|
||||||
|
|
||||||
If you just want to use the qpdf commandline program or use the
|
If you just want to use the qpdf commandline program or use the
|
||||||
qpdf DLL's C-language interface, you can download this file. You
|
qpdf DLL's C-language interface, you can download this file. You
|
||||||
can also download this version if you are using MINGW's gcc 4.4 and
|
can also download this version if you are using MINGW's gcc 4.4 and
|
||||||
want to program using the C++ interface.
|
want to program using the C++ interface.
|
||||||
|
|
||||||
* qpdf-<version>-bin-msvc.zip
|
* qpdf-<version>-bin-mingw64.zip
|
||||||
|
|
||||||
|
A 64-bit version built with mingw. Use this for 64-bit Windows
|
||||||
|
systems. The 32-bit version will also work on Windows 64-bit.
|
||||||
|
Both the 32-bit and the 64-bit version support files over 2 GB in
|
||||||
|
size, but you may find it easier to integrate this with your own
|
||||||
|
software if you use the 64-bit version.
|
||||||
|
|
||||||
|
* qpdf-<version>-bin-msvc32.zip
|
||||||
|
|
||||||
If you want to program using qpdf's C++ interface and you are using
|
If you want to program using qpdf's C++ interface and you are using
|
||||||
Microsoft Visual C++ .NET 2008 (VC9), you can download this file.
|
Microsoft Visual C++ 2010 in 32-bit mode, you can download this
|
||||||
|
file.
|
||||||
|
|
||||||
|
* qpdf-<version>-bin-msvc64.zip
|
||||||
|
|
||||||
|
If you want to program using qpdf's C++ interface and you are using
|
||||||
|
Microsoft Visual C++ 2010 in 64-bit mode, you can download this
|
||||||
|
file.
|
||||||
|
|
||||||
* qpdf-external-libs-bin.zip
|
* qpdf-external-libs-bin.zip
|
||||||
|
|
||||||
If you want to build qpdf for Windows yourself with either MINGW's
|
If you want to build qpdf for Windows yourself with either MINGW or
|
||||||
gcc 4.4 or VC9, you can download this file and extract it inside
|
MSVC 2010, you can download this file and extract it inside the
|
||||||
the qpdf source distribution. Please refer to README-windows.txt
|
qpdf source distribution. Please refer to README-windows.txt in
|
||||||
in the qpdf source distribution for additional details.
|
the qpdf source distribution for additional details. Note that you
|
||||||
|
need the 2012-06-20 version or later to be able to build qpdf 3.0
|
||||||
|
or newer.
|
||||||
|
|
||||||
* qpdf-external-libs-src.zip
|
* qpdf-external-libs-src.zip
|
||||||
|
|
||||||
|
@ -1,21 +1,49 @@
|
|||||||
Common Setup
|
Common Setup
|
||||||
============
|
============
|
||||||
|
|
||||||
To be able to build qpdf and run its test suite, you must have either
|
You may need to disable antivirus software to run qpdf's test suite.
|
||||||
Cygwin or MSYS from MinGW (>= 1.0.11) installed. If you want to build
|
|
||||||
with Microsoft Visual C++, either Cygwin or MSYS will do. If you want
|
To be able to build qpdf and run its test suite, you must have MSYS
|
||||||
to build with MinGW, you must use MSYS rather than Cygwin.
|
from MinGW installed, and you must have ActiveState Perl. Here's what
|
||||||
|
I did on my system:
|
||||||
|
|
||||||
|
Install ActiveState perl.
|
||||||
|
|
||||||
|
Grab the latest mingw-get-inst. From the installation wizard, choose
|
||||||
|
to install developer kit, C, and C++ support. Once installed, you
|
||||||
|
will have an icon to start an msys shell. From the msys shell, run
|
||||||
|
|
||||||
|
mingw-get install msys-unzip msys-zip mingw32-make
|
||||||
|
|
||||||
|
Then replace perl and make with the appropriate versions:
|
||||||
|
|
||||||
|
mv /bin/perl.exe /bin/msys-perl.exe
|
||||||
|
mv /bin/make.exe /bin/msys-make.exe
|
||||||
|
mv /mingw/bin/mingw32-make.exe /mingw/bin/make.exe
|
||||||
|
|
||||||
|
Make sure perl --version shows ActiveState perl.
|
||||||
|
|
||||||
|
To install MinGW-w64, first install msys and mingw32 as above.
|
||||||
|
|
||||||
|
From MinGW-w64 download page, go to "Toolchains targetting
|
||||||
|
Win64/Automated Builds" and find the latest mingw-w64 that runs under
|
||||||
|
i686-mingw. It will be called something like
|
||||||
|
mingw-w64-bin_i686-mingw_yyyymmdd.zip. The compiler binaries are
|
||||||
|
32-bit, which (of course) runs on 64-bit Windows. Extract this under
|
||||||
|
C:\MinGW-w64, and add C:\MinGW-w64\bin and C:\MinGW-w64\lib\mingw to
|
||||||
|
the path.
|
||||||
|
|
||||||
As of this writing, the image comparison tests confuse ghostscript in
|
As of this writing, the image comparison tests confuse ghostscript in
|
||||||
cygwin, but there's a chance they might work at some point. If you
|
cygwin, but there's a chance they might work at some point. If you
|
||||||
want to run them, you need ghostscript and tiff utils as well. Then
|
want to run them, you need ghostscript and tiff utils as well, and you
|
||||||
omit --disable-test-compare-images from the configure statements given
|
will need to add --enable-test-compare-images from the configure
|
||||||
below. The image comparison tests have not been tried under MSYS.
|
statements given below.
|
||||||
|
|
||||||
Jian Ma <stronghorse@tom.com> has generously provided a port of QPDF
|
Jian Ma <stronghorse@tom.com> has generously provided a port of QPDF
|
||||||
that works with Microsoft VC6. Several changes are required, but they
|
that works with Microsoft VC6. Several changes are required, but they
|
||||||
are well documented in his port. You can find the VC6 port in the
|
are well documented in his port. You can find the VC6 port in the
|
||||||
contrib area of the qpdf download area.
|
contrib area of the qpdf download area. It may not always be
|
||||||
|
up-to-date with the latest official qpdf release.
|
||||||
|
|
||||||
|
|
||||||
External Libraries
|
External Libraries
|
||||||
@ -24,13 +52,14 @@ External Libraries
|
|||||||
In order to build qpdf, you must have copies of zlib and pcre. The
|
In order to build qpdf, you must have copies of zlib and pcre. The
|
||||||
easy way to get them is to download them from the qpdf download area.
|
easy way to get them is to download them from the qpdf download area.
|
||||||
There are packages called external-libs-bin.zip and
|
There are packages called external-libs-bin.zip and
|
||||||
external-libs-src.zip. If you are building with MSVC 9 (.NET 2008) or
|
external-libs-src.zip. If you are building with MSVC 2010 or MINGW,
|
||||||
MINGW 4.4, you can just extract the external-libs-bin.zip zip file
|
you can just extract the qpdf-external-libs-bin.zip zip file into the
|
||||||
into the top-level qpdf source tree. It will create a directory
|
top-level qpdf source tree. Note that you need the 2012-06-20 version
|
||||||
called external-libs which contains header files and precompiled
|
(at least) to build qpdf 3.0 or greater since this incldues 64-bit
|
||||||
libraries. Passing --enable-external-libs to ./configure (which is
|
libaries. It will create a directory called external-libs which
|
||||||
done automatically if you follow the instructions below) is sufficient
|
contains header files and precompiled libraries. Passing
|
||||||
to find them.
|
--enable-external-libs to ./configure (which is done automatically if
|
||||||
|
you follow the instructions below) is sufficient to find them.
|
||||||
|
|
||||||
You can also obtain pcre and zlib directly on your own and install
|
You can also obtain pcre and zlib directly on your own and install
|
||||||
them. If you are using mingw, you can just set CPPFLAGS, LDFLAGS, and
|
them. If you are using mingw, you can just set CPPFLAGS, LDFLAGS, and
|
||||||
@ -44,27 +73,42 @@ CPPFLAGS, LDFLAGS, LIBS in the generated autoconf.mk file. Note that
|
|||||||
you should use UNIX-like syntax (-I, -L, -l) even though this is not
|
you should use UNIX-like syntax (-I, -L, -l) even though this is not
|
||||||
what cl takes on the command line. qpdf's build rules will fix it.
|
what cl takes on the command line. qpdf's build rules will fix it.
|
||||||
|
|
||||||
|
You can also download qpdf-external-libs-src.zip and follow the
|
||||||
|
instructions in the README.txt there for how to build external libs.
|
||||||
|
|
||||||
|
|
||||||
Building with MinGW
|
Building with MinGW
|
||||||
===================
|
===================
|
||||||
|
|
||||||
QPDF is known to build and pass its test suite with MSYS-1.0.11 and
|
QPDF is known to build and pass its test suite with mingw (latest
|
||||||
gcc 4.4.0 with C++ support. If you also have ActiveState Perl in your
|
version tested: gcc 4.6.2), mingw64 (latest version tested: 4.7.0) and
|
||||||
path and the external-libs distribution described above, you can fully
|
Microsoft Visual C++ 2010, both 32-bit and 64-bit versions. MSYS plus
|
||||||
configure, build, and test qpdf in this environment. You will most
|
ActivateState Perl is required to build as well in order to get make
|
||||||
likely not be able to build qpdf with mingw using cygwin.
|
and other related tools. While it is possible that Cygwin could be
|
||||||
|
used to build native Windows versions of qpdf, this configuration has
|
||||||
|
not been tested recently.
|
||||||
|
|
||||||
From your MSYS prompt, run
|
From your MSYS prompt, run
|
||||||
|
|
||||||
./config-mingw
|
./config-mingw32
|
||||||
|
|
||||||
|
or
|
||||||
|
|
||||||
|
./config-mingw64
|
||||||
|
|
||||||
and then
|
and then
|
||||||
|
|
||||||
make
|
make
|
||||||
|
|
||||||
Note that ./config-mingw just runs ./configure with specific
|
Note that ./config-mingw32 and ./configure-mingw64 just run
|
||||||
arguments, so you can look at it, make adjustments, and manually run
|
./configure with specific arguments, so you can look at it, make
|
||||||
configure instead.
|
adjustments, and manually run configure instead. Note also that
|
||||||
|
config-mingw32 appends definition of _FILE_OFFSET_BITS=64 to
|
||||||
|
qpdf-config.h since, as of the qpdf 3.0 release, the current versions
|
||||||
|
of the autoconf tools did not correctly detect that mingw requires
|
||||||
|
this to get large file support. This workaround is only required for
|
||||||
|
mingw32. The 64-bit version of mingw works "out of the box" with
|
||||||
|
large file support, as do both the 32-bit and 64-bit versions of MSVC.
|
||||||
|
|
||||||
Add the absolute path to the libqpdf/build directory to your PATH.
|
Add the absolute path to the libqpdf/build directory to your PATH.
|
||||||
Make sure you can run the qpdf command by typing qpdf/build/qpdf and
|
Make sure you can run the qpdf command by typing qpdf/build/qpdf and
|
||||||
@ -80,26 +124,42 @@ create install-mingw/qpdf-VERSION and populate it. The binary
|
|||||||
download of qpdf for Windows with mingw is created from this
|
download of qpdf for Windows with mingw is created from this
|
||||||
directory.
|
directory.
|
||||||
|
|
||||||
|
You can also take a look at make_windows_releases for reference. This
|
||||||
|
is how the distributed Windows executables are created.
|
||||||
|
|
||||||
Building with MSVC .NET 2008 Express
|
|
||||||
====================================
|
Building with MSVC 2010
|
||||||
|
=======================
|
||||||
|
|
||||||
These instructions would likely work with newer version of MSVC or
|
These instructions would likely work with newer version of MSVC or
|
||||||
with full version of MSVC. They may also work with .NET 2005. They
|
with full version of MSVC. They may also work with .NET 2005. They
|
||||||
have only been tested with .NET 2008 Express (VC9.0). You may follow
|
have only been tested with Visual C++ 2010. Earlier version of qpdf
|
||||||
these instructions from either Cygwin or from MSYS, though only MSYS
|
were built with MSVC 2008 Express.
|
||||||
is regularly tested.
|
|
||||||
|
|
||||||
You should first set up your environment to be able to run MSVC from
|
You should first set up your environment to be able to run MSVC from
|
||||||
the command line. There is usually a batch file included with MSVC
|
the command line. There is usually a batch file included with MSVC
|
||||||
that does this. From that cmd prompt, you can start your cygwin
|
that does this. Make sure that you start a command line environment
|
||||||
shell.
|
configured for whichever of 32-bit or 64-bit output that you intend to
|
||||||
|
build for.
|
||||||
|
|
||||||
|
From that cmd prompt, you can start your msys shell by just running
|
||||||
|
manually whatever command is associated with your msys shell icon.
|
||||||
|
|
||||||
Configure as follows:
|
Configure as follows:
|
||||||
|
|
||||||
./config-msvc
|
./config-msvc 32
|
||||||
|
|
||||||
and then
|
or
|
||||||
|
|
||||||
|
./config-msvc 64
|
||||||
|
|
||||||
|
Note that you must pass the 32/64 option that matches your command
|
||||||
|
line setup. The scripts do not presently figure this out. If you
|
||||||
|
used the wrong argument, it would probably just build the size you
|
||||||
|
have in your environment and then install the results in the wrong
|
||||||
|
place.
|
||||||
|
|
||||||
|
Once configured, run
|
||||||
|
|
||||||
make
|
make
|
||||||
|
|
||||||
@ -156,4 +216,5 @@ when the runtime is linked in statically, exceptions cannot be thrown
|
|||||||
across the DLL to EXE boundary. Since qpdf uses exception handling
|
across the DLL to EXE boundary. Since qpdf uses exception handling
|
||||||
extensively for error handling, we have no choice but to redistribute
|
extensively for error handling, we have no choice but to redistribute
|
||||||
the C++ runtime DLLs. Maybe this will be addressed in a future
|
the C++ runtime DLLs. Maybe this will be addressed in a future
|
||||||
version of the compilers.
|
version of the compilers. This has not been retested with the
|
||||||
|
toolchain versions used to create qpdf 3.0 distributions.
|
||||||
|
@ -94,6 +94,7 @@ Release Reminders
|
|||||||
|
|
||||||
* Remember to update the web page including putting new documentation
|
* Remember to update the web page including putting new documentation
|
||||||
in the "files" subdirectory of the website on sourceforge.net.
|
in the "files" subdirectory of the website on sourceforge.net.
|
||||||
|
Linearize the PDF version of the manual when copying it there.
|
||||||
|
|
||||||
* Create a tag in the version control system, and make backups of the
|
* Create a tag in the version control system, and make backups of the
|
||||||
actual releases. With git, use git tag -s to create a signed tag:
|
actual releases. With git, use git tag -s to create a signed tag:
|
||||||
|
88
TODO
88
TODO
@ -1,89 +1,21 @@
|
|||||||
Next
|
|
||||||
====
|
|
||||||
|
|
||||||
*** ABI changes have been made. build.mk has been updated.
|
|
||||||
|
|
||||||
* 64-bit windows build, remaining steps
|
|
||||||
|
|
||||||
- new external-libs have been built and copied into
|
|
||||||
~/Q/storage/releases/qpdf/external-libs. Release is done in
|
|
||||||
git. Just need to upload when ready. Remember to document that
|
|
||||||
this version is needed for > 2.3.1.
|
|
||||||
|
|
||||||
- update README-windows.txt docs to indicate that MSVC 2010 is the
|
|
||||||
supported version and to update the information about mingw,
|
|
||||||
including the need for the _FILE_OFFSET_BITS workaround on the
|
|
||||||
32-bit version.
|
|
||||||
|
|
||||||
* Document that your compiler has to support long long.
|
|
||||||
|
|
||||||
* Make sure that the release notes call attention to the one API
|
|
||||||
breaking change: removal of length from replaceStreamData.
|
|
||||||
|
|
||||||
* Document thread safety: One individual QPDF or QPDFWriter object
|
|
||||||
can only be used by one thread at a time, but multiple threads can
|
|
||||||
simultaneously use separate objects.
|
|
||||||
|
|
||||||
* Mention QPDFObjectHandle::parse in the documentation.
|
|
||||||
|
|
||||||
* Manual: empty --empty as an input file name option
|
|
||||||
|
|
||||||
* copyForeignObject, merge/split documentation:
|
|
||||||
|
|
||||||
document details of --pages option in manual. Include nuances of
|
|
||||||
range parsing, such as backward ranges and "z". Discuss
|
|
||||||
implications of using --empty vs. using one of the source files as
|
|
||||||
the original file including Outlines (which basically work) and
|
|
||||||
page labels (which don't). Also mention trick of specifying two
|
|
||||||
different paths to the same file get duplication.
|
|
||||||
|
|
||||||
Command line is
|
|
||||||
|
|
||||||
--pages infile [ --password=pwd ] range ... --
|
|
||||||
|
|
||||||
The regular input referenced would be the one whose other data
|
|
||||||
would be preserved (like trailer, info, encryption, outlines,
|
|
||||||
etc.). It can be but doesn't have to be one of the files selected.
|
|
||||||
|
|
||||||
Example: to grab pages 1-5 from file1 and 11-15 from file2 in
|
|
||||||
reverse:
|
|
||||||
|
|
||||||
qpdf file1.pdf out.pdf --pages file1.pdf 1-5 file2.pdf 15-11 --
|
|
||||||
|
|
||||||
Use comments in qpdf.cc to guide internals documentation when
|
|
||||||
discussing implementation. Also see copyForeignObject as a source
|
|
||||||
for documentation.
|
|
||||||
|
|
||||||
Document that makeIndirectObject doesn't handle foreign objects
|
|
||||||
automatically because copying a foreign object is a big enough deal
|
|
||||||
that it should be explicit. However addPages* does handle foreign
|
|
||||||
page objects automatically.
|
|
||||||
|
|
||||||
* Document --copy-encryption and --encryption-file-password in
|
|
||||||
manual. Mention that the first half of /ID as well as all the
|
|
||||||
encryption parameters are copied. Maybe mention about StrF and
|
|
||||||
StrM with respect to AES here and also with encryption
|
|
||||||
preservation.
|
|
||||||
|
|
||||||
|
|
||||||
Soon
|
|
||||||
====
|
|
||||||
|
|
||||||
* See if I can support the new encryption formats mentioned in the
|
|
||||||
open bug on sourceforge. Check other sourceforge bugs.
|
|
||||||
|
|
||||||
|
|
||||||
General
|
General
|
||||||
=======
|
=======
|
||||||
|
|
||||||
|
* See if I can support the encryption format used with /R 5 /V 5,
|
||||||
|
even though a qpdf-announce subscriber with an adobe.com email
|
||||||
|
address mentioned that this is deprecated. There is also a new
|
||||||
|
encryption format coming in a future release, which may be better
|
||||||
|
to support. As of the qpdf 3.0 release, the specification was not
|
||||||
|
publicly available yet.
|
||||||
|
|
||||||
|
* Consider the possibility of doing something locale-aware to support
|
||||||
|
non-ASCII passwords. Update documentation if this is done.
|
||||||
|
|
||||||
* Look for %PDF header somewhere within the first 1024 bytes of the
|
* Look for %PDF header somewhere within the first 1024 bytes of the
|
||||||
file. Also accept headers of the form "%!PS−Adobe−N.n PDF−M.m".
|
file. Also accept headers of the form "%!PS−Adobe−N.n PDF−M.m".
|
||||||
See Implementation notes 13 and 14 in appendix H of the PDF 1.7
|
See Implementation notes 13 and 14 in appendix H of the PDF 1.7
|
||||||
specification. This is bug 3267974.
|
specification. This is bug 3267974.
|
||||||
|
|
||||||
* Update qpdf docs about non-ascii passwords. See thread from
|
|
||||||
2010-12-07,08 for details.
|
|
||||||
|
|
||||||
* Consider impact of article threads on page splitting/merging.
|
* Consider impact of article threads on page splitting/merging.
|
||||||
Subramanyam provided a test file; see ../misc/article-threads.pdf.
|
Subramanyam provided a test file; see ../misc/article-threads.pdf.
|
||||||
Email Q-Count: 431864 from 2009-11-03. Other things to consider:
|
Email Q-Count: 431864 from 2009-11-03. Other things to consider:
|
||||||
|
@ -2,7 +2,7 @@ dnl Process this file with autoconf to produce a configure script.
|
|||||||
dnl This config.in requires autoconf 2.5 or greater.
|
dnl This config.in requires autoconf 2.5 or greater.
|
||||||
|
|
||||||
AC_PREREQ([2.68])
|
AC_PREREQ([2.68])
|
||||||
AC_INIT([qpdf],[3.0.a0])
|
AC_INIT([qpdf],[3.0.rc1])
|
||||||
|
|
||||||
AC_CONFIG_MACRO_DIR([m4])
|
AC_CONFIG_MACRO_DIR([m4])
|
||||||
AC_CONFIG_FILES([autoconf.mk])
|
AC_CONFIG_FILES([autoconf.mk])
|
||||||
|
@ -18,7 +18,7 @@
|
|||||||
#include <qpdf/QPDF_Null.hh>
|
#include <qpdf/QPDF_Null.hh>
|
||||||
#include <qpdf/QPDF_Dictionary.hh>
|
#include <qpdf/QPDF_Dictionary.hh>
|
||||||
|
|
||||||
std::string QPDF::qpdf_version = "3.0.a0";
|
std::string QPDF::qpdf_version = "3.0.rc1";
|
||||||
|
|
||||||
static char const* EMPTY_PDF =
|
static char const* EMPTY_PDF =
|
||||||
"%PDF-1.3\n"
|
"%PDF-1.3\n"
|
||||||
|
@ -5,8 +5,8 @@
|
|||||||
<!ENTITY mdash "—">
|
<!ENTITY mdash "—">
|
||||||
<!ENTITY ndash "–">
|
<!ENTITY ndash "–">
|
||||||
<!ENTITY nbsp " ">
|
<!ENTITY nbsp " ">
|
||||||
<!ENTITY swversion "3.0.a0">
|
<!ENTITY swversion "3.0.rc1">
|
||||||
<!ENTITY lastreleased "June 25, 2012">
|
<!ENTITY lastreleased "July 29, 2012">
|
||||||
]>
|
]>
|
||||||
<book>
|
<book>
|
||||||
<bookinfo>
|
<bookinfo>
|
||||||
@ -26,6 +26,8 @@
|
|||||||
QPDF is a program that does structural, content-preserving
|
QPDF is a program that does structural, content-preserving
|
||||||
transformations on PDF files. QPDF's website is located at <ulink
|
transformations on PDF files. QPDF's website is located at <ulink
|
||||||
url="http://qpdf.sourceforge.net/">http://qpdf.sourceforge.net/</ulink>.
|
url="http://qpdf.sourceforge.net/">http://qpdf.sourceforge.net/</ulink>.
|
||||||
|
QPDF's source code is hosted on github at <ulink
|
||||||
|
url="https://github.com/qpdf/qpdf">https://github.com/qpdf/qpdf</ulink>.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
QPDF has been released under the terms of <ulink
|
QPDF has been released under the terms of <ulink
|
||||||
@ -56,14 +58,28 @@
|
|||||||
about how they work.
|
about how they work.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
QPDF is <emphasis>not</emphasis> a PDF content creation library, a
|
With QPDF, it is possible to copy objects from one PDF file into
|
||||||
PDF viewer, or a program capable of converting PDF into other
|
another and to manipulate the list of pages in a PDF file. This
|
||||||
formats. In particular, QPDF knows nothing about the semantics of
|
makes it possible to merge and split PDF files. The QPDF library
|
||||||
PDF content streams. If you are looking for something that can do
|
also makes it possible for you to create PDF files from scratch.
|
||||||
|
In this mode, you are responsible for supplying all the contents of
|
||||||
|
the file, while the QPDF library takes care off all the syntactical
|
||||||
|
representation of the objects, creation of cross references tables
|
||||||
|
and, if you use them, object streams, encryption, linearization,
|
||||||
|
and other syntactic details. You are still responsible for
|
||||||
|
generating PDF content on your own.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
QPDF has been designed with very few external dependencies, and it
|
||||||
|
is intentionally very lightweight. QPDF is
|
||||||
|
<emphasis>not</emphasis> a PDF content creation library, a PDF
|
||||||
|
viewer, or a program capable of converting PDF into other formats.
|
||||||
|
In particular, QPDF knows nothing about the semantics of PDF
|
||||||
|
content streams. If you are looking for something that can do
|
||||||
that, you should look elsewhere. However, once you have a valid
|
that, you should look elsewhere. However, once you have a valid
|
||||||
PDF file, QPDF can be used to transform that file in ways perhaps
|
PDF file, QPDF can be used to transform that file in ways perhaps
|
||||||
your original PDF creation can't handle. For example, programs
|
your original PDF creation can't handle. For example, many
|
||||||
generate simple PDF files but can't password-protect them,
|
programs generate simple PDF files but can't password-protect them,
|
||||||
web-optimize them, or perform other transformations of that type.
|
web-optimize them, or perform other transformations of that type.
|
||||||
</para>
|
</para>
|
||||||
</chapter>
|
</chapter>
|
||||||
@ -112,17 +128,34 @@
|
|||||||
-u</command>.
|
-u</command>.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
A C++ compiler that works well with STL and has the <type>long
|
||||||
|
long</type> type. Most modern C++ compilers should fit the
|
||||||
|
bill fine. QPDF is tested with gcc and Microsoft Visual C++.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Part of qpdf's test suite does comparisons of the contents PDF
|
Part of qpdf's test suite does comparisons of the contents PDF
|
||||||
files by converting them images and comparing the images. You can
|
files by converting them images and comparing the images. The
|
||||||
optionally disable this part of the test suite by running
|
image comparison tests are disabled by default. Those tests are
|
||||||
<command>configure</command> with the
|
not required for determining correctness of a qpdf build if you
|
||||||
<option>--disable-test-compare-images</option> flag. If you leave
|
have not modified the code since the test suite also contains
|
||||||
this enabled, the following additional requirements are required
|
expected output files that are compared literally. The image
|
||||||
by the test suite. Note that in no case are these items required
|
comparison tests provide an extra check to make sure that any
|
||||||
to use qpdf.
|
content transformations don't break the rendering of pages.
|
||||||
|
Transformations that affect the content streams themselves are off
|
||||||
|
by default and are only provided to help developers look into the
|
||||||
|
contents of PDF files. If you are making deep changes to the
|
||||||
|
library that cause changes in the contents of the files that qpdf
|
||||||
|
generates, then you should enable the image comparison tests.
|
||||||
|
Enable them by running <command>configure</command> with the
|
||||||
|
<option>--enable-test-compare-images</option> flag. If you enable
|
||||||
|
this, the following additional requirements are required by the
|
||||||
|
test suite. Note that in no case are these items required to use
|
||||||
|
qpdf.
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
@ -132,13 +165,12 @@
|
|||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
GhostScript version 8.60 or newer: <ulink
|
GhostScript version 8.60 or newer: <ulink
|
||||||
url="http://pages.cs.wisc.edu/~ghost/">http://pages.cs.wisc.edu/~ghost/</ulink>
|
url="http://www.ghostscript.com">http://www.ghostscript.com</ulink>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
This option is primarily intended for use by packagers of qpdf so
|
If you do not enable this, then you do not need to have tiff and
|
||||||
that they can avoid having the qpdf packages depend on tiff and
|
ghostscript.
|
||||||
ghostscript software.
|
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
If Adobe Reader is installed as <command>acroread</command>, some
|
If Adobe Reader is installed as <command>acroread</command>, some
|
||||||
@ -158,7 +190,7 @@
|
|||||||
To build the PDF version of the documentation, you need Apache fop
|
To build the PDF version of the documentation, you need Apache fop
|
||||||
(<ulink
|
(<ulink
|
||||||
url="http://xml.apache.org/fop/">http://xml.apache.org/fop/</ulink>)
|
url="http://xml.apache.org/fop/">http://xml.apache.org/fop/</ulink>)
|
||||||
version 0.94 of higher.
|
version 0.94 or higher.
|
||||||
</para>
|
</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
<sect1 id="ref.building">
|
<sect1 id="ref.building">
|
||||||
@ -182,9 +214,9 @@ make
|
|||||||
Building on Windows is a little bit more complicated. For
|
Building on Windows is a little bit more complicated. For
|
||||||
details, please see <filename>README-windows.txt</filename> in the
|
details, please see <filename>README-windows.txt</filename> in the
|
||||||
source distribution. You can also download a binary distribution
|
source distribution. You can also download a binary distribution
|
||||||
for Windows. There is a port of qpdf in the
|
for Windows. There is a port of qpdf to Visual C++ version 6 in
|
||||||
<filename>contrib</filename> area generously contributed by Jian
|
the <filename>contrib</filename> area generously contributed by
|
||||||
Ma. This is also discussed in more detail in
|
Jian Ma. This is also discussed in more detail in
|
||||||
<filename>README-windows.txt</filename>.
|
<filename>README-windows.txt</filename>.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
@ -215,7 +247,12 @@ make
|
|||||||
identical to the input file but may have been structurally
|
identical to the input file but may have been structurally
|
||||||
reorganized. Also, orphaned objects will be removed from the
|
reorganized. Also, orphaned objects will be removed from the
|
||||||
file. Many transformations are available as controlled by the
|
file. Many transformations are available as controlled by the
|
||||||
options below.
|
options below. In place of <option>infilename</option>, the
|
||||||
|
parameter <option>--empty</option> may be specified. This causes
|
||||||
|
qpdf to use a dummy input file that contains zero pages. The only
|
||||||
|
normal use case for using <option>--empty</option> would be if you
|
||||||
|
were going to add pages from another source, as discussed in <xref
|
||||||
|
linkend="ref.page-selection"/>.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
<option>outfilename</option> does not have to be seekable, even
|
<option>outfilename</option> does not have to be seekable, even
|
||||||
@ -248,7 +285,35 @@ make
|
|||||||
<term><option>--linearize</option></term>
|
<term><option>--linearize</option></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Causes generation of a linearized (web optimized) output file.
|
Causes generation of a linearized (web-optimized) output file.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><option>--copy-encryption=file</option></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Encrypt the file using the same encryption parameters,
|
||||||
|
including user and owner password, as the specified file. Use
|
||||||
|
<option>--encrypt-file-password</option> to specify a password
|
||||||
|
if one is needed to open this file. Note that copying the
|
||||||
|
encryption parameters from a file also copies the first half
|
||||||
|
of <literal>/ID</literal> from the file since this is part of
|
||||||
|
the encryption parameters.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><option>--encrypt-file-password=password</option></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If the file specified with <option>--copy-encryption</option>
|
||||||
|
requires a password, specify the password using this option.
|
||||||
|
Note that only one of the user or owner password is required.
|
||||||
|
Both passwords will be preserved since QPDF does not
|
||||||
|
distinguish between the two passwords. It is possible to
|
||||||
|
preserve encryption parameters, including the owner password,
|
||||||
|
from a file even if you don't know the file's owner password.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
@ -271,6 +336,16 @@ make
|
|||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term><option>--pages options --</option></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Select specific pages from one or more input files. See <xref
|
||||||
|
linkend="ref.page-selection"/> for details on how to do page
|
||||||
|
selection (splitting and merging).
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
@ -289,6 +364,25 @@ make
|
|||||||
restrictions or other restrictions placed on files by their
|
restrictions or other restrictions placed on files by their
|
||||||
producers.
|
producers.
|
||||||
</para>
|
</para>
|
||||||
|
<para>
|
||||||
|
In all cases where qpdf allows specification of a password, care
|
||||||
|
must be taken if the password contains characters that fall
|
||||||
|
outside of the 7-bit US-ASCII character range to ensure that the
|
||||||
|
exact correct byte sequence is provided. It is possible that a
|
||||||
|
future version of qpdf may handle this more gracefully. For
|
||||||
|
example, if a password was encrypted using a password that was
|
||||||
|
encoded in ISO-8859-1 and your terminal is configured to use
|
||||||
|
UTF-8, the password you supply may not work properly. There are
|
||||||
|
various approaches to handling this. For example, if you are
|
||||||
|
using Linux and have the iconv executable (part of the ICU
|
||||||
|
package) installed, you could pass <option>--password=`echo
|
||||||
|
<replaceable>password</replaceable> | iconv -t
|
||||||
|
iso-8859-1`</option> to qpdf where
|
||||||
|
<replaceable>password</replaceable> is a password specified in
|
||||||
|
your terminal's locale. A detailed discussion of this is out of
|
||||||
|
scope for this manual, but just be aware of this issue if you have
|
||||||
|
trouble with a password that contains 8-bit characters.
|
||||||
|
</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
<sect1 id="ref.encryption-options">
|
<sect1 id="ref.encryption-options">
|
||||||
<title>Encryption Options</title>
|
<title>Encryption Options</title>
|
||||||
@ -474,6 +568,126 @@ make
|
|||||||
The default for each permission option is to be fully permissive.
|
The default for each permission option is to be fully permissive.
|
||||||
</para>
|
</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
<sect1 id="ref.page-selection">
|
||||||
|
<title>Page Selection Options</title>
|
||||||
|
<para>
|
||||||
|
Starting with qpdf 3.0, it is possible to split and merge PDF
|
||||||
|
files by selecting pages from one or more input files. Whatever
|
||||||
|
file is given as the primary input file is used as the starting
|
||||||
|
point, but its pages are replaced with pages as specified.
|
||||||
|
|
||||||
|
<programlisting><option>--pages <replaceable>input-file</replaceable> [ <replaceable>--password=password</replaceable> ] <replaceable>page-range</replaceable> [ ... ] --</option>
|
||||||
|
</programlisting>
|
||||||
|
Multiple input files may be specified. Each one is given as the
|
||||||
|
name of the input file, an optional password (if required to open
|
||||||
|
the file), and the range of pages. Note that
|
||||||
|
“<option>--</option>” terminates parsing of page
|
||||||
|
selection flags.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
For each file that pages should be taken from, specify the file, a
|
||||||
|
password needed to open the file (if needed), and a page range.
|
||||||
|
If the primary input file file requires a password, that password
|
||||||
|
must be specified outside the <option>--pages</option> option and
|
||||||
|
does not need to be repeated inside the <option>--pages</option>.
|
||||||
|
The same file can be repeated multiple times. If a file that is
|
||||||
|
repeated has a password, the password only has to be given the
|
||||||
|
first time. All non-page data (info, outlines, page numbers,
|
||||||
|
etc.) are taken from the primary input file. To discard these,
|
||||||
|
use <option>--empty</option> as the primary input. One subtlety
|
||||||
|
about specifying passwords is that specifying a password as
|
||||||
|
<option>--encryption-file-password</option> doesn't prevent you
|
||||||
|
from having to repeat that password of that is also one of the
|
||||||
|
input files. If in doubt, it's never an error to specify the
|
||||||
|
password multiple times.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
It is not presently possible to specify the same page from the
|
||||||
|
same file directly more than once, but you can make this work by
|
||||||
|
specifying two different paths to the same file (such as by
|
||||||
|
putting <filename>./</filename> somewhere in the path). This can
|
||||||
|
also be used if you want to repeat a page from one of the input
|
||||||
|
files in the output file. This may be made more convenient in a
|
||||||
|
future version of qpdf if there is enough demand for this feature.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The page range is a set of numbers separated by commas, ranges of
|
||||||
|
numbers separated dashes, or combinations of those. The character
|
||||||
|
“z” represents the last page. Pages can appear in any
|
||||||
|
order. Ranges can appear with a high number followed by a low
|
||||||
|
number, which causes the pages to appear in reverse. Repeating a
|
||||||
|
number will cause an error, but you can use the workaround
|
||||||
|
discussed above should you really want to include the same page
|
||||||
|
twice.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Example page ranges:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<literal>1,3,5-9,15-12</literal>: pages 1, 2, 3, 5, 6, 7, 8,
|
||||||
|
9, 15, 14, 13, and 12.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<literal>z-1</literal>: all pages in the document in reverse
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Note that qpdf doesn't presently do anything special about other
|
||||||
|
constructs in a PDF file that may know about pages, so semantics
|
||||||
|
of splitting and merging vary across features. For example, the
|
||||||
|
document's outlines (bookmarks) point to actual page objects, so
|
||||||
|
if you select some pages and not others, bookmarks that point to
|
||||||
|
pages that are in the output file will work, and remaining
|
||||||
|
bookmarks will not work. On the other hand, page labels (page
|
||||||
|
numbers specified in the file) are just sequential, so page labels
|
||||||
|
will be messed up in the output file. A future version of
|
||||||
|
<command>qpdf</command> may do a better job at handling these
|
||||||
|
issues. (Note that the qpdf library already contains all of the
|
||||||
|
APIs required in order to implement this in your own application
|
||||||
|
if you need it.) In the mean time, you can always use
|
||||||
|
<option>--empty</option> 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 <filename>infile.pdf</filename> while
|
||||||
|
preserving all metadata associated with that file, you could use
|
||||||
|
|
||||||
|
<programlisting><command>qpdf</command> <option>infile.pdf --pages infile.pdf 1-5 -- outfile.pdf</option>
|
||||||
|
</programlisting>
|
||||||
|
If you wanted pages 1 through 5 from
|
||||||
|
<filename>infile.pdf</filename> but you wanted the rest of the
|
||||||
|
metadata to be dropped, you could instead run
|
||||||
|
|
||||||
|
<programlisting><command>qpdf</command> <option>--empty --pages infile.pdf 1-5 -- outfile.pdf</option>
|
||||||
|
</programlisting>
|
||||||
|
If you wanted to take pages 1–5 from
|
||||||
|
<filename>file1.pdf</filename> and pages 11–15 from
|
||||||
|
<filename>file2.pdf</filename> in reverse, you would run
|
||||||
|
|
||||||
|
<programlisting><command>qpdf</command> <option>file1.pdf --pages file1.pdf 1-5 file2.pdf 15-11 -- outfile.pdf</option>
|
||||||
|
</programlisting>
|
||||||
|
If, for some reason, you wanted to take the first page of an
|
||||||
|
encrypted file called <filename>encrypted.pdf</filename> with
|
||||||
|
password <literal>pass</literal> and repeat it twice in an output
|
||||||
|
file, and if you wanted to drop metadata (like page numbers and
|
||||||
|
outlines) but preserve encryption, you would use
|
||||||
|
|
||||||
|
<programlisting><command>qpdf</command> <option>--empty --copy-encryption=encrypted.pdf --encryption-file-password=pass
|
||||||
|
--pages encrypted.pdf --password=pass 1 ./encrypted.pdf --password=pass 1 --
|
||||||
|
outfile.pdf</option>
|
||||||
|
</programlisting>
|
||||||
|
Note that we had to specify the password all three times because
|
||||||
|
giving a password as <option>--encryption-file-password</option>
|
||||||
|
doesn't count for page selection, and as far as qpdf is concerned,
|
||||||
|
<filename>encrypted.pdf</filename> and
|
||||||
|
<filename>./encrypted.pdf</filename> are separated files. These
|
||||||
|
are all corner cases that most users should hopefully never have
|
||||||
|
to be bothered with.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
<sect1 id="ref.advanced-transformation">
|
<sect1 id="ref.advanced-transformation">
|
||||||
<title>Advanced Transformation Options</title>
|
<title>Advanced Transformation Options</title>
|
||||||
<para>
|
<para>
|
||||||
@ -1053,6 +1267,14 @@ make
|
|||||||
your system understands how to read libtool
|
your system understands how to read libtool
|
||||||
<filename>.la</filename> files, this may not be necessary.
|
<filename>.la</filename> files, this may not be necessary.
|
||||||
</para>
|
</para>
|
||||||
|
<para>
|
||||||
|
The qpdf library is safe to use in a multithreaded program, but no
|
||||||
|
individual <type>QPDF</type> object instance (including
|
||||||
|
<type>QPDF</type>, <type>QPDFObjectHandle</type>, or
|
||||||
|
<type>QPDFWriter</type>) can be used in more than one thread at a
|
||||||
|
time. Multiple threads may simultaneously work with different
|
||||||
|
instances of these and all other QPDF objects.
|
||||||
|
</para>
|
||||||
</chapter>
|
</chapter>
|
||||||
<chapter id="ref.design">
|
<chapter id="ref.design">
|
||||||
<title>Design and Library Notes</title>
|
<title>Design and Library Notes</title>
|
||||||
@ -1156,17 +1378,15 @@ make
|
|||||||
which objects are direct and which objects are indirect.
|
which objects are direct and which objects are indirect.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
There is no public interface for creating instances of
|
Instances of <classname>QPDFObjectHandle</classname> can be
|
||||||
QPDFObjectHandle. They can be created only inside the QPDF
|
directly created and modified using static factory methods in the
|
||||||
library. This is generally done through a call to the private
|
<classname>QPDFObjectHandle</classname> class. There are factory
|
||||||
method <function>QPDF::readObject</function> which uses
|
methods for each type of object as well as a convenience method
|
||||||
<classname>QPDFTokenizer</classname> to read an indirect object at
|
<function>QPDFObjectHandle::parse</function> that creates an
|
||||||
a given file position and return a
|
object from a string representation of the object. Existing
|
||||||
<classname>QPDFObjectHandle</classname> that encapsulates it.
|
instances of <classname>QPDFObjectHandle</classname> can also be
|
||||||
There are also internal methods to create fabricated indirect
|
modified in several ways. See comments in
|
||||||
objects from existing direct objects or to change an indirect
|
<filename>QPDFObjectHandle.hh</filename> for details.
|
||||||
object into a direct object, though these steps are not performed
|
|
||||||
except to support rewriting.
|
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
When the <classname>QPDF</classname> class creates a new object,
|
When the <classname>QPDF</classname> class creates a new object,
|
||||||
@ -1377,6 +1597,86 @@ make
|
|||||||
files.
|
files.
|
||||||
</para>
|
</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
<sect1 id="ref.adding-and-remove-pages">
|
||||||
|
<title>Adding and Removing Pages</title>
|
||||||
|
<para>
|
||||||
|
While qpdf's API has supported adding and modifying objects for
|
||||||
|
some time, version 3.0 introduces specific methods for adding and
|
||||||
|
removing pages. These are largely convenience routines that
|
||||||
|
handle two tricky issues: pushing inheritable resources from the
|
||||||
|
<literal>/Pages</literal> tree down to individual pages and
|
||||||
|
manipulation of the <literal>/Pages</literal> tree itself. For
|
||||||
|
details, see <function>addPage</function> and surrounding methods
|
||||||
|
in <filename>QPDF.hh</filename>.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="ref.reserved-objects">
|
||||||
|
<title>Reserving Object Numbers</title>
|
||||||
|
<para>
|
||||||
|
Version 3.0 of qpdf introduced the concept of reserved objects.
|
||||||
|
These are seldom needed for ordinary operations, but there are
|
||||||
|
cases in which you may want to add a series of indirect objects
|
||||||
|
with references to each other to a <classname>QPDF</classname>
|
||||||
|
object. This causes a problem because you can't determine the
|
||||||
|
object ID that a new indirect object will have until you add it to
|
||||||
|
the <classname>QPDF</classname> object with
|
||||||
|
<function>QPDF::makeIndirectObject</function>. The only way to
|
||||||
|
add two mutually referential objects to a
|
||||||
|
<classname>QPDF</classname> object prior to version 3.0 would be
|
||||||
|
to add the new objects first and then make them refer to each
|
||||||
|
other after adding them. Now it is possible to create a
|
||||||
|
<firstterm>reserved object</firstterm> using
|
||||||
|
<function>QPDFObjectHandle::newReserved</function>. This is an
|
||||||
|
indirect object that stays “unresolved” even if it is
|
||||||
|
queried for its type. So now, if you want to create a set of
|
||||||
|
mutually referential objects, you can create reservations for each
|
||||||
|
one of them and use those reservations to construct the
|
||||||
|
references. When finished, you can call
|
||||||
|
<function>QPDF::replaceReserved</function> to replace the reserved
|
||||||
|
objects with the real ones. This functionality will never be
|
||||||
|
needed by most applications, but it is used internally by QPDF
|
||||||
|
when copying objects from other PDF files, as discussed in <xref
|
||||||
|
linkend="ref.foreign-objects"/>. For an example of how to use
|
||||||
|
reserved objects, search for <function>newReserved</function> in
|
||||||
|
<filename>test_driver.cc</filename> in qpdf's sources.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
|
<sect1 id="ref.foreign-objects">
|
||||||
|
<title>Copying Objects From Other PDF Files</title>
|
||||||
|
<para>
|
||||||
|
Version 3.0 of qpdf introduced the ability to copy objects into a
|
||||||
|
<classname>QPDF</classname> object from a different
|
||||||
|
<classname>QPDF</classname> object, which we refer to as
|
||||||
|
<firstterm>foreign objects</firstterm>. This allows arbitrary
|
||||||
|
merging of PDF files. The <command>qpdf</command> command-line
|
||||||
|
tool provides limited support for basic page selection, including
|
||||||
|
merging in pages from other files, but the library's API makes it
|
||||||
|
possible to implement arbitrarily complex merging operations. The
|
||||||
|
main method for copying foreign objects is
|
||||||
|
<function>QPDF::copyForeignObject</function>. This takes an
|
||||||
|
indirect object from another <classname>QPDF</classname> and
|
||||||
|
copies it recursively into this object while preserving all object
|
||||||
|
structure, including circular references. This means you can add
|
||||||
|
a direct object that you create from scratch to a
|
||||||
|
<classname>QPDF</classname> object with
|
||||||
|
<function>QPDF::makeIndirectObject</function>, and you can add an
|
||||||
|
indirect object from another file with
|
||||||
|
<function>QPDF::copyForeignObject</function>. The fact that
|
||||||
|
<function>QPDF::makeIndirectObject</function> does not
|
||||||
|
automatically detect a foreign object and copy it is an explicit
|
||||||
|
design decision. Copying a foreign object seems like a
|
||||||
|
sufficiently significant thing to do that it should be done
|
||||||
|
explicitly.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The other way to copy foreign objects is by passing a page from
|
||||||
|
one <classname>QPDF</classname> to another by calling
|
||||||
|
<function>QPDF::addPage</function>. In contrast to
|
||||||
|
<function>QPDF::makeIndirectObject</function>, this method
|
||||||
|
automatically distinguishes between indirect objects in the
|
||||||
|
current file, foreign objects, and direct objects.
|
||||||
|
</para>
|
||||||
|
</sect1>
|
||||||
<sect1 id="ref.rewriting">
|
<sect1 id="ref.rewriting">
|
||||||
<title>Writing PDF Files</title>
|
<title>Writing PDF Files</title>
|
||||||
<para>
|
<para>
|
||||||
@ -1892,8 +2192,8 @@ print "\n";
|
|||||||
<para>
|
<para>
|
||||||
The specification recommends limiting the number of objects in
|
The specification recommends limiting the number of objects in
|
||||||
object stream for efficiency in reading and decoding. Acrobat 6
|
object stream for efficiency in reading and decoding. Acrobat 6
|
||||||
uses no more than objects per object stream for linearized files
|
uses no more than 100 objects per object stream for linearized
|
||||||
and no more 200 objects per stream for non-linearized files.
|
files and no more 200 objects per stream for non-linearized files.
|
||||||
<classname>QPDFWriter</classname>, in object stream generation
|
<classname>QPDFWriter</classname>, in object stream generation
|
||||||
mode, never puts more than 100 objects in an object stream.
|
mode, never puts more than 100 objects in an object stream.
|
||||||
</para>
|
</para>
|
||||||
@ -2085,6 +2385,119 @@ print "\n";
|
|||||||
For a detailed list of changes, please see the file
|
For a detailed list of changes, please see the file
|
||||||
<filename>ChangeLog</filename> in the source distribution.
|
<filename>ChangeLog</filename> in the source distribution.
|
||||||
</para>
|
</para>
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term>3.0.rc1: July 29, 2012</term>
|
||||||
|
<listitem>
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Acknowledgment: I would like to express gratitude for the
|
||||||
|
contributions of Tobias Hoffmann toward the release of qpdf
|
||||||
|
version 3.0. He is responsible for most of the implementation
|
||||||
|
and design of the new API for manipulating pages, and
|
||||||
|
contributed code and ideas for many of the improvements made
|
||||||
|
in version 3.0. Without his work, this release would
|
||||||
|
certainly not have happened as soon as it did, if at all.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
<emphasis>Non-compatible API change:</emphasis> The version of
|
||||||
|
<function>QPDFObjectHandle::replaceStreamData</function> that
|
||||||
|
uses a <classname>StreamDataProvider</classname> no longer
|
||||||
|
requires (or accepts) a <varname>length</varname> parameter.
|
||||||
|
See <xref linkend="ref.upgrading-to-3.0"/> for an explanation.
|
||||||
|
While care is taken to avoid non-compatible API changes in
|
||||||
|
general, an exception was made this time because the new
|
||||||
|
interface offers an opportunity to significantly simplify
|
||||||
|
calling code.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Support has been added for large files. The test suite
|
||||||
|
verifies support for files larger than 4 gigabytes, and manual
|
||||||
|
testing has verified support for files larger than 10
|
||||||
|
gigabytes. Large file support is available for both 32-bit
|
||||||
|
and 64-bit platforms as long as the compiler and underlying
|
||||||
|
platforms support it.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Support for page selection (splitting and merging PDF files)
|
||||||
|
has been added to the <command>qpdf</command> command-line
|
||||||
|
tool. See <xref linkend="ref.page-selection"/>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Options have been added to the <command>qpdf</command>
|
||||||
|
command-line tool for copying encryption parameters from
|
||||||
|
another file. See <xref linkend="ref.basic-options"/>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
New methods have been added to the <classname>QPDF</classname>
|
||||||
|
object for adding and removing pages. See <xref
|
||||||
|
linkend="ref.adding-and-remove-pages"/>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
New methods have been added to the <classname>QPDF</classname>
|
||||||
|
object for copying objects from other PDF files. See <xref
|
||||||
|
linkend="ref.foreign-objects"/>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
A new method <function>QPDFObjectHandle::parse</function> has
|
||||||
|
been added for constructing
|
||||||
|
<classname>QPDFObjectHandle</classname> objects from a string
|
||||||
|
description.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Methods have been added to <classname>QPDFWriter</classname>
|
||||||
|
to allow writing to an already open stdio <type>FILE*</type>
|
||||||
|
addition to writing to standard output or a named file.
|
||||||
|
Methods have been added to <classname>QPDF</classname> to be
|
||||||
|
able to process a file from an already open stdio
|
||||||
|
<type>FILE*</type>. This makes it possible to read and write
|
||||||
|
PDF from secure temporary files that have been unlinked prior
|
||||||
|
to being fully read or written.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The <function>QPDF::emptyPDF</function> can be used to allow
|
||||||
|
creation of PDF files from scratch. The example
|
||||||
|
<filename>examples/pdf-create.cc</filename> illustrates how it
|
||||||
|
can be used.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Several methods to take
|
||||||
|
<classname>PointerHolder<Buffer></classname> can now
|
||||||
|
also accept <type>std::string</type> arguments.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Many new convenience methods have been added to the library,
|
||||||
|
most in <classname>QPDFObjectHandle</classname>. See
|
||||||
|
<filename>ChangeLog</filename> for a full list.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>2.3.1: December 28, 2011</term>
|
<term>2.3.1: December 28, 2011</term>
|
||||||
@ -2728,4 +3141,47 @@ print "\n";
|
|||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</appendix>
|
</appendix>
|
||||||
|
<appendix id="ref.upgrading-to-3.0">
|
||||||
|
<title>Upgrading to 3.0</title>
|
||||||
|
<para>
|
||||||
|
For the most part, the API for qpdf version 3.0 is backward
|
||||||
|
compatible with versions 2.1 and later. There are two exceptions:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The method
|
||||||
|
<function>QPDFObjectHandle::replaceStreamData</function> that
|
||||||
|
uses a <classname>StreamDataProvider</classname> to provide the
|
||||||
|
stream data no longer takes a <varname>length</varname>
|
||||||
|
parameter. While it would have been easy enough to keep the
|
||||||
|
parameter for backward compatibility, in this case, the
|
||||||
|
parameter was removed since this provides the user an
|
||||||
|
opportunity to simplify the calling code. This method was
|
||||||
|
introduced in version 2.2. At the time, the
|
||||||
|
<varname>length</varname> parameter was required in order to
|
||||||
|
ensure that calls to the stream data provider returned the same
|
||||||
|
length for a specific stream every time they were invoked. In
|
||||||
|
particular, the linearization code depends on this. Instead,
|
||||||
|
qpdf 3.0 and newer check for that constraint explicitly. The
|
||||||
|
first time the stream data provider is called for a specific
|
||||||
|
stream, the actual length is saved, and subsequent calls are
|
||||||
|
required to return the same number of bytes. This means the
|
||||||
|
calling code no longer has to compute the length in advance,
|
||||||
|
which can be a significant simplification. If your code fails
|
||||||
|
to compile because of the extra argument and you don't want to
|
||||||
|
make other changes to your code, just omit the argument.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Many methods take <type>long long</type> instead of other
|
||||||
|
integer types. Most if not all existing code should compile
|
||||||
|
fine with this change since such parameters had always
|
||||||
|
previously been smaller types. This change was required to
|
||||||
|
support files larger than two gigabytes in size.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
</appendix>
|
||||||
</book>
|
</book>
|
||||||
|
@ -1,6 +1,6 @@
|
|||||||
Summary: Command-line tools and library for transforming PDF files
|
Summary: Command-line tools and library for transforming PDF files
|
||||||
Name: qpdf
|
Name: qpdf
|
||||||
Version: 3.0.a0
|
Version: 3.0.rc1
|
||||||
Release: 1%{?dist}
|
Release: 1%{?dist}
|
||||||
License: Artistic
|
License: Artistic
|
||||||
Group: System Environment/Libraries
|
Group: System Environment/Libraries
|
||||||
|
@ -160,11 +160,6 @@ repeated multiple times. All non-page data (info, outlines, page numbers,\n\
|
|||||||
etc. are taken from the primary input file. To discard this, use --empty\n\
|
etc. are taken from the primary input file. To discard this, use --empty\n\
|
||||||
as the primary input.\n\
|
as the primary input.\n\
|
||||||
\n\
|
\n\
|
||||||
It is not presently possible to specify the same page from the same\n\
|
|
||||||
file directly more than once, but you can make this work by specifying\n\
|
|
||||||
two different paths to the same file (such as by putting ./ somewhere\n\
|
|
||||||
in the path).\n\
|
|
||||||
\n\
|
|
||||||
The page range is a set of numbers separated by commas, ranges of\n\
|
The page range is a set of numbers separated by commas, ranges of\n\
|
||||||
numbers separated dashes, or combinations of those. The character\n\
|
numbers separated dashes, or combinations of those. The character\n\
|
||||||
\"z\" represents the last page. Pages can appear in any order. Ranges\n\
|
\"z\" represents the last page. Pages can appear in any order. Ranges\n\
|
||||||
|
Loading…
Reference in New Issue
Block a user