Commit cf3b9a778396cc336fd5772dd18762f04dc08134

Authored by Jay Berkenbilt
1 parent 3d5d42ef

doc: fix whitespace and indentation in pandoc output

Pandoc indented lists with two spaces after the dash, which is ugly
and messes up emacs fill-paragraph. I transformed the spacing using a
combination of this perl script and manual edits. I verified that the
HTML generated by sphinx was identical before and after the edits and
that this commit contains only whitespace changes. The perl script as
it stands does not do indentation quite right for variable lists, but
there were only about 8 cases that it missed, so I just fixed them
manually.

```perl
#!/usr/bin/env perl
require 5.008;
use warnings;
use strict;
use File::Basename;

my $whoami = basename($0);

my @liststack = ();

while (<>)
{
    if (m/^( *-  )\S/)
    {
        my $pre = $1;
        while ((scalar(@liststack) > 0) &&
               ($liststack[-1] >= length($pre)))
        {
            pop(@liststack);
        }
        if ((scalar(@liststack) == 0) && ($pre =~ m/^ /))
        {
            push(@liststack, 1);
        }
        push(@liststack, length($pre));
        my $n = scalar(@liststack);
        #print "** $n\n";
        my $newpre = ('  ' x ($n - 1)) . '- ';
        s/^$pre/$newpre/;
    }
    elsif (scalar(@liststack) > 0)
    {
        if ($_ ne "\n")
        {
            while (scalar(@liststack) > 0)
            {
                my $pre = m/^( *)/;
                if (length($1) < $liststack[-1])
                {
                    #print "XXX pop\n";
                    pop(@liststack);
                }
                else
                {
                    last;
                }
            }
            my $n = scalar(@liststack);
            #print "** $n\n";
            my $indent = '  ' x $n;
            s/^ +/$indent/;
        }
    }
    print;
}
```
Showing 1 changed file with 2916 additions and 2916 deletions
manual/index.rst
@@ -97,26 +97,26 @@ System Requirements @@ -97,26 +97,26 @@ System Requirements
97 The qpdf package has few external dependencies. In order to build qpdf, 97 The qpdf package has few external dependencies. In order to build qpdf,
98 the following packages are required: 98 the following packages are required:
99 99
100 -- A C++ compiler that supports C++-14. 100 +- A C++ compiler that supports C++-14.
101 101
102 -- zlib: http://www.zlib.net/ 102 +- zlib: http://www.zlib.net/
103 103
104 -- jpeg: http://www.ijg.org/files/ or https://libjpeg-turbo.org/ 104 +- jpeg: http://www.ijg.org/files/ or https://libjpeg-turbo.org/
105 105
106 -- *Recommended but not required:* gnutls: https://www.gnutls.org/ to be  
107 - able to use the gnutls crypto provider, and/or openssl:  
108 - https://openssl.org/ to be able to use the openssl crypto provider. 106 +- *Recommended but not required:* gnutls: https://www.gnutls.org/ to be
  107 + able to use the gnutls crypto provider, and/or openssl:
  108 + https://openssl.org/ to be able to use the openssl crypto provider.
109 109
110 -- gnu make 3.81 or newer: http://www.gnu.org/software/make 110 +- gnu make 3.81 or newer: http://www.gnu.org/software/make
111 111
112 -- perl version 5.8 or newer: http://www.perl.org/; required for running  
113 - the test suite. Starting with qpdf version 9.1.1, perl is no longer  
114 - required at runtime. 112 +- perl version 5.8 or newer: http://www.perl.org/; required for running
  113 + the test suite. Starting with qpdf version 9.1.1, perl is no longer
  114 + required at runtime.
115 115
116 -- GNU diffutils (any version): http://www.gnu.org/software/diffutils/  
117 - is required to run the test suite. Note that this is the version of  
118 - diff present on virtually all GNU/Linux systems. This is required  
119 - because the test suite uses @1@command@1@diff -u@2@command@2@. 116 +- GNU diffutils (any version): http://www.gnu.org/software/diffutils/
  117 + is required to run the test suite. Note that this is the version of
  118 + diff present on virtually all GNU/Linux systems. This is required
  119 + because the test suite uses @1@command@1@diff -u@2@command@2@.
120 120
121 Part of qpdf's test suite does comparisons of the contents PDF files by 121 Part of qpdf's test suite does comparisons of the contents PDF files by
122 converting them images and comparing the images. The image comparison 122 converting them images and comparing the images. The image comparison
@@ -135,9 +135,9 @@ running @1@command@1@configure@2@command@2@ with the @@ -135,9 +135,9 @@ running @1@command@1@configure@2@command@2@ with the
135 this, the following additional requirements are required by the test 135 this, the following additional requirements are required by the test
136 suite. Note that in no case are these items required to use qpdf. 136 suite. Note that in no case are these items required to use qpdf.
137 137
138 -- libtiff: http://www.remotesensing.org/libtiff/ 138 +- libtiff: http://www.remotesensing.org/libtiff/
139 139
140 -- GhostScript version 8.60 or newer: http://www.ghostscript.com 140 +- GhostScript version 8.60 or newer: http://www.ghostscript.com
141 141
142 If you do not enable this, then you do not need to have tiff and 142 If you do not enable this, then you do not need to have tiff and
143 ghostscript. 143 ghostscript.
@@ -226,23 +226,23 @@ available crypto providers, and to use an external provider as the @@ -226,23 +226,23 @@ available crypto providers, and to use an external provider as the
226 default over the native one. This behavior can be changed with the 226 default over the native one. This behavior can be changed with the
227 following flags to @1@command@1@./configure@2@command@2@: 227 following flags to @1@command@1@./configure@2@command@2@:
228 228
229 -- @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@  
230 - (where @1@replaceable@1@x@2@replaceable@2@ is a supported crypto  
231 - provider): enable the @1@replaceable@1@x@2@replaceable@2@ crypto  
232 - provider, requiring any external dependencies it needs 229 +- @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@
  230 + (where @1@replaceable@1@x@2@replaceable@2@ is a supported crypto
  231 + provider): enable the @1@replaceable@1@x@2@replaceable@2@ crypto
  232 + provider, requiring any external dependencies it needs
233 233
234 -- @1@option@1@--disable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@:  
235 - disable the @1@replaceable@1@x@2@replaceable@2@ provider, and do not  
236 - link against its dependencies even if they are available 234 +- @1@option@1@--disable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@:
  235 + disable the @1@replaceable@1@x@2@replaceable@2@ provider, and do not
  236 + link against its dependencies even if they are available
237 237
238 -- @1@option@1@--with-default-crypto=@1@replaceable@1@x@2@replaceable@2@@2@option@2@:  
239 - make @1@replaceable@1@x@2@replaceable@2@ the default provider even if  
240 - a higher priority one is available 238 +- @1@option@1@--with-default-crypto=@1@replaceable@1@x@2@replaceable@2@@2@option@2@:
  239 + make @1@replaceable@1@x@2@replaceable@2@ the default provider even if
  240 + a higher priority one is available
241 241
242 -- @1@option@1@--disable-implicit-crypto@2@option@2@: only build crypto  
243 - providers that are explicitly requested with an  
244 - @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@  
245 - option 242 +- @1@option@1@--disable-implicit-crypto@2@option@2@: only build crypto
  243 + providers that are explicitly requested with an
  244 + @1@option@1@--enable-crypto-@1@replaceable@1@x@2@replaceable@2@@2@option@2@
  245 + option
246 246
247 For example, if you want to guarantee that the gnutls crypto provider is 247 For example, if you want to guarantee that the gnutls crypto provider is
248 used and that the native provider is not built, you could run 248 used and that the native provider is not built, you could run
@@ -387,41 +387,41 @@ Notes for Packagers @@ -387,41 +387,41 @@ Notes for Packagers
387 If you are packaging qpdf for an operating system distribution, here are 387 If you are packaging qpdf for an operating system distribution, here are
388 some things you may want to keep in mind: 388 some things you may want to keep in mind:
389 389
390 -- Starting in qpdf version 9.1.1, qpdf no longer has a runtime  
391 - dependency on perl. This is because fix-qdf was rewritten in C++.  
392 - However, qpdf still has a build-time dependency on perl.  
393 -  
394 -- Make sure you are getting the intended behavior with regard to crypto  
395 - providers. Read `Build Support For Crypto  
396 - Providers <#ref.crypto.build>`__ for details.  
397 -  
398 -- Passing @1@option@1@--enable-show-failed-test-output@2@option@2@ to  
399 - @1@command@1@./configure@2@command@2@ will cause any failed test  
400 - output to be written to the console. This can be very useful for  
401 - seeing test failures generated by autobuilders where you can't access  
402 - qtest.log after the fact.  
403 -  
404 -- If qpdf's build environment detects the presence of autoconf and  
405 - related tools, it will check to ensure that automatically generated  
406 - files are up-to-date with recorded checksums and fail if it detects a  
407 - discrepancy. This feature is intended to prevent you from  
408 - accidentally forgetting to regenerate automatic files after modifying  
409 - their sources. If your packaging environment automatically refreshes  
410 - automatic files, it can cause this check to fail. Suppress qpdf's  
411 - checks by passing @1@option@1@--disable-check-autofiles@2@option@2@  
412 - to @1@command@1@/.configure@2@command@2@. This is safe since qpdf's  
413 - @1@command@1@autogen.sh@2@command@2@ just runs autotools in the  
414 - normal way.  
415 -  
416 -- QPDF's @1@command@1@make install@2@command@2@ does not install  
417 - completion files by default, but as a packager, it's good if you  
418 - install them wherever your distribution expects such files to go. You  
419 - can find completion files to install in the  
420 - @1@filename@1@completions@2@filename@2@ directory.  
421 -  
422 -- Packagers are encouraged to install the source files from the  
423 - @1@filename@1@examples@2@filename@2@ directory along with qpdf  
424 - development packages. 390 +- Starting in qpdf version 9.1.1, qpdf no longer has a runtime
  391 + dependency on perl. This is because fix-qdf was rewritten in C++.
  392 + However, qpdf still has a build-time dependency on perl.
  393 +
  394 +- Make sure you are getting the intended behavior with regard to crypto
  395 + providers. Read `Build Support For Crypto
  396 + Providers <#ref.crypto.build>`__ for details.
  397 +
  398 +- Passing @1@option@1@--enable-show-failed-test-output@2@option@2@ to
  399 + @1@command@1@./configure@2@command@2@ will cause any failed test
  400 + output to be written to the console. This can be very useful for
  401 + seeing test failures generated by autobuilders where you can't access
  402 + qtest.log after the fact.
  403 +
  404 +- If qpdf's build environment detects the presence of autoconf and
  405 + related tools, it will check to ensure that automatically generated
  406 + files are up-to-date with recorded checksums and fail if it detects a
  407 + discrepancy. This feature is intended to prevent you from
  408 + accidentally forgetting to regenerate automatic files after modifying
  409 + their sources. If your packaging environment automatically refreshes
  410 + automatic files, it can cause this check to fail. Suppress qpdf's
  411 + checks by passing @1@option@1@--disable-check-autofiles@2@option@2@
  412 + to @1@command@1@/.configure@2@command@2@. This is safe since qpdf's
  413 + @1@command@1@autogen.sh@2@command@2@ just runs autotools in the
  414 + normal way.
  415 +
  416 +- QPDF's @1@command@1@make install@2@command@2@ does not install
  417 + completion files by default, but as a packager, it's good if you
  418 + install them wherever your distribution expects such files to go. You
  419 + can find completion files to install in the
  420 + @1@filename@1@completions@2@filename@2@ directory.
  421 +
  422 +- Packagers are encouraged to install the source files from the
  423 + @1@filename@1@examples@2@filename@2@ directory along with qpdf
  424 + development packages.
425 425
426 .. _ref.using: 426 .. _ref.using:
427 427
@@ -487,20 +487,20 @@ Exit Status @@ -487,20 +487,20 @@ Exit Status
487 The exit status of @1@command@1@qpdf@2@command@2@ may be interpreted as 487 The exit status of @1@command@1@qpdf@2@command@2@ may be interpreted as
488 follows: 488 follows:
489 489
490 -- ``0``: no errors or warnings were found. The file may still have  
491 - problems qpdf can't detect. If  
492 - @1@option@1@--warning-exit-0@2@option@2@ was specified, exit status 0  
493 - is used even if there are warnings. 490 +- ``0``: no errors or warnings were found. The file may still have
  491 + problems qpdf can't detect. If
  492 + @1@option@1@--warning-exit-0@2@option@2@ was specified, exit status 0
  493 + is used even if there are warnings.
494 494
495 -- ``2``: errors were found. qpdf was not able to fully process the  
496 - file. 495 +- ``2``: errors were found. qpdf was not able to fully process the
  496 + file.
497 497
498 -- ``3``: qpdf encountered problems that it was able to recover from. In  
499 - some cases, the resulting file may still be damaged. Note that qpdf  
500 - still exits with status ``3`` if it finds warnings even when  
501 - @1@option@1@--no-warn@2@option@2@ is specified. With  
502 - @1@option@1@--warning-exit-0@2@option@2@, warnings without errors  
503 - exit with status 0 instead of 3. 498 +- ``3``: qpdf encountered problems that it was able to recover from. In
  499 + some cases, the resulting file may still be damaged. Note that qpdf
  500 + still exits with status ``3`` if it finds warnings even when
  501 + @1@option@1@--no-warn@2@option@2@ is specified. With
  502 + @1@option@1@--warning-exit-0@2@option@2@, warnings without errors
  503 + exit with status 0 instead of 3.
504 504
505 Note that @1@command@1@qpdf@2@command@2@ never exists with status ``1``. 505 Note that @1@command@1@qpdf@2@command@2@ never exists with status ``1``.
506 If you get an exit status of ``1``, it was something else, like the 506 If you get an exit status of ``1``, it was something else, like the
@@ -703,39 +703,39 @@ needed transformations. @@ -703,39 +703,39 @@ needed transformations.
703 `Unicode Passwords <#ref.unicode-passwords>`__. The following modes 703 `Unicode Passwords <#ref.unicode-passwords>`__. The following modes
704 are supported: 704 are supported:
705 705
706 - - @1@option@1@auto@2@option@2@: Automatically determine whether the  
707 - specified password is a properly encoded Unicode (UTF-8) string,  
708 - and transcode it as required by the PDF spec based on the type  
709 - encryption being applied. On Windows starting with version 8.4.0,  
710 - and on almost all other modern platforms, incoming passwords will  
711 - be properly encoded in UTF-8, so this is almost always what you  
712 - want.  
713 -  
714 - - @1@option@1@unicode@2@option@2@: Tells qpdf that the incoming  
715 - password is UTF-8, overriding whatever its automatic detection  
716 - determines. The only difference between this mode and  
717 - @1@option@1@auto@2@option@2@ is that qpdf will fail with an error  
718 - message if the password is not valid UTF-8 instead of falling back  
719 - to @1@option@1@bytes@2@option@2@ mode with a warning.  
720 -  
721 - - @1@option@1@bytes@2@option@2@: Interpret the password as a literal  
722 - byte string. For non-Windows platforms, this is what versions of  
723 - qpdf prior to 8.4.0 did. For Windows platforms, there is no way to  
724 - specify strings of binary data on the command line directly, but  
725 - you can use the @1@option@1@@filename@2@option@2@ option to do it,  
726 - in which case this option forces qpdf to respect the string of  
727 - bytes as provided. This option will allow you to encrypt PDF files  
728 - with passwords that will not be usable by other readers.  
729 -  
730 - - @1@option@1@hex-bytes@2@option@2@: Interpret the password as a  
731 - hex-encoded string. This provides a way to pass binary data as a  
732 - password on all platforms including Windows. As with  
733 - @1@option@1@bytes@2@option@2@, this option may allow creation of  
734 - files that can't be opened by other readers. This mode affects  
735 - qpdf's interpretation of passwords specified for decrypting files  
736 - as well as for encrypting them. It makes it possible to specify  
737 - strings that are encoded in some manner other than the system's  
738 - default encoding. 706 + - @1@option@1@auto@2@option@2@: Automatically determine whether the
  707 + specified password is a properly encoded Unicode (UTF-8) string,
  708 + and transcode it as required by the PDF spec based on the type
  709 + encryption being applied. On Windows starting with version 8.4.0,
  710 + and on almost all other modern platforms, incoming passwords will
  711 + be properly encoded in UTF-8, so this is almost always what you
  712 + want.
  713 +
  714 + - @1@option@1@unicode@2@option@2@: Tells qpdf that the incoming
  715 + password is UTF-8, overriding whatever its automatic detection
  716 + determines. The only difference between this mode and
  717 + @1@option@1@auto@2@option@2@ is that qpdf will fail with an error
  718 + message if the password is not valid UTF-8 instead of falling back
  719 + to @1@option@1@bytes@2@option@2@ mode with a warning.
  720 +
  721 + - @1@option@1@bytes@2@option@2@: Interpret the password as a literal
  722 + byte string. For non-Windows platforms, this is what versions of
  723 + qpdf prior to 8.4.0 did. For Windows platforms, there is no way to
  724 + specify strings of binary data on the command line directly, but
  725 + you can use the @1@option@1@@filename@2@option@2@ option to do it,
  726 + in which case this option forces qpdf to respect the string of
  727 + bytes as provided. This option will allow you to encrypt PDF files
  728 + with passwords that will not be usable by other readers.
  729 +
  730 + - @1@option@1@hex-bytes@2@option@2@: Interpret the password as a
  731 + hex-encoded string. This provides a way to pass binary data as a
  732 + password on all platforms including Windows. As with
  733 + @1@option@1@bytes@2@option@2@, this option may allow creation of
  734 + files that can't be opened by other readers. This mode affects
  735 + qpdf's interpretation of passwords specified for decrypting files
  736 + as well as for encrypting them. It makes it possible to specify
  737 + strings that are encoded in some manner other than the system's
  738 + default encoding.
739 739
740 @1@option@1@--rotate=[+|-]angle[:page-range]@2@option@2@ 740 @1@option@1@--rotate=[+|-]angle[:page-range]@2@option@2@
741 Apply rotation to specified pages. The 741 Apply rotation to specified pages. The
@@ -811,34 +811,34 @@ needed transformations. @@ -811,34 +811,34 @@ needed transformations.
811 output file. If @1@option@1@n@2@option@2@ is not specified, create 811 output file. If @1@option@1@n@2@option@2@ is not specified, create
812 single pages. Output file names are generated as follows: 812 single pages. Output file names are generated as follows:
813 813
814 - - If the string ``%d`` appears in the output file name, it is  
815 - replaced with a range of zero-padded page numbers starting from 1. 814 + - If the string ``%d`` appears in the output file name, it is
  815 + replaced with a range of zero-padded page numbers starting from 1.
816 816
817 - - Otherwise, if the output file name ends in  
818 - @1@filename@1@.pdf@2@filename@2@ (case insensitive), a zero-padded  
819 - page range, preceded by a dash, is inserted before the file  
820 - extension. 817 + - Otherwise, if the output file name ends in
  818 + @1@filename@1@.pdf@2@filename@2@ (case insensitive), a zero-padded
  819 + page range, preceded by a dash, is inserted before the file
  820 + extension.
821 821
822 - - Otherwise, the file name is appended with a zero-padded page range  
823 - preceded by a dash. 822 + - Otherwise, the file name is appended with a zero-padded page range
  823 + preceded by a dash.
824 824
825 Page ranges are a single number in the case of single-page groups or 825 Page ranges are a single number in the case of single-page groups or
826 two numbers separated by a dash otherwise. For example, if 826 two numbers separated by a dash otherwise. For example, if
827 @1@filename@1@infile.pdf@2@filename@2@ has 12 pages 827 @1@filename@1@infile.pdf@2@filename@2@ has 12 pages
828 828
829 - - @1@command@1@qpdf --split-pages infile.pdf %d-out@2@command@2@  
830 - would generate files @1@filename@1@01-out@2@filename@2@ through  
831 - @1@filename@1@12-out@2@filename@2@ 829 + - @1@command@1@qpdf --split-pages infile.pdf %d-out@2@command@2@
  830 + would generate files @1@filename@1@01-out@2@filename@2@ through
  831 + @1@filename@1@12-out@2@filename@2@
832 832
833 - - @1@command@1@qpdf --split-pages=2 infile.pdf  
834 - outfile.pdf@2@command@2@ would generate files  
835 - @1@filename@1@outfile-01-02.pdf@2@filename@2@ through  
836 - @1@filename@1@outfile-11-12.pdf@2@filename@2@ 833 + - @1@command@1@qpdf --split-pages=2 infile.pdf
  834 + outfile.pdf@2@command@2@ would generate files
  835 + @1@filename@1@outfile-01-02.pdf@2@filename@2@ through
  836 + @1@filename@1@outfile-11-12.pdf@2@filename@2@
837 837
838 - - @1@command@1@qpdf --split-pages infile.pdf  
839 - something.else@2@command@2@ would generate files  
840 - @1@filename@1@something.else-01@2@filename@2@ through  
841 - @1@filename@1@something.else-12@2@filename@2@ 838 + - @1@command@1@qpdf --split-pages infile.pdf
  839 + something.else@2@command@2@ would generate files
  840 + @1@filename@1@something.else-01@2@filename@2@ through
  841 + @1@filename@1@something.else-12@2@filename@2@
842 842
843 Note that outlines, threads, and other global features of the 843 Note that outlines, threads, and other global features of the
844 original PDF file are not preserved. For each page of output, this 844 original PDF file are not preserved. For each page of output, this
@@ -965,11 +965,11 @@ is 128, the following restriction options are available: @@ -965,11 +965,11 @@ is 128, the following restriction options are available:
965 @1@option@1@@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@ 965 @1@option@1@@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@
966 may be one of the following: 966 may be one of the following:
967 967
968 - - @1@option@1@full@2@option@2@: allow full printing 968 + - @1@option@1@full@2@option@2@: allow full printing
969 969
970 - - @1@option@1@low@2@option@2@: allow low-resolution printing only 970 + - @1@option@1@low@2@option@2@: allow low-resolution printing only
971 971
972 - - @1@option@1@none@2@option@2@: disallow printing 972 + - @1@option@1@none@2@option@2@: disallow printing
973 973
974 @1@option@1@--modify=@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@ 974 @1@option@1@--modify=@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@
975 Controls modify access. This way of controlling modify access has 975 Controls modify access. This way of controlling modify access has
@@ -977,17 +977,17 @@ is 128, the following restriction options are available: @@ -977,17 +977,17 @@ is 128, the following restriction options are available:
977 @1@option@1@@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@ 977 @1@option@1@@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@
978 may be one of the following: 978 may be one of the following:
979 979
980 - - @1@option@1@all@2@option@2@: allow full document modification 980 + - @1@option@1@all@2@option@2@: allow full document modification
981 981
982 - - @1@option@1@annotate@2@option@2@: allow comment authoring, form  
983 - operations, and document assembly 982 + - @1@option@1@annotate@2@option@2@: allow comment authoring, form
  983 + operations, and document assembly
984 984
985 - - @1@option@1@form@2@option@2@: allow form field fill-in and signing  
986 - and document assembly 985 + - @1@option@1@form@2@option@2@: allow form field fill-in and signing
  986 + and document assembly
987 987
988 - - @1@option@1@assembly@2@option@2@: allow document assembly only 988 + - @1@option@1@assembly@2@option@2@: allow document assembly only
989 989
990 - - @1@option@1@none@2@option@2@: allow no modifications 990 + - @1@option@1@none@2@option@2@: allow no modifications
991 991
992 Using the @1@option@1@--modify@2@option@2@ option does not allow you 992 Using the @1@option@1@--modify@2@option@2@ option does not allow you
993 to create certain combinations of permissions such as allowing form 993 to create certain combinations of permissions such as allowing form
@@ -1101,20 +1101,20 @@ is even or odd. @@ -1101,20 +1101,20 @@ is even or odd.
1101 1101
1102 Example page ranges: 1102 Example page ranges:
1103 1103
1104 -- ``1,3,5-9,15-12``: pages 1, 3, 5, 6, 7, 8, 9, 15, 14, 13, and 12 in  
1105 - that order. 1104 +- ``1,3,5-9,15-12``: pages 1, 3, 5, 6, 7, 8, 9, 15, 14, 13, and 12 in
  1105 + that order.
1106 1106
1107 -- ``z-1``: all pages in the document in reverse 1107 +- ``z-1``: all pages in the document in reverse
1108 1108
1109 -- ``r3-r1``: the last three pages of the document 1109 +- ``r3-r1``: the last three pages of the document
1110 1110
1111 -- ``r1-r3``: the last three pages of the document in reverse order 1111 +- ``r1-r3``: the last three pages of the document in reverse order
1112 1112
1113 -- ``1-20:even``: even pages from 2 to 20 1113 +- ``1-20:even``: even pages from 2 to 20
1114 1114
1115 -- ``5,7-9,12:odd``: pages 5, 8, and, 12, which are the pages in odd  
1116 - positions from among the original range, which represents pages 5, 7,  
1117 - 8, 9, and 12. 1115 +- ``5,7-9,12:odd``: pages 5, 8, and, 12, which are the pages in odd
  1116 + positions from among the original range, which represents pages 5, 7,
  1117 + 8, 9, and 12.
1118 1118
1119 Starting in qpdf version 8.3, you can specify the 1119 Starting in qpdf version 8.3, you can specify the
1120 @1@option@1@--collate@2@option@2@ option. Note that this option is 1120 @1@option@1@--collate@2@option@2@ option. Note that this option is
@@ -1134,23 +1134,23 @@ example, if you ran @1@command@1@qpdf --collate --empty --pages a.pdf @@ -1134,23 +1134,23 @@ example, if you ran @1@command@1@qpdf --collate --empty --pages a.pdf
1134 1-5 b.pdf 6-4 c.pdf r1 -- out.pdf@2@command@2@, you would get the 1134 1-5 b.pdf 6-4 c.pdf r1 -- out.pdf@2@command@2@, you would get the
1135 following pages in this order: 1135 following pages in this order:
1136 1136
1137 -- a.pdf page 1 1137 +- a.pdf page 1
1138 1138
1139 -- b.pdf page 6 1139 +- b.pdf page 6
1140 1140
1141 -- c.pdf last page 1141 +- c.pdf last page
1142 1142
1143 -- a.pdf page 2 1143 +- a.pdf page 2
1144 1144
1145 -- b.pdf page 5 1145 +- b.pdf page 5
1146 1146
1147 -- a.pdf page 3 1147 +- a.pdf page 3
1148 1148
1149 -- b.pdf page 4 1149 +- b.pdf page 4
1150 1150
1151 -- a.pdf page 4 1151 +- a.pdf page 4
1152 1152
1153 -- a.pdf page 5 1153 +- a.pdf page 5
1154 1154
1155 Starting in qpdf version 10.2, you may specify a numeric argument to 1155 Starting in qpdf version 10.2, you may specify a numeric argument to
1156 @1@option@1@--collate@2@option@2@. With 1156 @1@option@1@--collate@2@option@2@. With
@@ -1161,23 +1161,23 @@ again, stopping when there are no more pages. For example, if you ran @@ -1161,23 +1161,23 @@ again, stopping when there are no more pages. For example, if you ran
1161 r1 -- out.pdf@2@command@2@, you would get the following pages in this 1161 r1 -- out.pdf@2@command@2@, you would get the following pages in this
1162 order: 1162 order:
1163 1163
1164 -- a.pdf page 1 1164 +- a.pdf page 1
1165 1165
1166 -- a.pdf page 2 1166 +- a.pdf page 2
1167 1167
1168 -- b.pdf page 6 1168 +- b.pdf page 6
1169 1169
1170 -- b.pdf page 5 1170 +- b.pdf page 5
1171 1171
1172 -- c.pdf last page 1172 +- c.pdf last page
1173 1173
1174 -- a.pdf page 3 1174 +- a.pdf page 3
1175 1175
1176 -- a.pdf page 4 1176 +- a.pdf page 4
1177 1177
1178 -- b.pdf page 4 1178 +- b.pdf page 4
1179 1179
1180 -- a.pdf page 5 1180 +- a.pdf page 5
1181 1181
1182 Starting in qpdf version 8.3, when you split and merge files, any page 1182 Starting in qpdf version 8.3, when you split and merge files, any page
1183 labels (page numbers) are preserved in the final file. It is expected 1183 labels (page numbers) are preserved in the final file. It is expected
@@ -1280,40 +1280,40 @@ between the @1@option@1@--overlay@2@option@2@ or @@ -1280,40 +1280,40 @@ between the @1@option@1@--overlay@2@option@2@ or
1280 @1@option@1@--underlay@2@option@2@ flag and the 1280 @1@option@1@--underlay@2@option@2@ flag and the
1281 @1@option@1@--@2@option@2@ option. The following options are supported: 1281 @1@option@1@--@2@option@2@ option. The following options are supported:
1282 1282
1283 -- @1@option@1@--password=password@2@option@2@: supply a password if the  
1284 - overlay/underlay file is encrypted. 1283 +- @1@option@1@--password=password@2@option@2@: supply a password if the
  1284 + overlay/underlay file is encrypted.
1285 1285
1286 -- @1@option@1@--to=page-range@2@option@2@: a range of pages in the same  
1287 - form at described in `Page Selection Options <#ref.page-selection>`__  
1288 - indicates which pages in the output should have the overlay/underlay  
1289 - applied. If not specified, overlay/underlay are applied to all pages. 1286 +- @1@option@1@--to=page-range@2@option@2@: a range of pages in the same
  1287 + form at described in `Page Selection Options <#ref.page-selection>`__
  1288 + indicates which pages in the output should have the overlay/underlay
  1289 + applied. If not specified, overlay/underlay are applied to all pages.
1290 1290
1291 -- @1@option@1@--from=[page-range]@2@option@2@: a range of pages that  
1292 - specifies which pages in the overlay/underlay file will be used for  
1293 - overlay or underlay. If not specified, all pages will be used. This  
1294 - can be explicitly specified to be empty if  
1295 - @1@option@1@--repeat@2@option@2@ is used. 1291 +- @1@option@1@--from=[page-range]@2@option@2@: a range of pages that
  1292 + specifies which pages in the overlay/underlay file will be used for
  1293 + overlay or underlay. If not specified, all pages will be used. This
  1294 + can be explicitly specified to be empty if
  1295 + @1@option@1@--repeat@2@option@2@ is used.
1296 1296
1297 -- @1@option@1@--repeat=page-range@2@option@2@: an optional range of  
1298 - pages that specifies which pages in the overlay/underlay file will be  
1299 - repeated after the "from" pages are used up. If you want to repeat a  
1300 - range of pages starting at the beginning, you can explicitly use  
1301 - @1@option@1@--from=@2@option@2@. 1297 +- @1@option@1@--repeat=page-range@2@option@2@: an optional range of
  1298 + pages that specifies which pages in the overlay/underlay file will be
  1299 + repeated after the "from" pages are used up. If you want to repeat a
  1300 + range of pages starting at the beginning, you can explicitly use
  1301 + @1@option@1@--from=@2@option@2@.
1302 1302
1303 Here are some examples. 1303 Here are some examples.
1304 1304
1305 -- @1@command@1@--overlay o.pdf --to=1-5 --from=1-3 --repeat=4  
1306 - --@2@command@2@: overlay the first three pages from file  
1307 - @1@filename@1@o.pdf@2@filename@2@ onto the first three pages of the  
1308 - output, then overlay page 4 from @1@filename@1@o.pdf@2@filename@2@  
1309 - onto pages 4 and 5 of the output. Leave remaining output pages  
1310 - untouched. 1305 +- @1@command@1@--overlay o.pdf --to=1-5 --from=1-3 --repeat=4
  1306 + --@2@command@2@: overlay the first three pages from file
  1307 + @1@filename@1@o.pdf@2@filename@2@ onto the first three pages of the
  1308 + output, then overlay page 4 from @1@filename@1@o.pdf@2@filename@2@
  1309 + onto pages 4 and 5 of the output. Leave remaining output pages
  1310 + untouched.
1311 1311
1312 -- @1@command@1@--underlay footer.pdf --from= --repeat=1,2  
1313 - --@2@command@2@: Underlay page 1 of  
1314 - @1@filename@1@footer.pdf@2@filename@2@ on all odd output pages, and  
1315 - underlay page 2 of @1@filename@1@footer.pdf@2@filename@2@ on all even  
1316 - output pages. 1312 +- @1@command@1@--underlay footer.pdf --from= --repeat=1,2
  1313 + --@2@command@2@: Underlay page 1 of
  1314 + @1@filename@1@footer.pdf@2@filename@2@ on all odd output pages, and
  1315 + underlay page 2 of @1@filename@1@footer.pdf@2@filename@2@ on all even
  1316 + output pages.
1317 1317
1318 .. _ref.attachments: 1318 .. _ref.attachments:
1319 1319
@@ -1468,24 +1468,24 @@ following options are available: @@ -1468,24 +1468,24 @@ following options are available:
1468 @1@option@1@generalized@2@option@2@. The following options are 1468 @1@option@1@generalized@2@option@2@. The following options are
1469 available: 1469 available:
1470 1470
1471 - - @1@option@1@none@2@option@2@: do not attempt to decode any streams 1471 + - @1@option@1@none@2@option@2@: do not attempt to decode any streams
1472 1472
1473 - - @1@option@1@generalized@2@option@2@: decode streams filtered with  
1474 - supported generalized filters: ``/LZWDecode``, ``/FlateDecode``,  
1475 - ``/ASCII85Decode``, and ``/ASCIIHexDecode``. We define generalized  
1476 - filters as those to be used for general-purpose compression or  
1477 - encoding, as opposed to filters specifically designed for image  
1478 - data. Note that, by default, streams already compressed with  
1479 - ``/FlateDecode`` are not uncompressed and recompressed unless you  
1480 - also specify @1@option@1@--recompress-flate@2@option@2@. 1473 + - @1@option@1@generalized@2@option@2@: decode streams filtered with
  1474 + supported generalized filters: ``/LZWDecode``, ``/FlateDecode``,
  1475 + ``/ASCII85Decode``, and ``/ASCIIHexDecode``. We define generalized
  1476 + filters as those to be used for general-purpose compression or
  1477 + encoding, as opposed to filters specifically designed for image
  1478 + data. Note that, by default, streams already compressed with
  1479 + ``/FlateDecode`` are not uncompressed and recompressed unless you
  1480 + also specify @1@option@1@--recompress-flate@2@option@2@.
1481 1481
1482 - - @1@option@1@specialized@2@option@2@: in addition to generalized,  
1483 - decode streams with supported non-lossy specialized filters;  
1484 - currently this is just ``/RunLengthDecode`` 1482 + - @1@option@1@specialized@2@option@2@: in addition to generalized,
  1483 + decode streams with supported non-lossy specialized filters;
  1484 + currently this is just ``/RunLengthDecode``
1485 1485
1486 - - @1@option@1@all@2@option@2@: in addition to generalized and  
1487 - specialized, decode streams with supported lossy filters;  
1488 - currently this is just ``/DCTDecode`` (JPEG) 1486 + - @1@option@1@all@2@option@2@: in addition to generalized and
  1487 + specialized, decode streams with supported lossy filters;
  1488 + currently this is just ``/DCTDecode`` (JPEG)
1489 1489
1490 @1@option@1@--stream-data=@1@replaceable@1@option@2@replaceable@2@@2@option@2@ 1490 @1@option@1@--stream-data=@1@replaceable@1@option@2@replaceable@2@@2@option@2@
1491 Controls transformation of stream data. This option predates the 1491 Controls transformation of stream data. This option predates the
@@ -1495,21 +1495,21 @@ following options are available: @@ -1495,21 +1495,21 @@ following options are available:
1495 @1@option@1@@1@replaceable@1@option@2@replaceable@2@@2@option@2@ may 1495 @1@option@1@@1@replaceable@1@option@2@replaceable@2@@2@option@2@ may
1496 be one of the following: 1496 be one of the following:
1497 1497
1498 - - @1@option@1@compress@2@option@2@: recompress stream data when  
1499 - possible (default); equivalent to  
1500 - @1@option@1@--compress-streams=y@2@option@2@  
1501 - @1@option@1@--decode-level=generalized@2@option@2@. Does not  
1502 - recompress streams already compressed with ``/FlateDecode`` unless  
1503 - @1@option@1@--recompress-flate@2@option@2@ is also specified. 1498 + - @1@option@1@compress@2@option@2@: recompress stream data when
  1499 + possible (default); equivalent to
  1500 + @1@option@1@--compress-streams=y@2@option@2@
  1501 + @1@option@1@--decode-level=generalized@2@option@2@. Does not
  1502 + recompress streams already compressed with ``/FlateDecode`` unless
  1503 + @1@option@1@--recompress-flate@2@option@2@ is also specified.
1504 1504
1505 - - @1@option@1@preserve@2@option@2@: leave all stream data as is;  
1506 - equivalent to @1@option@1@--compress-streams=n@2@option@2@  
1507 - @1@option@1@--decode-level=none@2@option@2@ 1505 + - @1@option@1@preserve@2@option@2@: leave all stream data as is;
  1506 + equivalent to @1@option@1@--compress-streams=n@2@option@2@
  1507 + @1@option@1@--decode-level=none@2@option@2@
1508 1508
1509 - - @1@option@1@uncompress@2@option@2@: uncompress stream data  
1510 - compressed with generalized filters when possible; equivalent to  
1511 - @1@option@1@--compress-streams=n@2@option@2@  
1512 - @1@option@1@--decode-level=generalized@2@option@2@ 1509 + - @1@option@1@uncompress@2@option@2@: uncompress stream data
  1510 + compressed with generalized filters when possible; equivalent to
  1511 + @1@option@1@--compress-streams=n@2@option@2@
  1512 + @1@option@1@--decode-level=generalized@2@option@2@
1513 1513
1514 @1@option@1@--recompress-flate@2@option@2@ 1514 @1@option@1@--recompress-flate@2@option@2@
1515 By default, streams already compressed with ``/FlateDecode`` are left 1515 By default, streams already compressed with ``/FlateDecode`` are left
@@ -1540,13 +1540,13 @@ following options are available: @@ -1540,13 +1540,13 @@ following options are available:
1540 @1@option@1@@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ may be 1540 @1@option@1@@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ may be
1541 one of the following: 1541 one of the following:
1542 1542
1543 - - @1@option@1@preserve@2@option@2@: preserve original object streams  
1544 - (default) 1543 + - @1@option@1@preserve@2@option@2@: preserve original object streams
  1544 + (default)
1545 1545
1546 - - @1@option@1@disable@2@option@2@: don't write any object streams 1546 + - @1@option@1@disable@2@option@2@: don't write any object streams
1547 1547
1548 - - @1@option@1@generate@2@option@2@: use object streams wherever  
1549 - possible 1548 + - @1@option@1@generate@2@option@2@: use object streams wherever
  1549 + possible
1550 1550
1551 @1@option@1@--preserve-unreferenced@2@option@2@ 1551 @1@option@1@--preserve-unreferenced@2@option@2@
1552 Tells qpdf to preserve objects that are not referenced when writing 1552 Tells qpdf to preserve objects that are not referenced when writing
@@ -1637,14 +1637,14 @@ following options are available: @@ -1637,14 +1637,14 @@ following options are available:
1637 annotations. The @1@replaceable@1@option@2@replaceable@2@ parameter 1637 annotations. The @1@replaceable@1@option@2@replaceable@2@ parameter
1638 may be any of the following: 1638 may be any of the following:
1639 1639
1640 - - @1@option@1@all@2@option@2@: include all annotations that are not  
1641 - marked invisible or hidden 1640 + - @1@option@1@all@2@option@2@: include all annotations that are not
  1641 + marked invisible or hidden
1642 1642
1643 - - @1@option@1@print@2@option@2@: only include annotations that  
1644 - indicate that they should appear when the page is printed 1643 + - @1@option@1@print@2@option@2@: only include annotations that
  1644 + indicate that they should appear when the page is printed
1645 1645
1646 - - @1@option@1@screen@2@option@2@: omit annotations that indicate  
1647 - they should not appear on the screen 1646 + - @1@option@1@screen@2@option@2@: omit annotations that indicate
  1647 + they should not appear on the screen
1648 1648
1649 Note that form fields are special because the annotations that are 1649 Note that form fields are special because the annotations that are
1650 used to render filled-in form fields may become out of date from the 1650 used to render filled-in form fields may become out of date from the
@@ -1666,25 +1666,25 @@ following options are available: @@ -1666,25 +1666,25 @@ following options are available:
1666 option. Most of these are not a problem with well-behaved PDF files. 1666 option. Most of these are not a problem with well-behaved PDF files.
1667 The limitations are as follows: 1667 The limitations are as follows:
1668 1668
1669 - - Radio button and checkbox appearances use the pre-set values in  
1670 - the PDF file. QPDF just makes sure that the correct appearance is  
1671 - displayed based on the value of the field. This is fine for PDF  
1672 - files that create their forms properly. Some PDF writers save  
1673 - appearances for fields when they change, which could cause some  
1674 - controls to have inconsistent appearances. 1669 + - Radio button and checkbox appearances use the pre-set values in
  1670 + the PDF file. QPDF just makes sure that the correct appearance is
  1671 + displayed based on the value of the field. This is fine for PDF
  1672 + files that create their forms properly. Some PDF writers save
  1673 + appearances for fields when they change, which could cause some
  1674 + controls to have inconsistent appearances.
1675 1675
1676 - - For text fields and list boxes, any characters that fall outside  
1677 - of US-ASCII or, if detected, "Windows ANSI" or "Mac Roman"  
1678 - encoding, will be replaced by the ``?`` character. 1676 + - For text fields and list boxes, any characters that fall outside
  1677 + of US-ASCII or, if detected, "Windows ANSI" or "Mac Roman"
  1678 + encoding, will be replaced by the ``?`` character.
1679 1679
1680 - - Quadding is ignored. Quadding is used to specify whether the  
1681 - contents of a field should be left, center, or right aligned with  
1682 - the field. 1680 + - Quadding is ignored. Quadding is used to specify whether the
  1681 + contents of a field should be left, center, or right aligned with
  1682 + the field.
1683 1683
1684 - - Rich text, multi-line, and other more elaborate formatting  
1685 - directives are ignored. 1684 + - Rich text, multi-line, and other more elaborate formatting
  1685 + directives are ignored.
1686 1686
1687 - - There is no support for multi-select fields or signature fields. 1687 + - There is no support for multi-select fields or signature fields.
1688 1688
1689 If qpdf doesn't do a good enough job with your form, use an external 1689 If qpdf doesn't do a good enough job with your form, use an external
1690 application to save your filled-in form before processing it with 1690 application to save your filled-in form before processing it with
@@ -2141,41 +2141,41 @@ writes a repaired file to standard output. @@ -2141,41 +2141,41 @@ writes a repaired file to standard output.
2141 2141
2142 The following attributes characterize a QDF file: 2142 The following attributes characterize a QDF file:
2143 2143
2144 -- All objects appear in numerical order in the PDF file, including when  
2145 - objects appear in object streams. 2144 +- All objects appear in numerical order in the PDF file, including when
  2145 + objects appear in object streams.
2146 2146
2147 -- Objects are printed in an easy-to-read format, and all line endings  
2148 - are normalized to UNIX line endings. 2147 +- Objects are printed in an easy-to-read format, and all line endings
  2148 + are normalized to UNIX line endings.
2149 2149
2150 -- Unless specifically overridden, streams appear uncompressed (when  
2151 - qpdf supports the filters and they are compressed with a non-lossy  
2152 - compression scheme), and most content streams are normalized (line  
2153 - endings are converted to just a UNIX-style linefeeds). 2150 +- Unless specifically overridden, streams appear uncompressed (when
  2151 + qpdf supports the filters and they are compressed with a non-lossy
  2152 + compression scheme), and most content streams are normalized (line
  2153 + endings are converted to just a UNIX-style linefeeds).
2154 2154
2155 -- All streams lengths are represented as indirect objects, and the  
2156 - stream length object is always the next object after the stream. If  
2157 - the stream data does not end with a newline, an extra newline is  
2158 - inserted, and a special comment appears after the stream indicating  
2159 - that this has been done. 2155 +- All streams lengths are represented as indirect objects, and the
  2156 + stream length object is always the next object after the stream. If
  2157 + the stream data does not end with a newline, an extra newline is
  2158 + inserted, and a special comment appears after the stream indicating
  2159 + that this has been done.
2160 2160
2161 -- If the PDF file contains object streams, if object stream *n*  
2162 - contains *k* objects, those objects are numbered from *n+1* through  
2163 - *n+k*, and the object number/offset pairs appear on a separate line  
2164 - for each object. Additionally, each object in the object stream is  
2165 - preceded by a comment indicating its object number and index. This  
2166 - makes it very easy to find objects in object streams. 2161 +- If the PDF file contains object streams, if object stream *n*
  2162 + contains *k* objects, those objects are numbered from *n+1* through
  2163 + *n+k*, and the object number/offset pairs appear on a separate line
  2164 + for each object. Additionally, each object in the object stream is
  2165 + preceded by a comment indicating its object number and index. This
  2166 + makes it very easy to find objects in object streams.
2167 2167
2168 -- All beginnings of objects, ``stream`` tokens, ``endstream`` tokens,  
2169 - and ``endobj`` tokens appear on lines by themselves. A blank line  
2170 - follows every ``endobj`` token. 2168 +- All beginnings of objects, ``stream`` tokens, ``endstream`` tokens,
  2169 + and ``endobj`` tokens appear on lines by themselves. A blank line
  2170 + follows every ``endobj`` token.
2171 2171
2172 -- If there is a cross-reference stream, it is unfiltered. 2172 +- If there is a cross-reference stream, it is unfiltered.
2173 2173
2174 -- Page dictionaries and page content streams are marked with special  
2175 - comments that make them easy to find. 2174 +- Page dictionaries and page content streams are marked with special
  2175 + comments that make them easy to find.
2176 2176
2177 -- Comments precede each object indicating the object number of the  
2178 - corresponding object in the original file. 2177 +- Comments precede each object indicating the object number of the
  2178 + corresponding object in the original file.
2179 2179
2180 When editing a QDF file, any edits can be made as long as the above 2180 When editing a QDF file, any edits can be made as long as the above
2181 constraints are maintained. This means that you can freely edit a page's 2181 constraints are maintained. This means that you can freely edit a page's
@@ -2195,18 +2195,18 @@ object. @@ -2195,18 +2195,18 @@ object.
2195 When @1@command@1@fix-qdf@2@command@2@ is run, it goes through the file 2195 When @1@command@1@fix-qdf@2@command@2@ is run, it goes through the file
2196 and recomputes the following parts of the file: 2196 and recomputes the following parts of the file:
2197 2197
2198 -- the ``/N``, ``/W``, and ``/First`` keys of all object stream  
2199 - dictionaries 2198 +- the ``/N``, ``/W``, and ``/First`` keys of all object stream
  2199 + dictionaries
2200 2200
2201 -- the pairs of numbers representing object numbers and offsets of  
2202 - objects in object streams 2201 +- the pairs of numbers representing object numbers and offsets of
  2202 + objects in object streams
2203 2203
2204 -- all stream lengths 2204 +- all stream lengths
2205 2205
2206 -- the cross-reference table or cross-reference stream 2206 +- the cross-reference table or cross-reference stream
2207 2207
2208 -- the offset to the cross-reference table or cross-reference stream  
2209 - following the ``startxref`` token 2208 +- the offset to the cross-reference table or cross-reference stream
  2209 + following the ``startxref`` token
2210 2210
2211 .. _ref.using-library: 2211 .. _ref.using-library:
2212 2212
@@ -2393,26 +2393,26 @@ Documentation @@ -2393,26 +2393,26 @@ Documentation
2393 of the corresponding field in the JSON output. The specific 2393 of the corresponding field in the JSON output. The specific
2394 guarantees are as follows: 2394 guarantees are as follows:
2395 2395
2396 - - A dictionary in the help output means that the corresponding  
2397 - location in the actual JSON output is also a dictionary with  
2398 - exactly the same keys; that is, no keys present in help are absent  
2399 - in the real output, and no keys will be present in the real output  
2400 - that are not in help. As a special case, if the dictionary has a  
2401 - single key whose name starts with ``<`` and ends with ``>``, it  
2402 - means that the JSON output is a dictionary that can have any keys,  
2403 - each of which conforms to the value of the special key. This is  
2404 - used for cases in which the keys of the dictionary are things like  
2405 - object IDs.  
2406 -  
2407 - - A string in the help output is a description of the item that  
2408 - appears in the corresponding location of the actual output. The  
2409 - corresponding output can have any format.  
2410 -  
2411 - - An array in the help output always contains a single element. It  
2412 - indicates that the corresponding location in the actual output is  
2413 - also an array, and that each element of the array has whatever  
2414 - format is implied by the single element of the help output's  
2415 - array. 2396 + - A dictionary in the help output means that the corresponding
  2397 + location in the actual JSON output is also a dictionary with
  2398 + exactly the same keys; that is, no keys present in help are absent
  2399 + in the real output, and no keys will be present in the real output
  2400 + that are not in help. As a special case, if the dictionary has a
  2401 + single key whose name starts with ``<`` and ends with ``>``, it
  2402 + means that the JSON output is a dictionary that can have any keys,
  2403 + each of which conforms to the value of the special key. This is
  2404 + used for cases in which the keys of the dictionary are things like
  2405 + object IDs.
  2406 +
  2407 + - A string in the help output is a description of the item that
  2408 + appears in the corresponding location of the actual output. The
  2409 + corresponding output can have any format.
  2410 +
  2411 + - An array in the help output always contains a single element. It
  2412 + indicates that the corresponding location in the actual output is
  2413 + also an array, and that each element of the array has whatever
  2414 + format is implied by the single element of the help output's
  2415 + array.
2416 2416
2417 For example, the help output indicates includes a "``pagelabels``" 2417 For example, the help output indicates includes a "``pagelabels``"
2418 key whose value is an array of one element. That element is a 2418 key whose value is an array of one element. That element is a
@@ -2438,41 +2438,41 @@ Limitations of JSON Representation @@ -2438,41 +2438,41 @@ Limitations of JSON Representation
2438 2438
2439 There are a few limitations to be aware of with the JSON structure: 2439 There are a few limitations to be aware of with the JSON structure:
2440 2440
2441 -- Strings, names, and indirect object references in the original PDF  
2442 - file are all converted to strings in the JSON representation. In the  
2443 - case of a "normal" PDF file, you can tell the difference because a  
2444 - name starts with a slash (``/``), and an indirect object reference  
2445 - looks like ``n n R``, but if there were to be a string that looked  
2446 - like a name or indirect object reference, there would be no way to  
2447 - tell this from the JSON output. Note that there are certain cases  
2448 - where you know for sure what something is, such as knowing that  
2449 - dictionary keys in objects are always names and that certain things  
2450 - in the higher-level computed data are known to contain indirect  
2451 - object references.  
2452 -  
2453 -- The JSON format doesn't support binary data very well. Mostly the  
2454 - details are not important, but they are presented here for  
2455 - information. When qpdf outputs a string in the JSON representation,  
2456 - it converts the string to UTF-8, assuming usual PDF string semantics.  
2457 - Specifically, if the original string is UTF-16, it is converted to  
2458 - UTF-8. Otherwise, it is assumed to have PDF doc encoding, and is  
2459 - converted to UTF-8 with that assumption. This causes strange things  
2460 - to happen to binary strings. For example, if you had the binary  
2461 - string ``<038051>``, this would be output to the JSON as ``\u0003โ€ขQ``  
2462 - because ``03`` is not a printable character and ``80`` is the bullet  
2463 - character in PDF doc encoding and is mapped to the Unicode value  
2464 - ``2022``. Since ``51`` is ``Q``, it is output as is. If you wanted to  
2465 - convert back from here to a binary string, would have to recognize  
2466 - Unicode values whose code points are higher than ``0xFF`` and map  
2467 - those back to their corresponding PDF doc encoding characters. There  
2468 - is no way to tell the difference between a Unicode string that was  
2469 - originally encoded as UTF-16 or one that was converted from PDF doc  
2470 - encoding. In other words, it's best if you don't try to use the JSON  
2471 - format to extract binary strings from the PDF file, but if you really  
2472 - had to, it could be done. Note that qpdf's  
2473 - @1@option@1@--show-object@2@option@2@ option does not have this  
2474 - limitation and will reveal the string as encoded in the original  
2475 - file. 2441 +- Strings, names, and indirect object references in the original PDF
  2442 + file are all converted to strings in the JSON representation. In the
  2443 + case of a "normal" PDF file, you can tell the difference because a
  2444 + name starts with a slash (``/``), and an indirect object reference
  2445 + looks like ``n n R``, but if there were to be a string that looked
  2446 + like a name or indirect object reference, there would be no way to
  2447 + tell this from the JSON output. Note that there are certain cases
  2448 + where you know for sure what something is, such as knowing that
  2449 + dictionary keys in objects are always names and that certain things
  2450 + in the higher-level computed data are known to contain indirect
  2451 + object references.
  2452 +
  2453 +- The JSON format doesn't support binary data very well. Mostly the
  2454 + details are not important, but they are presented here for
  2455 + information. When qpdf outputs a string in the JSON representation,
  2456 + it converts the string to UTF-8, assuming usual PDF string semantics.
  2457 + Specifically, if the original string is UTF-16, it is converted to
  2458 + UTF-8. Otherwise, it is assumed to have PDF doc encoding, and is
  2459 + converted to UTF-8 with that assumption. This causes strange things
  2460 + to happen to binary strings. For example, if you had the binary
  2461 + string ``<038051>``, this would be output to the JSON as ``\u0003โ€ขQ``
  2462 + because ``03`` is not a printable character and ``80`` is the bullet
  2463 + character in PDF doc encoding and is mapped to the Unicode value
  2464 + ``2022``. Since ``51`` is ``Q``, it is output as is. If you wanted to
  2465 + convert back from here to a binary string, would have to recognize
  2466 + Unicode values whose code points are higher than ``0xFF`` and map
  2467 + those back to their corresponding PDF doc encoding characters. There
  2468 + is no way to tell the difference between a Unicode string that was
  2469 + originally encoded as UTF-16 or one that was converted from PDF doc
  2470 + encoding. In other words, it's best if you don't try to use the JSON
  2471 + format to extract binary strings from the PDF file, but if you really
  2472 + had to, it could be done. Note that qpdf's
  2473 + @1@option@1@--show-object@2@option@2@ option does not have this
  2474 + limitation and will reveal the string as encoded in the original
  2475 + file.
2476 2476
2477 .. _json.considerations: 2477 .. _json.considerations:
2478 2478
@@ -2483,34 +2483,34 @@ For the most part, the built-in JSON help tells you everything you need @@ -2483,34 +2483,34 @@ For the most part, the built-in JSON help tells you everything you need
2483 to know about the JSON format, but there are a few non-obvious things to 2483 to know about the JSON format, but there are a few non-obvious things to
2484 be aware of: 2484 be aware of:
2485 2485
2486 -- While qpdf guarantees that keys present in the help will be present  
2487 - in the output, those fields may be null or empty if the information  
2488 - is not known or absent in the file. Also, if you specify  
2489 - @1@option@1@--json-keys@2@option@2@, the keys that are not listed  
2490 - will be excluded entirely except for those that  
2491 - @1@option@1@--json-help@2@option@2@ says are always present.  
2492 -  
2493 -- In a few places, there are keys with names containing  
2494 - ``pageposfrom1``. The values of these keys are null or an integer. If  
2495 - an integer, they point to a page index within the file numbering from  
2496 - 1. Note that JSON indexes from 0, and you would also use 0-based  
2497 - indexing using the API. However, 1-based indexing is easier in this  
2498 - case because the command-line syntax for specifying page ranges is  
2499 - 1-based. If you were going to write a program that looked through the  
2500 - JSON for information about specific pages and then use the  
2501 - command-line to extract those pages, 1-based indexing is easier.  
2502 - Besides, it's more convenient to subtract 1 from a program in a real  
2503 - programming language than it is to add 1 from shell code.  
2504 -  
2505 -- The image information included in the ``page`` section of the JSON  
2506 - output includes the key "``filterable``". Note that the value of this  
2507 - field may depend on the @1@option@1@--decode-level@2@option@2@ that  
2508 - you invoke qpdf with. The JSON output includes a top-level key  
2509 - "``parameters``" that indicates the decode level used for computing  
2510 - whether a stream was filterable. For example, jpeg images will be  
2511 - shown as not filterable by default, but they will be shown as  
2512 - filterable if you run @1@command@1@qpdf --json  
2513 - --decode-level=all@2@command@2@. 2486 +- While qpdf guarantees that keys present in the help will be present
  2487 + in the output, those fields may be null or empty if the information
  2488 + is not known or absent in the file. Also, if you specify
  2489 + @1@option@1@--json-keys@2@option@2@, the keys that are not listed
  2490 + will be excluded entirely except for those that
  2491 + @1@option@1@--json-help@2@option@2@ says are always present.
  2492 +
  2493 +- In a few places, there are keys with names containing
  2494 + ``pageposfrom1``. The values of these keys are null or an integer. If
  2495 + an integer, they point to a page index within the file numbering from
  2496 + 1. Note that JSON indexes from 0, and you would also use 0-based
  2497 + indexing using the API. However, 1-based indexing is easier in this
  2498 + case because the command-line syntax for specifying page ranges is
  2499 + 1-based. If you were going to write a program that looked through the
  2500 + JSON for information about specific pages and then use the
  2501 + command-line to extract those pages, 1-based indexing is easier.
  2502 + Besides, it's more convenient to subtract 1 from a program in a real
  2503 + programming language than it is to add 1 from shell code.
  2504 +
  2505 +- The image information included in the ``page`` section of the JSON
  2506 + output includes the key "``filterable``". Note that the value of this
  2507 + field may depend on the @1@option@1@--decode-level@2@option@2@ that
  2508 + you invoke qpdf with. The JSON output includes a top-level key
  2509 + "``parameters``" that indicates the decode level used for computing
  2510 + whether a stream was filterable. For example, jpeg images will be
  2511 + shown as not filterable by default, but they will be shown as
  2512 + filterable if you run @1@command@1@qpdf --json
  2513 + --decode-level=all@2@command@2@.
2514 2514
2515 .. _ref.design: 2515 .. _ref.design:
2516 2516
@@ -2703,29 +2703,29 @@ find them by looking at @@ -2703,29 +2703,29 @@ find them by looking at
2703 In order to avoid creation of circular dependencies, the following 2703 In order to avoid creation of circular dependencies, the following
2704 general guidelines are followed with helper classes: 2704 general guidelines are followed with helper classes:
2705 2705
2706 -- Core class interfaces do not know about helper classes. For example,  
2707 - no methods of ``QPDF`` or ``QPDFObjectHandle`` will include helper  
2708 - classes in their interfaces.  
2709 -  
2710 -- Interfaces of object helpers will usually not use document helpers in  
2711 - their interfaces. This is because it is much more useful for document  
2712 - helpers to have methods that return object helpers. Most operations  
2713 - in PDF files start at the document level and go from there to the  
2714 - object level rather than the other way around. It can sometimes be  
2715 - useful to map back from object-level structures to document-level  
2716 - structures. If there is a desire to do this, it will generally be  
2717 - provided by a method in the document helper class.  
2718 -  
2719 -- Most of the time, object helpers don't know about other object  
2720 - helpers. However, in some cases, one type of object may be a  
2721 - container for another type of object, in which case it may make sense  
2722 - for the outer object to know about the inner object. For example,  
2723 - there are methods in the ``QPDFPageObjectHelper`` that know  
2724 - ``QPDFAnnotationObjectHelper`` because references to annotations are  
2725 - contained in page dictionaries.  
2726 -  
2727 -- Any helper or core library class may use helpers in their  
2728 - implementations. 2706 +- Core class interfaces do not know about helper classes. For example,
  2707 + no methods of ``QPDF`` or ``QPDFObjectHandle`` will include helper
  2708 + classes in their interfaces.
  2709 +
  2710 +- Interfaces of object helpers will usually not use document helpers in
  2711 + their interfaces. This is because it is much more useful for document
  2712 + helpers to have methods that return object helpers. Most operations
  2713 + in PDF files start at the document level and go from there to the
  2714 + object level rather than the other way around. It can sometimes be
  2715 + useful to map back from object-level structures to document-level
  2716 + structures. If there is a desire to do this, it will generally be
  2717 + provided by a method in the document helper class.
  2718 +
  2719 +- Most of the time, object helpers don't know about other object
  2720 + helpers. However, in some cases, one type of object may be a
  2721 + container for another type of object, in which case it may make sense
  2722 + for the outer object to know about the inner object. For example,
  2723 + there are methods in the ``QPDFPageObjectHelper`` that know
  2724 + ``QPDFAnnotationObjectHelper`` because references to annotations are
  2725 + contained in page dictionaries.
  2726 +
  2727 +- Any helper or core library class may use helpers in their
  2728 + implementations.
2729 2729
2730 Prior to qpdf version 8.1, higher level interfaces were added as 2730 Prior to qpdf version 8.1, higher level interfaces were added as
2731 "convenience functions" in either ``QPDF`` or ``QPDFObjectHandle``. For 2731 "convenience functions" in either ``QPDF`` or ``QPDFObjectHandle``. For
@@ -2786,55 +2786,55 @@ stream are cached. @@ -2786,55 +2786,55 @@ stream are cached.
2786 The following example should clarify how ``QPDF`` processes a simple 2786 The following example should clarify how ``QPDF`` processes a simple
2787 file. 2787 file.
2788 2788
2789 -- Client constructs ``QPDF`` ``pdf`` and calls  
2790 - ``pdf.processFile("a.pdf");``.  
2791 -  
2792 -- The ``QPDF`` class checks the beginning of  
2793 - @1@filename@1@a.pdf@2@filename@2@ for a PDF header. It then reads the  
2794 - cross reference table mentioned at the end of the file, ensuring that  
2795 - it is looking before the last ``%%EOF``. After getting to ``trailer``  
2796 - keyword, it invokes the parser.  
2797 -  
2798 -- The parser sees "``<<``", so it calls itself recursively in  
2799 - dictionary creation mode.  
2800 -  
2801 -- In dictionary creation mode, the parser keeps accumulating objects  
2802 - until it encounters "``>>``". Each object that is read is pushed onto  
2803 - a stack. If "``R``" is read, the last two objects on the stack are  
2804 - inspected. If they are integers, they are popped off the stack and  
2805 - their values are used to construct an indirect object handle which is  
2806 - then pushed onto the stack. When "``>>``" is finally read, the stack  
2807 - is converted into a ``QPDF_Dictionary`` which is placed in a  
2808 - ``QPDFObjectHandle`` and returned.  
2809 -  
2810 -- The resulting dictionary is saved as the trailer dictionary.  
2811 -  
2812 -- The ``/Prev`` key is searched. If present, ``QPDF`` seeks to that  
2813 - point and repeats except that the new trailer dictionary is not  
2814 - saved. If ``/Prev`` is not present, the initial parsing process is  
2815 - complete.  
2816 -  
2817 - If there is an encryption dictionary, the document's encryption  
2818 - parameters are initialized.  
2819 -  
2820 -- The client requests root object. The ``QPDF`` class gets the value of  
2821 - root key from trailer dictionary and returns it. It is an unresolved  
2822 - indirect ``QPDFObjectHandle``.  
2823 -  
2824 -- The client requests the ``/Pages`` key from root  
2825 - ``QPDFObjectHandle``. The ``QPDFObjectHandle`` notices that it is  
2826 - indirect so it asks ``QPDF`` to resolve it. ``QPDF`` looks in the  
2827 - object cache for an object with the root dictionary's object ID and  
2828 - generation number. Upon not seeing it, it checks the cross reference  
2829 - table, gets the offset, and reads the object present at that offset.  
2830 - It stores the result in the object cache and returns the cached  
2831 - result. The calling ``QPDFObjectHandle`` replaces its object pointer  
2832 - with the one from the resolved ``QPDFObjectHandle``, verifies that it  
2833 - a valid dictionary object, and returns the (unresolved indirect)  
2834 - ``QPDFObject`` handle to the top of the Pages hierarchy.  
2835 -  
2836 - As the client continues to request objects, the same process is  
2837 - followed for each new requested object. 2789 +- Client constructs ``QPDF`` ``pdf`` and calls
  2790 + ``pdf.processFile("a.pdf");``.
  2791 +
  2792 +- The ``QPDF`` class checks the beginning of
  2793 + @1@filename@1@a.pdf@2@filename@2@ for a PDF header. It then reads the
  2794 + cross reference table mentioned at the end of the file, ensuring that
  2795 + it is looking before the last ``%%EOF``. After getting to ``trailer``
  2796 + keyword, it invokes the parser.
  2797 +
  2798 +- The parser sees "``<<``", so it calls itself recursively in
  2799 + dictionary creation mode.
  2800 +
  2801 +- In dictionary creation mode, the parser keeps accumulating objects
  2802 + until it encounters "``>>``". Each object that is read is pushed onto
  2803 + a stack. If "``R``" is read, the last two objects on the stack are
  2804 + inspected. If they are integers, they are popped off the stack and
  2805 + their values are used to construct an indirect object handle which is
  2806 + then pushed onto the stack. When "``>>``" is finally read, the stack
  2807 + is converted into a ``QPDF_Dictionary`` which is placed in a
  2808 + ``QPDFObjectHandle`` and returned.
  2809 +
  2810 +- The resulting dictionary is saved as the trailer dictionary.
  2811 +
  2812 +- The ``/Prev`` key is searched. If present, ``QPDF`` seeks to that
  2813 + point and repeats except that the new trailer dictionary is not
  2814 + saved. If ``/Prev`` is not present, the initial parsing process is
  2815 + complete.
  2816 +
  2817 + If there is an encryption dictionary, the document's encryption
  2818 + parameters are initialized.
  2819 +
  2820 +- The client requests root object. The ``QPDF`` class gets the value of
  2821 + root key from trailer dictionary and returns it. It is an unresolved
  2822 + indirect ``QPDFObjectHandle``.
  2823 +
  2824 +- The client requests the ``/Pages`` key from root
  2825 + ``QPDFObjectHandle``. The ``QPDFObjectHandle`` notices that it is
  2826 + indirect so it asks ``QPDF`` to resolve it. ``QPDF`` looks in the
  2827 + object cache for an object with the root dictionary's object ID and
  2828 + generation number. Upon not seeing it, it checks the cross reference
  2829 + table, gets the offset, and reads the object present at that offset.
  2830 + It stores the result in the object cache and returns the cached
  2831 + result. The calling ``QPDFObjectHandle`` replaces its object pointer
  2832 + with the one from the resolved ``QPDFObjectHandle``, verifies that it
  2833 + a valid dictionary object, and returns the (unresolved indirect)
  2834 + ``QPDFObject`` handle to the top of the Pages hierarchy.
  2835 +
  2836 + As the client continues to request objects, the same process is
  2837 + followed for each new requested object.
2838 2838
2839 .. _ref.casting: 2839 .. _ref.casting:
2840 2840
@@ -3093,66 +3093,66 @@ This outline was written prior to implementation and is not exactly @@ -3093,66 +3093,66 @@ This outline was written prior to implementation and is not exactly
3093 accurate, but it provides a correct "notional" idea of how writing 3093 accurate, but it provides a correct "notional" idea of how writing
3094 works. Look at the code in ``QPDFWriter`` for exact details. 3094 works. Look at the code in ``QPDFWriter`` for exact details.
3095 3095
3096 -- Initialize state: 3096 +- Initialize state:
3097 3097
3098 - - next object number = 1 3098 + - next object number = 1
3099 3099
3100 - - object queue = empty 3100 + - object queue = empty
3101 3101
3102 - - renumber table: old object id/generation to new id/0 = empty 3102 + - renumber table: old object id/generation to new id/0 = empty
3103 3103
3104 - - xref table: new id -> offset = empty 3104 + - xref table: new id -> offset = empty
3105 3105
3106 -- Create a QPDF object from a file. 3106 +- Create a QPDF object from a file.
3107 3107
3108 -- Write header for new PDF file. 3108 +- Write header for new PDF file.
3109 3109
3110 -- Request the trailer dictionary. 3110 +- Request the trailer dictionary.
3111 3111
3112 -- For each value that is an indirect object, grab the next object  
3113 - number (via an operation that returns and increments the number). Map  
3114 - object to new number in renumber table. Push object onto queue. 3112 +- For each value that is an indirect object, grab the next object
  3113 + number (via an operation that returns and increments the number). Map
  3114 + object to new number in renumber table. Push object onto queue.
3115 3115
3116 -- While there are more objects on the queue: 3116 +- While there are more objects on the queue:
3117 3117
3118 - - Pop queue. 3118 + - Pop queue.
3119 3119
3120 - - Look up object's new number *n* in the renumbering table. 3120 + - Look up object's new number *n* in the renumbering table.
3121 3121
3122 - - Store current offset into xref table. 3122 + - Store current offset into xref table.
3123 3123
3124 - - Write ``@1@replaceable@1@n@2@replaceable@2@ 0 obj``. 3124 + - Write ``@1@replaceable@1@n@2@replaceable@2@ 0 obj``.
3125 3125
3126 - - If object is null, whether direct or indirect, write out null,  
3127 - thus eliminating unresolvable indirect object references. 3126 + - If object is null, whether direct or indirect, write out null,
  3127 + thus eliminating unresolvable indirect object references.
3128 3128
3129 - - If the object is a stream stream, write stream contents, piped  
3130 - through any filters as required, to a memory buffer. Use this  
3131 - buffer to determine the stream length. 3129 + - If the object is a stream stream, write stream contents, piped
  3130 + through any filters as required, to a memory buffer. Use this
  3131 + buffer to determine the stream length.
3132 3132
3133 - - If object is not a stream, array, or dictionary, write out its  
3134 - contents. 3133 + - If object is not a stream, array, or dictionary, write out its
  3134 + contents.
3135 3135
3136 - - If object is an array or dictionary (including stream), traverse  
3137 - its elements (for array) or values (for dictionaries), handling  
3138 - recursive dictionaries and arrays, looking for indirect objects.  
3139 - When an indirect object is found, if it is not resolvable, ignore.  
3140 - (This case is handled when writing it out.) Otherwise, look it up  
3141 - in the renumbering table. If not found, grab the next available  
3142 - object number, assign to the referenced object in the renumbering  
3143 - table, and push the referenced object onto the queue. As a special  
3144 - case, when writing out a stream dictionary, replace length,  
3145 - filters, and decode parameters as required. 3136 + - If object is an array or dictionary (including stream), traverse
  3137 + its elements (for array) or values (for dictionaries), handling
  3138 + recursive dictionaries and arrays, looking for indirect objects.
  3139 + When an indirect object is found, if it is not resolvable, ignore.
  3140 + (This case is handled when writing it out.) Otherwise, look it up
  3141 + in the renumbering table. If not found, grab the next available
  3142 + object number, assign to the referenced object in the renumbering
  3143 + table, and push the referenced object onto the queue. As a special
  3144 + case, when writing out a stream dictionary, replace length,
  3145 + filters, and decode parameters as required.
3146 3146
3147 - Write out dictionary or array, replacing any unresolvable indirect  
3148 - object references with null (pdf spec says reference to  
3149 - non-existent object is legal and resolves to null) and any  
3150 - resolvable ones with references to the renumbered objects. 3147 + Write out dictionary or array, replacing any unresolvable indirect
  3148 + object references with null (pdf spec says reference to
  3149 + non-existent object is legal and resolves to null) and any
  3150 + resolvable ones with references to the renumbered objects.
3151 3151
3152 - - If the object is a stream, write ``stream\n``, the stream contents  
3153 - (from the memory buffer), and ``\nendstream\n``. 3152 + - If the object is a stream, write ``stream\n``, the stream contents
  3153 + (from the memory buffer), and ``\nendstream\n``.
3154 3154
3155 - - When done, write ``endobj``. 3155 + - When done, write ``endobj``.
3156 3156
3157 Once we have finished the queue, all referenced objects will have been 3157 Once we have finished the queue, all referenced objects will have been
3158 written out and all deleted objects or unreferenced objects will have 3158 written out and all deleted objects or unreferenced objects will have
@@ -3307,11 +3307,11 @@ refer to linearization as optimization or web optimization. @@ -3307,11 +3307,11 @@ refer to linearization as optimization or web optimization.
3307 When creating linearized PDF files from optimized PDF files, there are 3307 When creating linearized PDF files from optimized PDF files, there are
3308 really only a few issues that need to be dealt with: 3308 really only a few issues that need to be dealt with:
3309 3309
3310 -- Creation of hints tables 3310 +- Creation of hints tables
3311 3311
3312 -- Placing objects in the correct order 3312 +- Placing objects in the correct order
3313 3313
3314 -- Filling in offsets and byte sizes 3314 +- Filling in offsets and byte sizes
3315 3315
3316 .. _ref.optimization: 3316 .. _ref.optimization:
3317 3317
@@ -3424,17 +3424,17 @@ various other programs that create linearized files have many of these @@ -3424,17 +3424,17 @@ various other programs that create linearized files have many of these
3424 same issues. These items make reference to terminology used in the 3424 same issues. These items make reference to terminology used in the
3425 linearization appendix of the PDF specification. 3425 linearization appendix of the PDF specification.
3426 3426
3427 -- Thread Dictionary information keys appear in part 4 with the rest of  
3428 - Threads instead of in part 9. Objects in part 9 are not grouped  
3429 - together functionally. 3427 +- Thread Dictionary information keys appear in part 4 with the rest of
  3428 + Threads instead of in part 9. Objects in part 9 are not grouped
  3429 + together functionally.
3430 3430
3431 -- We are not calculating numerators for shared object positions within  
3432 - content streams or interleaving them within content streams. 3431 +- We are not calculating numerators for shared object positions within
  3432 + content streams or interleaving them within content streams.
3433 3433
3434 -- We generate only page offset, shared object, and outline hint tables.  
3435 - It would be relatively easy to add some additional tables. We gather  
3436 - most of the information needed to create thumbnail hint tables. There  
3437 - are comments in the code about this. 3434 +- We generate only page offset, shared object, and outline hint tables.
  3435 + It would be relatively easy to add some additional tables. We gather
  3436 + most of the information needed to create thumbnail hint tables. There
  3437 + are comments in the code about this.
3438 3438
3439 .. _ref.linearization-debugging: 3439 .. _ref.linearization-debugging:
3440 3440
@@ -3475,13 +3475,13 @@ Object Streams @@ -3475,13 +3475,13 @@ Object Streams
3475 3475
3476 Object streams can contain any regular object except the following: 3476 Object streams can contain any regular object except the following:
3477 3477
3478 -- stream objects 3478 +- stream objects
3479 3479
3480 -- objects with generation > 0 3480 +- objects with generation > 0
3481 3481
3482 -- the encryption dictionary 3482 +- the encryption dictionary
3483 3483
3484 -- objects containing the /Length of another stream 3484 +- objects containing the /Length of another stream
3485 3485
3486 In addition, Adobe reader (at least as of version 8.0.0) appears to not 3486 In addition, Adobe reader (at least as of version 8.0.0) appears to not
3487 be able to handle having the document catalog appear in an object stream 3487 be able to handle having the document catalog appear in an object stream
@@ -3501,11 +3501,11 @@ a regular object. @@ -3501,11 +3501,11 @@ a regular object.
3501 3501
3502 The object stream dictionary has the following keys: 3502 The object stream dictionary has the following keys:
3503 3503
3504 -- ``/N``: number of objects 3504 +- ``/N``: number of objects
3505 3505
3506 -- ``/First``: byte offset of first object 3506 +- ``/First``: byte offset of first object
3507 3507
3508 -- ``/Extends``: indirect reference to stream that this extends 3508 +- ``/Extends``: indirect reference to stream that this extends
3509 3509
3510 Stream collections are formed with ``/Extends``. They must form a 3510 Stream collections are formed with ``/Extends``. They must form a
3511 directed acyclic graph. These can be used for semantic information and 3511 directed acyclic graph. These can be used for semantic information and
@@ -3555,21 +3555,21 @@ Since xref streams must be read very early, they may not be encrypted, @@ -3555,21 +3555,21 @@ Since xref streams must be read very early, they may not be encrypted,
3555 and the may not contain indirect objects for keys required to read them, 3555 and the may not contain indirect objects for keys required to read them,
3556 which are these: 3556 which are these:
3557 3557
3558 -- ``/Type``: value ``/XRef`` 3558 +- ``/Type``: value ``/XRef``
3559 3559
3560 -- ``/Size``: value *n+1*: where *n* is highest object number (same as  
3561 - ``/Size`` in the trailer dictionary) 3560 +- ``/Size``: value *n+1*: where *n* is highest object number (same as
  3561 + ``/Size`` in the trailer dictionary)
3562 3562
3563 -- ``/Index`` (optional): value  
3564 - ``[@1@replaceable@1@n count@2@replaceable@2@ ...]`` used to determine  
3565 - which objects' information is stored in this stream. The default is  
3566 - ``[0 /Size]``. 3563 +- ``/Index`` (optional): value
  3564 + ``[@1@replaceable@1@n count@2@replaceable@2@ ...]`` used to determine
  3565 + which objects' information is stored in this stream. The default is
  3566 + ``[0 /Size]``.
3567 3567
3568 -- ``/Prev``: value @1@replaceable@1@offset@2@replaceable@2@: byte  
3569 - offset of previous xref stream (same as ``/Prev`` in the trailer  
3570 - dictionary) 3568 +- ``/Prev``: value @1@replaceable@1@offset@2@replaceable@2@: byte
  3569 + offset of previous xref stream (same as ``/Prev`` in the trailer
  3570 + dictionary)
3571 3571
3572 -- ``/W [...]``: sizes of each field in the xref table 3572 +- ``/W [...]``: sizes of each field in the xref table
3573 3573
3574 The other fields in the xref stream, which may be indirect if desired, 3574 The other fields in the xref stream, which may be indirect if desired,
3575 are the union of those from the xref table's trailer dictionary. 3575 are the union of those from the xref table's trailer dictionary.
@@ -3589,14 +3589,14 @@ type is &quot;``1``&quot;. All other default values are &quot;``0``&quot;. @@ -3589,14 +3589,14 @@ type is &quot;``1``&quot;. All other default values are &quot;``0``&quot;.
3589 3589
3590 PDF 1.5 has three field types: 3590 PDF 1.5 has three field types:
3591 3591
3592 -- 0: for free objects. Format: ``0 obj next-generation``, same as the  
3593 - free table in a traditional cross-reference table 3592 +- 0: for free objects. Format: ``0 obj next-generation``, same as the
  3593 + free table in a traditional cross-reference table
3594 3594
3595 -- 1: regular non-compressed object. Format: ``1 offset generation`` 3595 +- 1: regular non-compressed object. Format: ``1 offset generation``
3596 3596
3597 -- 2: for objects in object streams. Format: ``2 object-stream-number  
3598 - index``, the number of object stream containing the object and the  
3599 - index within the object stream of the object. 3597 +- 2: for objects in object streams. Format: ``2 object-stream-number
  3598 + index``, the number of object stream containing the object and the
  3599 + index within the object stream of the object.
3600 3600
3601 It seems standard to have the first entry in the table be ``0 0 0`` 3601 It seems standard to have the first entry in the table be ``0 0 0``
3602 instead of ``0 0 ffff`` if there are no deleted objects. 3602 instead of ``0 0 ffff`` if there are no deleted objects.
@@ -3657,1014 +3657,1014 @@ For a detailed list of changes, please see the file @@ -3657,1014 +3657,1014 @@ For a detailed list of changes, please see the file
3657 @1@filename@1@ChangeLog@2@filename@2@ in the source distribution. 3657 @1@filename@1@ChangeLog@2@filename@2@ in the source distribution.
3658 3658
3659 10.5.0: XXX Month dd, YYYY 3659 10.5.0: XXX Month dd, YYYY
3660 - - Library Enhancements  
3661 -  
3662 - - Since qpdf version 8, using object accessor methods on an  
3663 - instance of ``QPDFObjectHandle`` may create warnings if the  
3664 - object is not of the expected type. These warnings now have an  
3665 - error code of ``qpdf_e_object`` instead of  
3666 - ``qpdf_e_damaged_pdf``. Also, comments have been added to  
3667 - @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ to explain in  
3668 - more detail what the behavior is. See `Object Accessor  
3669 - Methods <#ref.object-accessors>`__ for a more in-depth  
3670 - discussion.  
3671 -  
3672 - - Overhaul error handling for the object handle functions in the  
3673 - C API. See comments in the "Object handling" section of  
3674 - @1@filename@1@include/qpdf/qpdf-c.h@2@filename@2@ for details.  
3675 - In particular, exceptions thrown by the underlying C++ code  
3676 - when calling object accessors are caught and converted into  
3677 - errors. The errors can be trapped by registering an error  
3678 - handler with ``qpdf_register_oh_error_handler`` or will be  
3679 - written to stderr if no handler is registered.  
3680 -  
3681 - - Add ``qpdf_get_last_string_length`` to the C API to get the  
3682 - length of the last string that was returned. This is needed to  
3683 - handle strings that contain embedded null characters.  
3684 -  
3685 - - Add ``qpdf_oh_is_initialized`` and  
3686 - ``qpdf_oh_new_uninitialized`` to the C API to make it possible  
3687 - to work with uninitialized objects.  
3688 -  
3689 - - Add ``qpdf_oh_new_object`` to the C API. This allows you to  
3690 - clone an object handle.  
3691 -  
3692 - - Add ``qpdf_get_object_by_id``, ``qpdf_make_indirect_object``,  
3693 - and ``qpdf_replace_object``, exposing the corresponding methods  
3694 - in ``QPDF`` and ``QPDFObjectHandle``. 3660 + - Library Enhancements
  3661 +
  3662 + - Since qpdf version 8, using object accessor methods on an
  3663 + instance of ``QPDFObjectHandle`` may create warnings if the
  3664 + object is not of the expected type. These warnings now have an
  3665 + error code of ``qpdf_e_object`` instead of
  3666 + ``qpdf_e_damaged_pdf``. Also, comments have been added to
  3667 + @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ to explain in
  3668 + more detail what the behavior is. See `Object Accessor
  3669 + Methods <#ref.object-accessors>`__ for a more in-depth
  3670 + discussion.
  3671 +
  3672 + - Overhaul error handling for the object handle functions in the
  3673 + C API. See comments in the "Object handling" section of
  3674 + @1@filename@1@include/qpdf/qpdf-c.h@2@filename@2@ for details.
  3675 + In particular, exceptions thrown by the underlying C++ code
  3676 + when calling object accessors are caught and converted into
  3677 + errors. The errors can be trapped by registering an error
  3678 + handler with ``qpdf_register_oh_error_handler`` or will be
  3679 + written to stderr if no handler is registered.
  3680 +
  3681 + - Add ``qpdf_get_last_string_length`` to the C API to get the
  3682 + length of the last string that was returned. This is needed to
  3683 + handle strings that contain embedded null characters.
  3684 +
  3685 + - Add ``qpdf_oh_is_initialized`` and
  3686 + ``qpdf_oh_new_uninitialized`` to the C API to make it possible
  3687 + to work with uninitialized objects.
  3688 +
  3689 + - Add ``qpdf_oh_new_object`` to the C API. This allows you to
  3690 + clone an object handle.
  3691 +
  3692 + - Add ``qpdf_get_object_by_id``, ``qpdf_make_indirect_object``,
  3693 + and ``qpdf_replace_object``, exposing the corresponding methods
  3694 + in ``QPDF`` and ``QPDFObjectHandle``.
3695 3695
3696 10.4.0: November 16, 2021 3696 10.4.0: November 16, 2021
3697 - - Handling of Weak Cryptography Algorithms 3697 + - Handling of Weak Cryptography Algorithms
3698 3698
3699 - - From the qpdf CLI, the  
3700 - @1@option@1@--allow-weak-crypto@2@option@2@ is now required to  
3701 - suppress a warning when explicitly creating PDF files using RC4  
3702 - encryption. While qpdf will always retain the ability to read  
3703 - and write such files, doing so will require explicit  
3704 - acknowledgment moving forward. For qpdf 10.4, this change only  
3705 - affects the command-line tool. Starting in qpdf 11, there will  
3706 - be small API changes to require explicit acknowledgment in  
3707 - those cases as well. For additional information, see `Weak  
3708 - Cryptography <#ref.weak-crypto>`__. 3699 + - From the qpdf CLI, the
  3700 + @1@option@1@--allow-weak-crypto@2@option@2@ is now required to
  3701 + suppress a warning when explicitly creating PDF files using RC4
  3702 + encryption. While qpdf will always retain the ability to read
  3703 + and write such files, doing so will require explicit
  3704 + acknowledgment moving forward. For qpdf 10.4, this change only
  3705 + affects the command-line tool. Starting in qpdf 11, there will
  3706 + be small API changes to require explicit acknowledgment in
  3707 + those cases as well. For additional information, see `Weak
  3708 + Cryptography <#ref.weak-crypto>`__.
3709 3709
3710 - - Bug Fixes 3710 + - Bug Fixes
3711 3711
3712 - - Fix potential bounds error when handling shell completion that  
3713 - could occur when given bogus input. 3712 + - Fix potential bounds error when handling shell completion that
  3713 + could occur when given bogus input.
3714 3714
3715 - - Properly handle overlay/underlay on completely empty pages  
3716 - (with no resource dictionary). 3715 + - Properly handle overlay/underlay on completely empty pages
  3716 + (with no resource dictionary).
3717 3717
3718 - - Fix crash that could occur under certain conditions when using  
3719 - @1@option@1@--pages@2@option@2@ with files that had form  
3720 - fields. 3718 + - Fix crash that could occur under certain conditions when using
  3719 + @1@option@1@--pages@2@option@2@ with files that had form
  3720 + fields.
3721 3721
3722 - - Library Enhancements 3722 + - Library Enhancements
3723 3723
3724 - - Make ``QPDF::findPage`` functions public. 3724 + - Make ``QPDF::findPage`` functions public.
3725 3725
3726 - - Add methods to ``Pl_Flate`` to be able to receive warnings on  
3727 - certain recoverable conditions. 3726 + - Add methods to ``Pl_Flate`` to be able to receive warnings on
  3727 + certain recoverable conditions.
3728 3728
3729 - - Add an extra check to the library to detect when foreign  
3730 - objects are inserted directly (instead of using  
3731 - ``QPDF::copyForeignObject``) at the time of insertion rather  
3732 - than when the file is written. Catching the error sooner makes  
3733 - it much easier to locate the incorrect code. 3729 + - Add an extra check to the library to detect when foreign
  3730 + objects are inserted directly (instead of using
  3731 + ``QPDF::copyForeignObject``) at the time of insertion rather
  3732 + than when the file is written. Catching the error sooner makes
  3733 + it much easier to locate the incorrect code.
3734 3734
3735 - - CLI Enhancements 3735 + - CLI Enhancements
3736 3736
3737 - - Improve diagnostics around parsing  
3738 - @1@option@1@--pages@2@option@2@ command-line options 3737 + - Improve diagnostics around parsing
  3738 + @1@option@1@--pages@2@option@2@ command-line options
3739 3739
3740 - - Packaging Changes 3740 + - Packaging Changes
3741 3741
3742 - - The Windows binary distribution is now built with crypto  
3743 - provided by OpenSSL 3.0. 3742 + - The Windows binary distribution is now built with crypto
  3743 + provided by OpenSSL 3.0.
3744 3744
3745 10.3.2: May 8, 2021 3745 10.3.2: May 8, 2021
3746 - - Bug Fixes 3746 + - Bug Fixes
3747 3747
3748 - - When generating a file while preserving object streams,  
3749 - unreferenced objects are correctly removed unless  
3750 - @1@option@1@--preserve-unreferenced@2@option@2@ is specified. 3748 + - When generating a file while preserving object streams,
  3749 + unreferenced objects are correctly removed unless
  3750 + @1@option@1@--preserve-unreferenced@2@option@2@ is specified.
3751 3751
3752 - - Library Enhancements 3752 + - Library Enhancements
3753 3753
3754 - - When adding a page that already exists, make a shallow copy  
3755 - instead of throwing an exception. This makes the library  
3756 - behavior consistent with the CLI behavior. See  
3757 - @1@filename@1@ChangeLog@2@filename@2@ for additional notes. 3754 + - When adding a page that already exists, make a shallow copy
  3755 + instead of throwing an exception. This makes the library
  3756 + behavior consistent with the CLI behavior. See
  3757 + @1@filename@1@ChangeLog@2@filename@2@ for additional notes.
3758 3758
3759 10.3.1: March 11, 2021 3759 10.3.1: March 11, 2021
3760 - - Bug Fixes 3760 + - Bug Fixes
3761 3761
3762 - - Form field copying failed on files where /DR was a direct  
3763 - object in the document-level form dictionary. 3762 + - Form field copying failed on files where /DR was a direct
  3763 + object in the document-level form dictionary.
3764 3764
3765 10.3.0: March 4, 2021 3765 10.3.0: March 4, 2021
3766 - - Bug Fixes  
3767 -  
3768 - - The code for handling form fields when copying pages from  
3769 - 10.2.0 was not quite right and didn't work in a number of  
3770 - situations, such as when the same page was copied multiple  
3771 - times or when there were conflicting resource or field names  
3772 - across multiple copies. The 10.3.0 code has been much more  
3773 - thoroughly tested with more complex cases and with a multitude  
3774 - of readers and should be much closer to correct. The 10.2.0  
3775 - code worked well enough for page splitting or for copying pages  
3776 - with form fields into documents that didn't already have them  
3777 - but was still not quite correct in handling of field-level  
3778 - resources.  
3779 -  
3780 - - When ``QPDF::replaceObject`` or ``QPDF::swapObjects`` is  
3781 - called, existing ``QPDFObjectHandle`` instances no longer point  
3782 - to the old objects. The next time they are accessed, they  
3783 - automatically notice the change to the underlying object and  
3784 - update themselves. This resolves a very longstanding source of  
3785 - confusion, albeit in a very rarely used method call.  
3786 -  
3787 - - Fix form field handling code to look for default appearances,  
3788 - quadding, and default resources in the right places. The code  
3789 - was not looking for things in the document-level interactive  
3790 - form dictionary that it was supposed to be finding there. This  
3791 - required adding a few new methods to  
3792 - ``QPDFFormFieldObjectHelper``.  
3793 -  
3794 - - Library Enhancements  
3795 -  
3796 - - Reworked the code that handles copying annotations and form  
3797 - fields during page operations. There were additional methods  
3798 - added to the public API from 10.2.0 and a one deprecation of a  
3799 - method added in 10.2.0. The majority of the API changes are in  
3800 - methods most people would never call and that will hopefully be  
3801 - superseded by higher-level interfaces for handling page copies.  
3802 - Please see the @1@filename@1@ChangeLog@2@filename@2@ file for  
3803 - details.  
3804 -  
3805 - - The method ``QPDF::numWarnings`` was added so that you can tell  
3806 - whether any warnings happened during a specific block of code. 3766 + - Bug Fixes
  3767 +
  3768 + - The code for handling form fields when copying pages from
  3769 + 10.2.0 was not quite right and didn't work in a number of
  3770 + situations, such as when the same page was copied multiple
  3771 + times or when there were conflicting resource or field names
  3772 + across multiple copies. The 10.3.0 code has been much more
  3773 + thoroughly tested with more complex cases and with a multitude
  3774 + of readers and should be much closer to correct. The 10.2.0
  3775 + code worked well enough for page splitting or for copying pages
  3776 + with form fields into documents that didn't already have them
  3777 + but was still not quite correct in handling of field-level
  3778 + resources.
  3779 +
  3780 + - When ``QPDF::replaceObject`` or ``QPDF::swapObjects`` is
  3781 + called, existing ``QPDFObjectHandle`` instances no longer point
  3782 + to the old objects. The next time they are accessed, they
  3783 + automatically notice the change to the underlying object and
  3784 + update themselves. This resolves a very longstanding source of
  3785 + confusion, albeit in a very rarely used method call.
  3786 +
  3787 + - Fix form field handling code to look for default appearances,
  3788 + quadding, and default resources in the right places. The code
  3789 + was not looking for things in the document-level interactive
  3790 + form dictionary that it was supposed to be finding there. This
  3791 + required adding a few new methods to
  3792 + ``QPDFFormFieldObjectHelper``.
  3793 +
  3794 + - Library Enhancements
  3795 +
  3796 + - Reworked the code that handles copying annotations and form
  3797 + fields during page operations. There were additional methods
  3798 + added to the public API from 10.2.0 and a one deprecation of a
  3799 + method added in 10.2.0. The majority of the API changes are in
  3800 + methods most people would never call and that will hopefully be
  3801 + superseded by higher-level interfaces for handling page copies.
  3802 + Please see the @1@filename@1@ChangeLog@2@filename@2@ file for
  3803 + details.
  3804 +
  3805 + - The method ``QPDF::numWarnings`` was added so that you can tell
  3806 + whether any warnings happened during a specific block of code.
3807 3807
3808 10.2.0: February 23, 2021 3808 10.2.0: February 23, 2021
3809 - - CLI Behavior Changes  
3810 -  
3811 - - Operations that work on combining pages are much better about  
3812 - protecting form fields. In particular,  
3813 - @1@option@1@--split-pages@2@option@2@ and  
3814 - @1@option@1@--pages@2@option@2@ now preserve interaction form  
3815 - functionality by copying the relevant form field information  
3816 - from the original files. Additionally, if you use  
3817 - @1@option@1@--pages@2@option@2@ to select only some pages from  
3818 - the original input file, unused form fields are removed, which  
3819 - prevents lots of unused annotations from being retained.  
3820 -  
3821 - - By default, @1@command@1@qpdf@2@command@2@ no longer allows  
3822 - creation of encrypted PDF files whose user password is  
3823 - non-empty and owner password is empty when a 256-bit key is in  
3824 - use. The @1@option@1@--allow-insecure@2@option@2@ option,  
3825 - specified inside the @1@option@1@--encrypt@2@option@2@ options,  
3826 - allows creation of such files. Behavior changes in the CLI are  
3827 - avoided when possible, but an exception was made here because  
3828 - this is security-related. qpdf must always allow creation of  
3829 - weird files for testing purposes, but it should not default to  
3830 - letting users unknowingly create insecure files.  
3831 -  
3832 - - Library Behavior Changes  
3833 -  
3834 - - Note: the changes in this section cause differences in output  
3835 - in some cases. These differences change the syntax of the PDF  
3836 - but do not change the semantics (meaning). I make a strong  
3837 - effort to avoid gratuitous changes in qpdf's output so that  
3838 - qpdf changes don't break people's tests. In this case, the  
3839 - changes significantly improve the readability of the generated  
3840 - PDF and don't affect any output that's generated by simple  
3841 - transformation. If you are annoyed by having to update test  
3842 - files, please rest assured that changes like this have been and  
3843 - will continue to be rare events.  
3844 -  
3845 - - ``QPDFObjectHandle::newUnicodeString`` now uses whichever of  
3846 - ASCII, PDFDocEncoding, of UTF-16 is sufficient to encode all  
3847 - the characters in the string. This reduces needless encoding in  
3848 - UTF-16 of strings that can be encoded in ASCII. This change may  
3849 - cause qpdf to generate different output than before when form  
3850 - field values are set using ``QPDFFormFieldObjectHelper`` but  
3851 - does not change the meaning of the output.  
3852 -  
3853 - - The code that places form XObjects and also the code that  
3854 - flattens rotations trim trailing zeroes from real numbers that  
3855 - they calculate. This causes slight (but semantically  
3856 - equivalent) differences in generated appearance streams and  
3857 - form XObject invocations in overlay/underlay code or in user  
3858 - code that calls the methods that place form XObjects on a page.  
3859 -  
3860 - - CLI Enhancements  
3861 -  
3862 - - Add new command line options for listing, saving, adding,  
3863 - removing, and and copying file attachments. See `Embedded  
3864 - Files/Attachments Options <#ref.attachments>`__ for details.  
3865 -  
3866 - - Page splitting and merging operations, as well as  
3867 - @1@option@1@--flatten-rotation@2@option@2@, are better behaved  
3868 - with respect to annotations and interactive form fields. In  
3869 - most cases, interactive form field functionality and proper  
3870 - formatting and functionality of annotations is preserved by  
3871 - these operations. There are still some cases that aren't  
3872 - perfect, such as when functionality of annotations depends on  
3873 - document-level data that qpdf doesn't yet understand or when  
3874 - there are problems with referential integrity among form fields  
3875 - and annotations (e.g., when a single form field object or its  
3876 - associated annotations are shared across multiple pages, a case  
3877 - that is out of spec but that works in most viewers anyway).  
3878 -  
3879 - - The option  
3880 - @1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@  
3881 - can now be used to read the decryption password from a file.  
3882 - You can use ``-`` as the file name to read the password from  
3883 - standard input. This is an easier/more obvious way to read  
3884 - passwords from files or standard input than using  
3885 - @1@option@1@@file@2@option@2@ for this purpose.  
3886 -  
3887 - - Add some information about attachments to the json output, and  
3888 - added ``attachments`` as an additional json key. The  
3889 - information included here is limited to the preferred name and  
3890 - content stream and a reference to the file spec object. This is  
3891 - enough detail for clients to avoid the hassle of navigating a  
3892 - name tree and provides what is needed for basic enumeration and  
3893 - extraction of attachments. More detailed information can be  
3894 - obtained by following the reference to the file spec object.  
3895 -  
3896 - - Add numeric option to @1@option@1@--collate@2@option@2@. If  
3897 - @1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@  
3898 - is given, take pages in groups of  
3899 - @1@replaceable@1@n@2@replaceable@2@ from the given files.  
3900 -  
3901 - - It is now valid to provide @1@option@1@--rotate=0@2@option@2@  
3902 - to clear rotation from a page.  
3903 -  
3904 - - Library Enhancements  
3905 -  
3906 - - This release includes numerous additions to the API. Not all  
3907 - changes are listed here. Please see the  
3908 - @1@filename@1@ChangeLog@2@filename@2@ file in the source  
3909 - distribution for a comprehensive list. Highlights appear below.  
3910 -  
3911 - - Add ``QPDFObjectHandle::ditems()`` and  
3912 - ``QPDFObjectHandle::aitems()`` that enable C++-style iteration,  
3913 - including range-for iteration, over dictionary and array  
3914 - QPDFObjectHandles. See comments in  
3915 - @1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@  
3916 - and  
3917 - @1@filename@1@examples/pdf-name-number-tree.cc@2@filename@2@  
3918 - for details.  
3919 -  
3920 - - Add ``QPDFObjectHandle::copyStream`` for making a copy of a  
3921 - stream within the same ``QPDF`` instance.  
3922 -  
3923 - - Add new helper classes for supporting file attachments, also  
3924 - known as embedded files. New classes are  
3925 - ``QPDFEmbeddedFileDocumentHelper``,  
3926 - ``QPDFFileSpecObjectHelper``, and ``QPDFEFStreamObjectHelper``.  
3927 - See their respective headers for details and  
3928 - @1@filename@1@examples/pdf-attach-file.cc@2@filename@2@ for an  
3929 - example.  
3930 -  
3931 - - Add a version of ``QPDFObjectHandle::parse`` that takes a  
3932 - ``QPDF`` pointer as context so that it can parse strings  
3933 - containing indirect object references. This is illustrated in  
3934 - @1@filename@1@examples/pdf-attach-file.cc@2@filename@2@.  
3935 -  
3936 - - Re-implement ``QPDFNameTreeObjectHelper`` and  
3937 - ``QPDFNumberTreeObjectHelper`` to be more efficient, add an  
3938 - iterator-based API, give them the capability to repair broken  
3939 - trees, and create methods for modifying the trees. With this  
3940 - change, qpdf has a robust read/write implementation of name and  
3941 - number trees.  
3942 -  
3943 - - Add new versions of ``QPDFObjectHandle::replaceStreamData``  
3944 - that take ``std::function`` objects for cases when you need  
3945 - something between a static string and a full-fledged  
3946 - StreamDataProvider. Using this with ``QUtil::file_provider`` is  
3947 - a very easy way to create a stream from the contents of a file.  
3948 -  
3949 - - The ``QPDFMatrix`` class, formerly a private, internal class,  
3950 - has been added to the public API. See  
3951 - @1@filename@1@include/qpdf/QPDFMatrix.hh@2@filename@2@ for  
3952 - details. This class is for working with transformation  
3953 - matrices. Some methods in ``QPDFPageObjectHelper`` make use of  
3954 - this to make information about transformation matrices  
3955 - available. For an example, see  
3956 - @1@filename@1@examples/pdf-overlay-page.cc@2@filename@2@.  
3957 -  
3958 - - Several new methods were added to  
3959 - ``QPDFAcroFormDocumentHelper`` for adding, removing, getting  
3960 - information about, and enumerating form fields.  
3961 -  
3962 - - Add method  
3963 - ``QPDFAcroFormDocumentHelper::transformAnnotations``, which  
3964 - applies a transformation to each annotation on a page.  
3965 -  
3966 - - Add ``QPDFPageObjectHelper::copyAnnotations``, which copies  
3967 - annotations and, if applicable, associated form fields, from  
3968 - one page to another, possibly transforming the rectangles.  
3969 -  
3970 - - Build Changes  
3971 -  
3972 - - A C++-14 compiler is now required to build qpdf. There is no  
3973 - intention to require anything newer than that for a while.  
3974 - C++-14 includes modest enhancements to C++-11 and appears to be  
3975 - supported about as widely as C++-11.  
3976 -  
3977 - - Bug Fixes  
3978 -  
3979 - - The @1@option@1@--flatten-rotation@2@option@2@ option applies  
3980 - transformations to any annotations that may be on the page.  
3981 -  
3982 - - If a form XObject lacks a resources dictionary, consider any  
3983 - names in that form XObject to be referenced from the containing  
3984 - page. This is compliant with older PDF versions. Also detect if  
3985 - any form XObjects have any unresolved names and, if so, don't  
3986 - remove unreferenced resources from them or from the page that  
3987 - contains them. Unfortunately this has the side effect of  
3988 - preventing removal of unreferenced resources in some cases  
3989 - where names appear that don't refer to resources, such as with  
3990 - tagged PDF. This is a bit of a corner case that is not likely  
3991 - to cause a significant problem in practice, but the only side  
3992 - effect would be lack of removal of shared resources. A future  
3993 - version of qpdf may be more sophisticated in its detection of  
3994 - names that refer to resources.  
3995 -  
3996 - - Properly handle strings if they appear in inline image  
3997 - dictionaries while externalizing inline images. 3809 + - CLI Behavior Changes
  3810 +
  3811 + - Operations that work on combining pages are much better about
  3812 + protecting form fields. In particular,
  3813 + @1@option@1@--split-pages@2@option@2@ and
  3814 + @1@option@1@--pages@2@option@2@ now preserve interaction form
  3815 + functionality by copying the relevant form field information
  3816 + from the original files. Additionally, if you use
  3817 + @1@option@1@--pages@2@option@2@ to select only some pages from
  3818 + the original input file, unused form fields are removed, which
  3819 + prevents lots of unused annotations from being retained.
  3820 +
  3821 + - By default, @1@command@1@qpdf@2@command@2@ no longer allows
  3822 + creation of encrypted PDF files whose user password is
  3823 + non-empty and owner password is empty when a 256-bit key is in
  3824 + use. The @1@option@1@--allow-insecure@2@option@2@ option,
  3825 + specified inside the @1@option@1@--encrypt@2@option@2@ options,
  3826 + allows creation of such files. Behavior changes in the CLI are
  3827 + avoided when possible, but an exception was made here because
  3828 + this is security-related. qpdf must always allow creation of
  3829 + weird files for testing purposes, but it should not default to
  3830 + letting users unknowingly create insecure files.
  3831 +
  3832 + - Library Behavior Changes
  3833 +
  3834 + - Note: the changes in this section cause differences in output
  3835 + in some cases. These differences change the syntax of the PDF
  3836 + but do not change the semantics (meaning). I make a strong
  3837 + effort to avoid gratuitous changes in qpdf's output so that
  3838 + qpdf changes don't break people's tests. In this case, the
  3839 + changes significantly improve the readability of the generated
  3840 + PDF and don't affect any output that's generated by simple
  3841 + transformation. If you are annoyed by having to update test
  3842 + files, please rest assured that changes like this have been and
  3843 + will continue to be rare events.
  3844 +
  3845 + - ``QPDFObjectHandle::newUnicodeString`` now uses whichever of
  3846 + ASCII, PDFDocEncoding, of UTF-16 is sufficient to encode all
  3847 + the characters in the string. This reduces needless encoding in
  3848 + UTF-16 of strings that can be encoded in ASCII. This change may
  3849 + cause qpdf to generate different output than before when form
  3850 + field values are set using ``QPDFFormFieldObjectHelper`` but
  3851 + does not change the meaning of the output.
  3852 +
  3853 + - The code that places form XObjects and also the code that
  3854 + flattens rotations trim trailing zeroes from real numbers that
  3855 + they calculate. This causes slight (but semantically
  3856 + equivalent) differences in generated appearance streams and
  3857 + form XObject invocations in overlay/underlay code or in user
  3858 + code that calls the methods that place form XObjects on a page.
  3859 +
  3860 + - CLI Enhancements
  3861 +
  3862 + - Add new command line options for listing, saving, adding,
  3863 + removing, and and copying file attachments. See `Embedded
  3864 + Files/Attachments Options <#ref.attachments>`__ for details.
  3865 +
  3866 + - Page splitting and merging operations, as well as
  3867 + @1@option@1@--flatten-rotation@2@option@2@, are better behaved
  3868 + with respect to annotations and interactive form fields. In
  3869 + most cases, interactive form field functionality and proper
  3870 + formatting and functionality of annotations is preserved by
  3871 + these operations. There are still some cases that aren't
  3872 + perfect, such as when functionality of annotations depends on
  3873 + document-level data that qpdf doesn't yet understand or when
  3874 + there are problems with referential integrity among form fields
  3875 + and annotations (e.g., when a single form field object or its
  3876 + associated annotations are shared across multiple pages, a case
  3877 + that is out of spec but that works in most viewers anyway).
  3878 +
  3879 + - The option
  3880 + @1@option@1@--password-file=@1@replaceable@1@filename@2@replaceable@2@@2@option@2@
  3881 + can now be used to read the decryption password from a file.
  3882 + You can use ``-`` as the file name to read the password from
  3883 + standard input. This is an easier/more obvious way to read
  3884 + passwords from files or standard input than using
  3885 + @1@option@1@@file@2@option@2@ for this purpose.
  3886 +
  3887 + - Add some information about attachments to the json output, and
  3888 + added ``attachments`` as an additional json key. The
  3889 + information included here is limited to the preferred name and
  3890 + content stream and a reference to the file spec object. This is
  3891 + enough detail for clients to avoid the hassle of navigating a
  3892 + name tree and provides what is needed for basic enumeration and
  3893 + extraction of attachments. More detailed information can be
  3894 + obtained by following the reference to the file spec object.
  3895 +
  3896 + - Add numeric option to @1@option@1@--collate@2@option@2@. If
  3897 + @1@option@1@--collate=@1@replaceable@1@n@2@replaceable@2@@2@option@2@
  3898 + is given, take pages in groups of
  3899 + @1@replaceable@1@n@2@replaceable@2@ from the given files.
  3900 +
  3901 + - It is now valid to provide @1@option@1@--rotate=0@2@option@2@
  3902 + to clear rotation from a page.
  3903 +
  3904 + - Library Enhancements
  3905 +
  3906 + - This release includes numerous additions to the API. Not all
  3907 + changes are listed here. Please see the
  3908 + @1@filename@1@ChangeLog@2@filename@2@ file in the source
  3909 + distribution for a comprehensive list. Highlights appear below.
  3910 +
  3911 + - Add ``QPDFObjectHandle::ditems()`` and
  3912 + ``QPDFObjectHandle::aitems()`` that enable C++-style iteration,
  3913 + including range-for iteration, over dictionary and array
  3914 + QPDFObjectHandles. See comments in
  3915 + @1@filename@1@include/qpdf/QPDFObjectHandle.hh@2@filename@2@
  3916 + and
  3917 + @1@filename@1@examples/pdf-name-number-tree.cc@2@filename@2@
  3918 + for details.
  3919 +
  3920 + - Add ``QPDFObjectHandle::copyStream`` for making a copy of a
  3921 + stream within the same ``QPDF`` instance.
  3922 +
  3923 + - Add new helper classes for supporting file attachments, also
  3924 + known as embedded files. New classes are
  3925 + ``QPDFEmbeddedFileDocumentHelper``,
  3926 + ``QPDFFileSpecObjectHelper``, and ``QPDFEFStreamObjectHelper``.
  3927 + See their respective headers for details and
  3928 + @1@filename@1@examples/pdf-attach-file.cc@2@filename@2@ for an
  3929 + example.
  3930 +
  3931 + - Add a version of ``QPDFObjectHandle::parse`` that takes a
  3932 + ``QPDF`` pointer as context so that it can parse strings
  3933 + containing indirect object references. This is illustrated in
  3934 + @1@filename@1@examples/pdf-attach-file.cc@2@filename@2@.
  3935 +
  3936 + - Re-implement ``QPDFNameTreeObjectHelper`` and
  3937 + ``QPDFNumberTreeObjectHelper`` to be more efficient, add an
  3938 + iterator-based API, give them the capability to repair broken
  3939 + trees, and create methods for modifying the trees. With this
  3940 + change, qpdf has a robust read/write implementation of name and
  3941 + number trees.
  3942 +
  3943 + - Add new versions of ``QPDFObjectHandle::replaceStreamData``
  3944 + that take ``std::function`` objects for cases when you need
  3945 + something between a static string and a full-fledged
  3946 + StreamDataProvider. Using this with ``QUtil::file_provider`` is
  3947 + a very easy way to create a stream from the contents of a file.
  3948 +
  3949 + - The ``QPDFMatrix`` class, formerly a private, internal class,
  3950 + has been added to the public API. See
  3951 + @1@filename@1@include/qpdf/QPDFMatrix.hh@2@filename@2@ for
  3952 + details. This class is for working with transformation
  3953 + matrices. Some methods in ``QPDFPageObjectHelper`` make use of
  3954 + this to make information about transformation matrices
  3955 + available. For an example, see
  3956 + @1@filename@1@examples/pdf-overlay-page.cc@2@filename@2@.
  3957 +
  3958 + - Several new methods were added to
  3959 + ``QPDFAcroFormDocumentHelper`` for adding, removing, getting
  3960 + information about, and enumerating form fields.
  3961 +
  3962 + - Add method
  3963 + ``QPDFAcroFormDocumentHelper::transformAnnotations``, which
  3964 + applies a transformation to each annotation on a page.
  3965 +
  3966 + - Add ``QPDFPageObjectHelper::copyAnnotations``, which copies
  3967 + annotations and, if applicable, associated form fields, from
  3968 + one page to another, possibly transforming the rectangles.
  3969 +
  3970 + - Build Changes
  3971 +
  3972 + - A C++-14 compiler is now required to build qpdf. There is no
  3973 + intention to require anything newer than that for a while.
  3974 + C++-14 includes modest enhancements to C++-11 and appears to be
  3975 + supported about as widely as C++-11.
  3976 +
  3977 + - Bug Fixes
  3978 +
  3979 + - The @1@option@1@--flatten-rotation@2@option@2@ option applies
  3980 + transformations to any annotations that may be on the page.
  3981 +
  3982 + - If a form XObject lacks a resources dictionary, consider any
  3983 + names in that form XObject to be referenced from the containing
  3984 + page. This is compliant with older PDF versions. Also detect if
  3985 + any form XObjects have any unresolved names and, if so, don't
  3986 + remove unreferenced resources from them or from the page that
  3987 + contains them. Unfortunately this has the side effect of
  3988 + preventing removal of unreferenced resources in some cases
  3989 + where names appear that don't refer to resources, such as with
  3990 + tagged PDF. This is a bit of a corner case that is not likely
  3991 + to cause a significant problem in practice, but the only side
  3992 + effect would be lack of removal of shared resources. A future
  3993 + version of qpdf may be more sophisticated in its detection of
  3994 + names that refer to resources.
  3995 +
  3996 + - Properly handle strings if they appear in inline image
  3997 + dictionaries while externalizing inline images.
3998 3998
3999 10.1.0: January 5, 2021 3999 10.1.0: January 5, 2021
4000 - - CLI Enhancements 4000 + - CLI Enhancements
4001 4001
4002 - - Add @1@option@1@--flatten-rotation@2@option@2@ command-line  
4003 - option, which causes all pages that are rotated using  
4004 - parameters in the page's dictionary to instead be identically  
4005 - rotated in the page's contents. The change is not user-visible  
4006 - for compliant PDF readers but can be used to work around broken  
4007 - PDF applications that don't properly handle page rotation. 4002 + - Add @1@option@1@--flatten-rotation@2@option@2@ command-line
  4003 + option, which causes all pages that are rotated using
  4004 + parameters in the page's dictionary to instead be identically
  4005 + rotated in the page's contents. The change is not user-visible
  4006 + for compliant PDF readers but can be used to work around broken
  4007 + PDF applications that don't properly handle page rotation.
4008 4008
4009 - - Library Enhancements 4009 + - Library Enhancements
4010 4010
4011 - - Support for user-provided (pluggable, modular) stream filters.  
4012 - It is now possible to derive a class from ``QPDFStreamFilter``  
4013 - and register it with ``QPDF`` so that regular library methods,  
4014 - including those used by ``QPDFWriter``, can decode streams with  
4015 - filters not directly supported by the library. The example  
4016 - @1@filename@1@examples/pdf-custom-filter.cc@2@filename@2@  
4017 - illustrates how to use this capability. 4011 + - Support for user-provided (pluggable, modular) stream filters.
  4012 + It is now possible to derive a class from ``QPDFStreamFilter``
  4013 + and register it with ``QPDF`` so that regular library methods,
  4014 + including those used by ``QPDFWriter``, can decode streams with
  4015 + filters not directly supported by the library. The example
  4016 + @1@filename@1@examples/pdf-custom-filter.cc@2@filename@2@
  4017 + illustrates how to use this capability.
4018 4018
4019 - - Add methods to ``QPDFPageObjectHelper`` to iterate through  
4020 - XObjects on a page or form XObjects, possibly recursing into  
4021 - nested form XObjects: ``forEachXObject``, ``ForEachImage``,  
4022 - ``forEachFormXObject``. 4019 + - Add methods to ``QPDFPageObjectHelper`` to iterate through
  4020 + XObjects on a page or form XObjects, possibly recursing into
  4021 + nested form XObjects: ``forEachXObject``, ``ForEachImage``,
  4022 + ``forEachFormXObject``.
4023 4023
4024 - - Enhance several methods in ``QPDFPageObjectHelper`` to work  
4025 - with form XObjects as well as pages, as noted in comments. See  
4026 - @1@filename@1@ChangeLog@2@filename@2@ for a full list. 4024 + - Enhance several methods in ``QPDFPageObjectHelper`` to work
  4025 + with form XObjects as well as pages, as noted in comments. See
  4026 + @1@filename@1@ChangeLog@2@filename@2@ for a full list.
4027 4027
4028 - - Rename some functions in ``QPDFPageObjectHelper``, while  
4029 - keeping old names for compatibility: 4028 + - Rename some functions in ``QPDFPageObjectHelper``, while
  4029 + keeping old names for compatibility:
4030 4030
4031 - - ``getPageImages`` to ``getImages`` 4031 + - ``getPageImages`` to ``getImages``
4032 4032
4033 - - ``filterPageContents`` to ``filterContents`` 4033 + - ``filterPageContents`` to ``filterContents``
4034 4034
4035 - - ``pipePageContents`` to ``pipeContents`` 4035 + - ``pipePageContents`` to ``pipeContents``
4036 4036
4037 - - ``parsePageContents`` to ``parseContents`` 4037 + - ``parsePageContents`` to ``parseContents``
4038 4038
4039 - - Add method ``QPDFPageObjectHelper::getFormXObjects`` to return  
4040 - a map of form XObjects directly on a page or form XObject 4039 + - Add method ``QPDFPageObjectHelper::getFormXObjects`` to return
  4040 + a map of form XObjects directly on a page or form XObject
4041 4041
4042 - - Add new helper methods to ``QPDFObjectHandle``:  
4043 - ``isFormXObject``, ``isImage`` 4042 + - Add new helper methods to ``QPDFObjectHandle``:
  4043 + ``isFormXObject``, ``isImage``
4044 4044
4045 - - Add the optional ``allow_streams`` parameter  
4046 - ``QPDFObjectHandle::makeDirect``. When  
4047 - ``QPDFObjectHandle::makeDirect`` is called in this way, it  
4048 - preserves references to streams rather than throwing an  
4049 - exception. 4045 + - Add the optional ``allow_streams`` parameter
  4046 + ``QPDFObjectHandle::makeDirect``. When
  4047 + ``QPDFObjectHandle::makeDirect`` is called in this way, it
  4048 + preserves references to streams rather than throwing an
  4049 + exception.
4050 4050
4051 - - Add ``QPDFObjectHandle::setFilterOnWrite`` method. Calling this  
4052 - on a stream prevents ``QPDFWriter`` from attempting to  
4053 - uncompress, recompress, or otherwise filter a stream even if it  
4054 - could. Developers can use this to protect streams that are  
4055 - optimized should be protected from ``QPDFWriter``'s default  
4056 - behavior for any other reason. 4051 + - Add ``QPDFObjectHandle::setFilterOnWrite`` method. Calling this
  4052 + on a stream prevents ``QPDFWriter`` from attempting to
  4053 + uncompress, recompress, or otherwise filter a stream even if it
  4054 + could. Developers can use this to protect streams that are
  4055 + optimized should be protected from ``QPDFWriter``'s default
  4056 + behavior for any other reason.
4057 4057
4058 - - Add ``ostream`` ``<<`` operator for ``QPDFObjGen``. This is  
4059 - useful to have for debugging. 4058 + - Add ``ostream`` ``<<`` operator for ``QPDFObjGen``. This is
  4059 + useful to have for debugging.
4060 4060
4061 - - Add method ``QPDFPageObjectHelper::flattenRotation``, which  
4062 - replaces a page's ``/Rotate`` keyword by rotating the page  
4063 - within the content stream and altering the page's bounding  
4064 - boxes so the rendering is the same. This can be used to work  
4065 - around buggy PDF readers that can't properly handle page  
4066 - rotation. 4061 + - Add method ``QPDFPageObjectHelper::flattenRotation``, which
  4062 + replaces a page's ``/Rotate`` keyword by rotating the page
  4063 + within the content stream and altering the page's bounding
  4064 + boxes so the rendering is the same. This can be used to work
  4065 + around buggy PDF readers that can't properly handle page
  4066 + rotation.
4067 4067
4068 - - C API Enhancements 4068 + - C API Enhancements
4069 4069
4070 - - Add several new functions to the C API for working with  
4071 - objects. These are wrappers around many of the methods in  
4072 - ``QPDFObjectHandle``. Their inclusion adds considerable new  
4073 - capability to the C API. 4070 + - Add several new functions to the C API for working with
  4071 + objects. These are wrappers around many of the methods in
  4072 + ``QPDFObjectHandle``. Their inclusion adds considerable new
  4073 + capability to the C API.
4074 4074
4075 - - Add ``qpdf_register_progress_reporter`` to the C API,  
4076 - corresponding to ``QPDFWriter::registerProgressReporter``. 4075 + - Add ``qpdf_register_progress_reporter`` to the C API,
  4076 + corresponding to ``QPDFWriter::registerProgressReporter``.
4077 4077
4078 - - Performance Enhancements 4078 + - Performance Enhancements
4079 4079
4080 - - Improve steps ``QPDFWriter`` takes to prepare a ``QPDF`` object  
4081 - for writing, resulting in about an 8% improvement in write  
4082 - performance while allowing indirect objects to appear in  
4083 - ``/DecodeParms``. 4080 + - Improve steps ``QPDFWriter`` takes to prepare a ``QPDF`` object
  4081 + for writing, resulting in about an 8% improvement in write
  4082 + performance while allowing indirect objects to appear in
  4083 + ``/DecodeParms``.
4084 4084
4085 - - When extracting pages, the @1@command@1@qpdf@2@command@2@ CLI  
4086 - only removes unreferenced resources from the pages that are  
4087 - being kept, resulting in a significant performance improvement  
4088 - when extracting small numbers of pages from large, complex  
4089 - documents. 4085 + - When extracting pages, the @1@command@1@qpdf@2@command@2@ CLI
  4086 + only removes unreferenced resources from the pages that are
  4087 + being kept, resulting in a significant performance improvement
  4088 + when extracting small numbers of pages from large, complex
  4089 + documents.
4090 4090
4091 - - Bug Fixes 4091 + - Bug Fixes
4092 4092
4093 - - ``QPDFPageObjectHelper::externalizeInlineImages`` was not  
4094 - externalizing images referenced from form XObjects that  
4095 - appeared on the page. 4093 + - ``QPDFPageObjectHelper::externalizeInlineImages`` was not
  4094 + externalizing images referenced from form XObjects that
  4095 + appeared on the page.
4096 4096
4097 - - ``QPDFObjectHandle::filterPageContents`` was broken for pages  
4098 - with multiple content streams. 4097 + - ``QPDFObjectHandle::filterPageContents`` was broken for pages
  4098 + with multiple content streams.
4099 4099
4100 - - Tweak zsh completion code to behave a little better with  
4101 - respect to path completion. 4100 + - Tweak zsh completion code to behave a little better with
  4101 + respect to path completion.
4102 4102
4103 10.0.4: November 21, 2020 4103 10.0.4: November 21, 2020
4104 - - Bug Fixes 4104 + - Bug Fixes
4105 4105
4106 - - Fix a handful of integer overflows. This includes cases found  
4107 - by fuzzing as well as having qpdf not do range checking on  
4108 - unused values in the xref stream. 4106 + - Fix a handful of integer overflows. This includes cases found
  4107 + by fuzzing as well as having qpdf not do range checking on
  4108 + unused values in the xref stream.
4109 4109
4110 10.0.3: October 31, 2020 4110 10.0.3: October 31, 2020
4111 - - Bug Fixes 4111 + - Bug Fixes
4112 4112
4113 - - The fix to the bug involving copying streams with indirect  
4114 - filters was incorrect and introduced a new, more serious bug.  
4115 - The original bug has been fixed correctly, as has the bug  
4116 - introduced in 10.0.2. 4113 + - The fix to the bug involving copying streams with indirect
  4114 + filters was incorrect and introduced a new, more serious bug.
  4115 + The original bug has been fixed correctly, as has the bug
  4116 + introduced in 10.0.2.
4117 4117
4118 10.0.2: October 27, 2020 4118 10.0.2: October 27, 2020
4119 - - Bug Fixes  
4120 -  
4121 - - When concatenating content streams, as with  
4122 - @1@option@1@--coalesce-contents@2@option@2@, there were cases  
4123 - in which qpdf would merge two lexical tokens together, creating  
4124 - invalid results. A newline is now inserted between merged  
4125 - content streams if one is not already present.  
4126 -  
4127 - - Fix an internal error that could occur when copying foreign  
4128 - streams whose stream data had been replaced using a stream data  
4129 - provider if those streams had indirect filters or decode  
4130 - parameters. This is a rare corner case.  
4131 -  
4132 - - Ensure that the caller's locale settings do not change the  
4133 - results of numeric conversions performed internally by the qpdf  
4134 - library. Note that the problem here could only be caused when  
4135 - the qpdf library was used programmatically. Using the qpdf CLI  
4136 - already ignored the user's locale for numeric conversion.  
4137 -  
4138 - - Fix several instances in which warnings were not suppressed in  
4139 - spite of @1@option@1@--no-warn@2@option@2@ and/or errors or  
4140 - warnings were written to standard output rather than standard  
4141 - error.  
4142 -  
4143 - - Fixed a memory leak that could occur under specific  
4144 - circumstances when  
4145 - @1@option@1@--object-streams=generate@2@option@2@ was used.  
4146 -  
4147 - - Fix various integer overflows and similar conditions found by  
4148 - the OSS-Fuzz project.  
4149 -  
4150 - - Enhancements  
4151 -  
4152 - - New option @1@option@1@--warning-exit-0@2@option@2@ causes qpdf  
4153 - to exit with a status of ``0`` rather than ``3`` if there are  
4154 - warnings but no errors. Combine with  
4155 - @1@option@1@--no-warn@2@option@2@ to completely ignore  
4156 - warnings.  
4157 -  
4158 - - Performance improvements have been made to  
4159 - ``QPDF::processMemoryFile``.  
4160 -  
4161 - - The OpenSSL crypto provider produces more detailed error  
4162 - messages.  
4163 -  
4164 - - Build Changes  
4165 -  
4166 - - The option @1@option@1@--disable-rpath@2@option@2@ is now  
4167 - supported by qpdf's @1@command@1@./configure@2@command@2@  
4168 - script. Some distributions' packaging standards recommended the  
4169 - use of this option.  
4170 -  
4171 - - Selection of a printf format string for ``long long`` has  
4172 - been moved from ``ifdefs`` to an autoconf  
4173 - test. If you are using your own build system, you will need to  
4174 - provide a value for ``LL_FMT`` in  
4175 - @1@filename@1@libqpdf/qpdf/qpdf-config.h@2@filename@2@, which  
4176 - would typically be ``"%lld"`` or, for some Windows compilers,  
4177 - ``"%I64d"``.  
4178 -  
4179 - - Several improvements were made to build-time configuration of  
4180 - the OpenSSL crypto provider.  
4181 -  
4182 - - A nearly stand-alone Linux binary zip file is now included with  
4183 - the qpdf release. This is built on an older (but supported)  
4184 - Ubuntu LTS release, but would work on most reasonably recent  
4185 - Linux distributions. It contains only the executables and  
4186 - required shared libraries that would not be present on a  
4187 - minimal system. It can be used for including qpdf in a minimal  
4188 - environment, such as a docker container. The zip file is also  
4189 - known to work as a layer in AWS Lambda.  
4190 -  
4191 - - QPDF's automated build has been migrated from Azure Pipelines  
4192 - to GitHub Actions.  
4193 -  
4194 - - Windows-specific Changes  
4195 -  
4196 - - The Windows executables distributed with qpdf releases now use  
4197 - the OpenSSL crypto provider by default. The native crypto  
4198 - provider is also compiled in and can be selected at runtime  
4199 - with the ``QPDF_CRYPTO_PROVIDER`` environment variable.  
4200 -  
4201 - - Improvements have been made to how a cryptographic provider is  
4202 - obtained in the native Windows crypto implementation. However  
4203 - mostly this is shadowed by OpenSSL being used by default. 4119 + - Bug Fixes
  4120 +
  4121 + - When concatenating content streams, as with
  4122 + @1@option@1@--coalesce-contents@2@option@2@, there were cases
  4123 + in which qpdf would merge two lexical tokens together, creating
  4124 + invalid results. A newline is now inserted between merged
  4125 + content streams if one is not already present.
  4126 +
  4127 + - Fix an internal error that could occur when copying foreign
  4128 + streams whose stream data had been replaced using a stream data
  4129 + provider if those streams had indirect filters or decode
  4130 + parameters. This is a rare corner case.
  4131 +
  4132 + - Ensure that the caller's locale settings do not change the
  4133 + results of numeric conversions performed internally by the qpdf
  4134 + library. Note that the problem here could only be caused when
  4135 + the qpdf library was used programmatically. Using the qpdf CLI
  4136 + already ignored the user's locale for numeric conversion.
  4137 +
  4138 + - Fix several instances in which warnings were not suppressed in
  4139 + spite of @1@option@1@--no-warn@2@option@2@ and/or errors or
  4140 + warnings were written to standard output rather than standard
  4141 + error.
  4142 +
  4143 + - Fixed a memory leak that could occur under specific
  4144 + circumstances when
  4145 + @1@option@1@--object-streams=generate@2@option@2@ was used.
  4146 +
  4147 + - Fix various integer overflows and similar conditions found by
  4148 + the OSS-Fuzz project.
  4149 +
  4150 + - Enhancements
  4151 +
  4152 + - New option @1@option@1@--warning-exit-0@2@option@2@ causes qpdf
  4153 + to exit with a status of ``0`` rather than ``3`` if there are
  4154 + warnings but no errors. Combine with
  4155 + @1@option@1@--no-warn@2@option@2@ to completely ignore
  4156 + warnings.
  4157 +
  4158 + - Performance improvements have been made to
  4159 + ``QPDF::processMemoryFile``.
  4160 +
  4161 + - The OpenSSL crypto provider produces more detailed error
  4162 + messages.
  4163 +
  4164 + - Build Changes
  4165 +
  4166 + - The option @1@option@1@--disable-rpath@2@option@2@ is now
  4167 + supported by qpdf's @1@command@1@./configure@2@command@2@
  4168 + script. Some distributions' packaging standards recommended the
  4169 + use of this option.
  4170 +
  4171 + - Selection of a printf format string for ``long long`` has
  4172 + been moved from ``ifdefs`` to an autoconf
  4173 + test. If you are using your own build system, you will need to
  4174 + provide a value for ``LL_FMT`` in
  4175 + @1@filename@1@libqpdf/qpdf/qpdf-config.h@2@filename@2@, which
  4176 + would typically be ``"%lld"`` or, for some Windows compilers,
  4177 + ``"%I64d"``.
  4178 +
  4179 + - Several improvements were made to build-time configuration of
  4180 + the OpenSSL crypto provider.
  4181 +
  4182 + - A nearly stand-alone Linux binary zip file is now included with
  4183 + the qpdf release. This is built on an older (but supported)
  4184 + Ubuntu LTS release, but would work on most reasonably recent
  4185 + Linux distributions. It contains only the executables and
  4186 + required shared libraries that would not be present on a
  4187 + minimal system. It can be used for including qpdf in a minimal
  4188 + environment, such as a docker container. The zip file is also
  4189 + known to work as a layer in AWS Lambda.
  4190 +
  4191 + - QPDF's automated build has been migrated from Azure Pipelines
  4192 + to GitHub Actions.
  4193 +
  4194 + - Windows-specific Changes
  4195 +
  4196 + - The Windows executables distributed with qpdf releases now use
  4197 + the OpenSSL crypto provider by default. The native crypto
  4198 + provider is also compiled in and can be selected at runtime
  4199 + with the ``QPDF_CRYPTO_PROVIDER`` environment variable.
  4200 +
  4201 + - Improvements have been made to how a cryptographic provider is
  4202 + obtained in the native Windows crypto implementation. However
  4203 + mostly this is shadowed by OpenSSL being used by default.
4204 4204
4205 10.0.1: April 9, 2020 4205 10.0.1: April 9, 2020
4206 - - Bug Fixes 4206 + - Bug Fixes
4207 4207
4208 - - 10.0.0 introduced a bug in which calling  
4209 - ``QPDFObjectHandle::getStreamData`` on a stream that can't be  
4210 - filtered was returning the raw data instead of throwing an  
4211 - exception. This is now fixed. 4208 + - 10.0.0 introduced a bug in which calling
  4209 + ``QPDFObjectHandle::getStreamData`` on a stream that can't be
  4210 + filtered was returning the raw data instead of throwing an
  4211 + exception. This is now fixed.
4212 4212
4213 - - Fix a bug that was preventing qpdf from linking with some  
4214 - versions of clang on some platforms. 4213 + - Fix a bug that was preventing qpdf from linking with some
  4214 + versions of clang on some platforms.
4215 4215
4216 - - Enhancements 4216 + - Enhancements
4217 4217
4218 - - Improve the @1@filename@1@pdf-invert-images@2@filename@2@  
4219 - example to avoid having to load all the images into RAM at the  
4220 - same time. 4218 + - Improve the @1@filename@1@pdf-invert-images@2@filename@2@
  4219 + example to avoid having to load all the images into RAM at the
  4220 + same time.
4221 4221
4222 10.0.0: April 6, 2020 4222 10.0.0: April 6, 2020
4223 - - Performance Enhancements  
4224 -  
4225 - - The qpdf library and executable should run much faster in this  
4226 - version than in the last several releases. Several internal  
4227 - library optimizations have been made, and there has been  
4228 - improved behavior on page splitting as well. This version of  
4229 - qpdf should outperform any of the 8.x or 9.x versions.  
4230 -  
4231 - - Incompatible API (source-level) Changes (minor)  
4232 -  
4233 - - The ``QUtil::srandom`` method was removed. It didn't do  
4234 - anything unless insecure random numbers were compiled in, and  
4235 - they have been off by default for a long time. If you were  
4236 - calling it, just remove the call since it wasn't doing anything  
4237 - anyway.  
4238 -  
4239 - - Build/Packaging Changes  
4240 -  
4241 - - Add a ``openssl`` crypto provider, which is implemented with  
4242 - OpenSSL and also works with BoringSSL. Thanks to Dean Scarff  
4243 - for this contribution. If you maintain qpdf for a distribution,  
4244 - pay special attention to make sure that you are including  
4245 - support for the crypto providers you want. Package maintainers  
4246 - will have to weigh the advantages of allowing users to pick a  
4247 - crypto provider at runtime against the disadvantages of adding  
4248 - more dependencies to qpdf.  
4249 -  
4250 - - Allow qpdf to built on stripped down systems whose C/C++  
4251 - libraries lack the ``wchar_t`` type. Search for ``wchar_t`` in  
4252 - qpdf's README.md for details. This should be very rare, but it  
4253 - is known to be helpful in some embedded environments.  
4254 -  
4255 - - CLI Enhancements  
4256 -  
4257 - - Add ``objectinfo`` key to the JSON output. This will be a place  
4258 - to put computed metadata or other information about PDF objects  
4259 - that are not immediately evident in other ways or that seem  
4260 - useful for some other reason. In this version, information is  
4261 - provided about each object indicating whether it is a stream  
4262 - and, if so, what its length and filters are. Without this, it  
4263 - was not possible to tell conclusively from the JSON output  
4264 - alone whether or not an object was a stream. Run  
4265 - @1@command@1@qpdf --json-help@2@command@2@ for details.  
4266 -  
4267 - - Add new option  
4268 - @1@option@1@--remove-unreferenced-resources@2@option@2@ which  
4269 - takes ``auto``, ``yes``, or ``no`` as arguments. The new  
4270 - ``auto`` mode, which is the default, performs a fast heuristic  
4271 - over a PDF file when splitting pages to determine whether the  
4272 - expensive process of finding and removing unreferenced  
4273 - resources is likely to be of benefit. For most files, this new  
4274 - default will result in a significant performance improvement  
4275 - for splitting pages. See `Advanced Transformation  
4276 - Options <#ref.advanced-transformation>`__ for a more detailed  
4277 - discussion.  
4278 -  
4279 - - The @1@option@1@--preserve-unreferenced-resources@2@option@2@  
4280 - is now just a synonym for  
4281 - @1@option@1@--remove-unreferenced-resources=no@2@option@2@.  
4282 -  
4283 - - If the ``QPDF_EXECUTABLE`` environment variable is set when  
4284 - invoking @1@command@1@qpdf --bash-completion@2@command@2@ or  
4285 - @1@command@1@qpdf --zsh-completion@2@command@2@, the completion  
4286 - command that it outputs will refer to qpdf using the value of  
4287 - that variable rather than what @1@command@1@qpdf@2@command@2@  
4288 - determines its executable path to be. This can be useful when  
4289 - wrapping @1@command@1@qpdf@2@command@2@ with a script, working  
4290 - with a version in the source tree, using an AppImage, or other  
4291 - situations where there is some indirection.  
4292 -  
4293 - - Library Enhancements  
4294 -  
4295 - - Random number generation is now delegated to the crypto  
4296 - provider. The old behavior is still used by the native crypto  
4297 - provider. It is still possible to provide your own random  
4298 - number generator.  
4299 -  
4300 - - Add a new version of  
4301 - ``QPDFObjectHandle::StreamDataProvider::provideStreamData``  
4302 - that accepts the ``suppress_warnings`` and ``will_retry``  
4303 - options and allows a success code to be returned. This makes it  
4304 - possible to implement a ``StreamDataProvider`` that calls  
4305 - ``pipeStreamData`` on another stream and to pass the response  
4306 - back to the caller, which enables better error handling on  
4307 - those proxied streams.  
4308 -  
4309 - - Update ``QPDFObjectHandle::pipeStreamData`` to return an  
4310 - overall success code that goes beyond whether or not filtered  
4311 - data was written successfully. This allows better error  
4312 - handling of cases that were not filtering errors. You have to  
4313 - call this explicitly. Methods in previously existing APIs have  
4314 - the same semantics as before.  
4315 -  
4316 - - The ``QPDFPageObjectHelper::placeFormXObject`` method now  
4317 - allows separate control over whether it should be willing to  
4318 - shrink or expand objects to fit them better into the  
4319 - destination rectangle. The previous behavior was that shrinking  
4320 - was allowed but expansion was not. The previous behavior is  
4321 - still the default.  
4322 -  
4323 - - When calling the C API, any non-zero value passed to a boolean  
4324 - parameter is treated as ``TRUE``. Previously only the value  
4325 - ``1`` was accepted. This makes the C API behave more like most  
4326 - C interfaces and is known to improve compatibility with some  
4327 - Windows environments that dynamically load the DLL and call  
4328 - functions from it.  
4329 -  
4330 - - Add ``QPDFObjectHandle::unsafeShallowCopy`` for copying only  
4331 - top-level dictionary keys or array items. This is unsafe  
4332 - because it creates a situation in which changing a lower-level  
4333 - item in one object may also change it in another object, but  
4334 - for cases in which you *know* you are only inserting or  
4335 - replacing top-level items, it is much faster than  
4336 - ``QPDFObjectHandle::shallowCopy``.  
4337 -  
4338 - - Add ``QPDFObjectHandle::filterAsContents``, which filter's a  
4339 - stream's data as a content stream. This is useful for parsing  
4340 - the contents for form XObjects in the same way as parsing page  
4341 - content streams.  
4342 -  
4343 - - Bug Fixes  
4344 -  
4345 - - When detecting and removing unreferenced resources during page  
4346 - splitting, traverse into form XObjects and handle their  
4347 - resources dictionaries as well.  
4348 -  
4349 - - The same error recovery is applied to streams in other than the  
4350 - primary input file when merging or splitting pages. 4223 + - Performance Enhancements
  4224 +
  4225 + - The qpdf library and executable should run much faster in this
  4226 + version than in the last several releases. Several internal
  4227 + library optimizations have been made, and there has been
  4228 + improved behavior on page splitting as well. This version of
  4229 + qpdf should outperform any of the 8.x or 9.x versions.
  4230 +
  4231 + - Incompatible API (source-level) Changes (minor)
  4232 +
  4233 + - The ``QUtil::srandom`` method was removed. It didn't do
  4234 + anything unless insecure random numbers were compiled in, and
  4235 + they have been off by default for a long time. If you were
  4236 + calling it, just remove the call since it wasn't doing anything
  4237 + anyway.
  4238 +
  4239 + - Build/Packaging Changes
  4240 +
  4241 + - Add a ``openssl`` crypto provider, which is implemented with
  4242 + OpenSSL and also works with BoringSSL. Thanks to Dean Scarff
  4243 + for this contribution. If you maintain qpdf for a distribution,
  4244 + pay special attention to make sure that you are including
  4245 + support for the crypto providers you want. Package maintainers
  4246 + will have to weigh the advantages of allowing users to pick a
  4247 + crypto provider at runtime against the disadvantages of adding
  4248 + more dependencies to qpdf.
  4249 +
  4250 + - Allow qpdf to built on stripped down systems whose C/C++
  4251 + libraries lack the ``wchar_t`` type. Search for ``wchar_t`` in
  4252 + qpdf's README.md for details. This should be very rare, but it
  4253 + is known to be helpful in some embedded environments.
  4254 +
  4255 + - CLI Enhancements
  4256 +
  4257 + - Add ``objectinfo`` key to the JSON output. This will be a place
  4258 + to put computed metadata or other information about PDF objects
  4259 + that are not immediately evident in other ways or that seem
  4260 + useful for some other reason. In this version, information is
  4261 + provided about each object indicating whether it is a stream
  4262 + and, if so, what its length and filters are. Without this, it
  4263 + was not possible to tell conclusively from the JSON output
  4264 + alone whether or not an object was a stream. Run
  4265 + @1@command@1@qpdf --json-help@2@command@2@ for details.
  4266 +
  4267 + - Add new option
  4268 + @1@option@1@--remove-unreferenced-resources@2@option@2@ which
  4269 + takes ``auto``, ``yes``, or ``no`` as arguments. The new
  4270 + ``auto`` mode, which is the default, performs a fast heuristic
  4271 + over a PDF file when splitting pages to determine whether the
  4272 + expensive process of finding and removing unreferenced
  4273 + resources is likely to be of benefit. For most files, this new
  4274 + default will result in a significant performance improvement
  4275 + for splitting pages. See `Advanced Transformation
  4276 + Options <#ref.advanced-transformation>`__ for a more detailed
  4277 + discussion.
  4278 +
  4279 + - The @1@option@1@--preserve-unreferenced-resources@2@option@2@
  4280 + is now just a synonym for
  4281 + @1@option@1@--remove-unreferenced-resources=no@2@option@2@.
  4282 +
  4283 + - If the ``QPDF_EXECUTABLE`` environment variable is set when
  4284 + invoking @1@command@1@qpdf --bash-completion@2@command@2@ or
  4285 + @1@command@1@qpdf --zsh-completion@2@command@2@, the completion
  4286 + command that it outputs will refer to qpdf using the value of
  4287 + that variable rather than what @1@command@1@qpdf@2@command@2@
  4288 + determines its executable path to be. This can be useful when
  4289 + wrapping @1@command@1@qpdf@2@command@2@ with a script, working
  4290 + with a version in the source tree, using an AppImage, or other
  4291 + situations where there is some indirection.
  4292 +
  4293 + - Library Enhancements
  4294 +
  4295 + - Random number generation is now delegated to the crypto
  4296 + provider. The old behavior is still used by the native crypto
  4297 + provider. It is still possible to provide your own random
  4298 + number generator.
  4299 +
  4300 + - Add a new version of
  4301 + ``QPDFObjectHandle::StreamDataProvider::provideStreamData``
  4302 + that accepts the ``suppress_warnings`` and ``will_retry``
  4303 + options and allows a success code to be returned. This makes it
  4304 + possible to implement a ``StreamDataProvider`` that calls
  4305 + ``pipeStreamData`` on another stream and to pass the response
  4306 + back to the caller, which enables better error handling on
  4307 + those proxied streams.
  4308 +
  4309 + - Update ``QPDFObjectHandle::pipeStreamData`` to return an
  4310 + overall success code that goes beyond whether or not filtered
  4311 + data was written successfully. This allows better error
  4312 + handling of cases that were not filtering errors. You have to
  4313 + call this explicitly. Methods in previously existing APIs have
  4314 + the same semantics as before.
  4315 +
  4316 + - The ``QPDFPageObjectHelper::placeFormXObject`` method now
  4317 + allows separate control over whether it should be willing to
  4318 + shrink or expand objects to fit them better into the
  4319 + destination rectangle. The previous behavior was that shrinking
  4320 + was allowed but expansion was not. The previous behavior is
  4321 + still the default.
  4322 +
  4323 + - When calling the C API, any non-zero value passed to a boolean
  4324 + parameter is treated as ``TRUE``. Previously only the value
  4325 + ``1`` was accepted. This makes the C API behave more like most
  4326 + C interfaces and is known to improve compatibility with some
  4327 + Windows environments that dynamically load the DLL and call
  4328 + functions from it.
  4329 +
  4330 + - Add ``QPDFObjectHandle::unsafeShallowCopy`` for copying only
  4331 + top-level dictionary keys or array items. This is unsafe
  4332 + because it creates a situation in which changing a lower-level
  4333 + item in one object may also change it in another object, but
  4334 + for cases in which you *know* you are only inserting or
  4335 + replacing top-level items, it is much faster than
  4336 + ``QPDFObjectHandle::shallowCopy``.
  4337 +
  4338 + - Add ``QPDFObjectHandle::filterAsContents``, which filter's a
  4339 + stream's data as a content stream. This is useful for parsing
  4340 + the contents for form XObjects in the same way as parsing page
  4341 + content streams.
  4342 +
  4343 + - Bug Fixes
  4344 +
  4345 + - When detecting and removing unreferenced resources during page
  4346 + splitting, traverse into form XObjects and handle their
  4347 + resources dictionaries as well.
  4348 +
  4349 + - The same error recovery is applied to streams in other than the
  4350 + primary input file when merging or splitting pages.
4351 4351
4352 9.1.1: January 26, 2020 4352 9.1.1: January 26, 2020
4353 - - Build/Packaging Changes 4353 + - Build/Packaging Changes
4354 4354
4355 - - The fix-qdf program was converted from perl to C++. As such,  
4356 - qpdf no longer has a runtime dependency on perl. 4355 + - The fix-qdf program was converted from perl to C++. As such,
  4356 + qpdf no longer has a runtime dependency on perl.
4357 4357
4358 - - Library Enhancements 4358 + - Library Enhancements
4359 4359
4360 - - Added new helper routine ``QUtil::call_main_from_wmain`` which  
4361 - converts ``wchar_t`` arguments to UTF-8 encoded strings. This  
4362 - is useful for qpdf because library methods expect file names to  
4363 - be UTF-8 encoded, even on Windows 4360 + - Added new helper routine ``QUtil::call_main_from_wmain`` which
  4361 + converts ``wchar_t`` arguments to UTF-8 encoded strings. This
  4362 + is useful for qpdf because library methods expect file names to
  4363 + be UTF-8 encoded, even on Windows
4364 4364
4365 - - Added new ``QUtil::read_lines_from_file`` methods that take  
4366 - ``FILE*`` arguments and that allow preservation of end-of-line  
4367 - characters. This also fixes a bug where  
4368 - ``QUtil::read_lines_from_file`` wouldn't work properly with  
4369 - Unicode filenames. 4365 + - Added new ``QUtil::read_lines_from_file`` methods that take
  4366 + ``FILE*`` arguments and that allow preservation of end-of-line
  4367 + characters. This also fixes a bug where
  4368 + ``QUtil::read_lines_from_file`` wouldn't work properly with
  4369 + Unicode filenames.
4370 4370
4371 - - CLI Enhancements 4371 + - CLI Enhancements
4372 4372
4373 - - Added options @1@option@1@--is-encrypted@2@option@2@ and  
4374 - @1@option@1@--requires-password@2@option@2@ for testing whether  
4375 - a file is encrypted or requires a password other than the  
4376 - supplied (or empty) password. These communicate via exit  
4377 - status, making them useful for shell scripts. They also work on  
4378 - encrypted files with unknown passwords. 4373 + - Added options @1@option@1@--is-encrypted@2@option@2@ and
  4374 + @1@option@1@--requires-password@2@option@2@ for testing whether
  4375 + a file is encrypted or requires a password other than the
  4376 + supplied (or empty) password. These communicate via exit
  4377 + status, making them useful for shell scripts. They also work on
  4378 + encrypted files with unknown passwords.
4379 4379
4380 - - Added ``encrypt`` key to JSON options. With the exception of  
4381 - the reconstructed user password for older encryption formats,  
4382 - this provides the same information as  
4383 - @1@option@1@--show-encryption@2@option@2@ but in a consistent,  
4384 - parseable format. See output of @1@command@1@qpdf  
4385 - --json-help@2@command@2@ for details. 4380 + - Added ``encrypt`` key to JSON options. With the exception of
  4381 + the reconstructed user password for older encryption formats,
  4382 + this provides the same information as
  4383 + @1@option@1@--show-encryption@2@option@2@ but in a consistent,
  4384 + parseable format. See output of @1@command@1@qpdf
  4385 + --json-help@2@command@2@ for details.
4386 4386
4387 - - Bug Fixes 4387 + - Bug Fixes
4388 4388
4389 - - In QDF mode, be sure not to write more than one XRef stream to  
4390 - a file, even when  
4391 - @1@option@1@--preserve-unreferenced@2@option@2@ is used.  
4392 - @1@command@1@fix-qdf@2@command@2@ assumes that there is only  
4393 - one XRef stream, and that it appears at the end of the file. 4389 + - In QDF mode, be sure not to write more than one XRef stream to
  4390 + a file, even when
  4391 + @1@option@1@--preserve-unreferenced@2@option@2@ is used.
  4392 + @1@command@1@fix-qdf@2@command@2@ assumes that there is only
  4393 + one XRef stream, and that it appears at the end of the file.
4394 4394
4395 - - When externalizing inline images, properly handle images whose  
4396 - color space is a reference to an object in the page's resource  
4397 - dictionary. 4395 + - When externalizing inline images, properly handle images whose
  4396 + color space is a reference to an object in the page's resource
  4397 + dictionary.
4398 4398
4399 - - Windows-specific fix for acquiring crypt context with a new  
4400 - keyset. 4399 + - Windows-specific fix for acquiring crypt context with a new
  4400 + keyset.
4401 4401
4402 9.1.0: November 17, 2019 4402 9.1.0: November 17, 2019
4403 - - Build Changes  
4404 -  
4405 - - A C++-11 compiler is now required to build qpdf.  
4406 -  
4407 - - A new crypto provider that uses gnutls for crypto functions is  
4408 - now available and can be enabled at build time. See `Crypto  
4409 - Providers <#ref.crypto>`__ for more information about crypto  
4410 - providers and `Build Support For Crypto  
4411 - Providers <#ref.crypto.build>`__ for specific information about  
4412 - the build.  
4413 -  
4414 - - Library Enhancements  
4415 -  
4416 - - Incorporate contribution from Masamichi Hosoda to properly  
4417 - handle signature dictionaries by not including them in object  
4418 - streams, formatting the ``Contents`` key has a hexadecimal  
4419 - string, and excluding the ``/Contents`` key from encryption and  
4420 - decryption.  
4421 -  
4422 - - Incorporate contribution from Masamichi Hosoda to provide new  
4423 - API calls for getting file-level information about input and  
4424 - output files, enabling certain operations on the files at the  
4425 - file level rather than the object level. New methods include  
4426 - ``QPDF::getXRefTable()``,  
4427 - ``QPDFObjectHandle::getParsedOffset()``,  
4428 - ``QPDFWriter::getRenumberedObjGen(QPDFObjGen)``, and  
4429 - ``QPDFWriter::getWrittenXRefTable()``.  
4430 -  
4431 - - Support build-time and runtime selectable crypto providers.  
4432 - This includes the addition of new classes  
4433 - ``QPDFCryptoProvider`` and ``QPDFCryptoImpl`` and the  
4434 - recognition of the ``QPDF_CRYPTO_PROVIDER`` environment  
4435 - variable. Crypto providers are described in depth in `Crypto  
4436 - Providers <#ref.crypto>`__.  
4437 -  
4438 - - CLI Enhancements  
4439 -  
4440 - - Addition of the @1@option@1@--show-crypto@2@option@2@ option in  
4441 - support of selectable crypto providers, as described in `Crypto  
4442 - Providers <#ref.crypto>`__.  
4443 -  
4444 - - Allow ``:even`` or ``:odd`` to be appended to numeric ranges  
4445 - for specification of the even or odd pages from among the pages  
4446 - specified in the range.  
4447 -  
4448 - - Fix shell wildcard expansion behavior (``*`` and ``?``) of the  
4449 - @1@command@1@qpdf.exe@2@command@2@ as built my MSVC. 4403 + - Build Changes
  4404 +
  4405 + - A C++-11 compiler is now required to build qpdf.
  4406 +
  4407 + - A new crypto provider that uses gnutls for crypto functions is
  4408 + now available and can be enabled at build time. See `Crypto
  4409 + Providers <#ref.crypto>`__ for more information about crypto
  4410 + providers and `Build Support For Crypto
  4411 + Providers <#ref.crypto.build>`__ for specific information about
  4412 + the build.
  4413 +
  4414 + - Library Enhancements
  4415 +
  4416 + - Incorporate contribution from Masamichi Hosoda to properly
  4417 + handle signature dictionaries by not including them in object
  4418 + streams, formatting the ``Contents`` key has a hexadecimal
  4419 + string, and excluding the ``/Contents`` key from encryption and
  4420 + decryption.
  4421 +
  4422 + - Incorporate contribution from Masamichi Hosoda to provide new
  4423 + API calls for getting file-level information about input and
  4424 + output files, enabling certain operations on the files at the
  4425 + file level rather than the object level. New methods include
  4426 + ``QPDF::getXRefTable()``,
  4427 + ``QPDFObjectHandle::getParsedOffset()``,
  4428 + ``QPDFWriter::getRenumberedObjGen(QPDFObjGen)``, and
  4429 + ``QPDFWriter::getWrittenXRefTable()``.
  4430 +
  4431 + - Support build-time and runtime selectable crypto providers.
  4432 + This includes the addition of new classes
  4433 + ``QPDFCryptoProvider`` and ``QPDFCryptoImpl`` and the
  4434 + recognition of the ``QPDF_CRYPTO_PROVIDER`` environment
  4435 + variable. Crypto providers are described in depth in `Crypto
  4436 + Providers <#ref.crypto>`__.
  4437 +
  4438 + - CLI Enhancements
  4439 +
  4440 + - Addition of the @1@option@1@--show-crypto@2@option@2@ option in
  4441 + support of selectable crypto providers, as described in `Crypto
  4442 + Providers <#ref.crypto>`__.
  4443 +
  4444 + - Allow ``:even`` or ``:odd`` to be appended to numeric ranges
  4445 + for specification of the even or odd pages from among the pages
  4446 + specified in the range.
  4447 +
  4448 + - Fix shell wildcard expansion behavior (``*`` and ``?``) of the
  4449 + @1@command@1@qpdf.exe@2@command@2@ as built my MSVC.
4450 4450
4451 9.0.2: October 12, 2019 4451 9.0.2: October 12, 2019
4452 - - Bug Fix 4452 + - Bug Fix
4453 4453
4454 - - Fix the name of the temporary file used by  
4455 - @1@option@1@--replace-input@2@option@2@ so that it doesn't  
4456 - require path splitting and works with paths include  
4457 - directories. 4454 + - Fix the name of the temporary file used by
  4455 + @1@option@1@--replace-input@2@option@2@ so that it doesn't
  4456 + require path splitting and works with paths include
  4457 + directories.
4458 4458
4459 9.0.1: September 20, 2019 4459 9.0.1: September 20, 2019
4460 - - Bug Fixes/Enhancements 4460 + - Bug Fixes/Enhancements
4461 4461
4462 - - Fix some build and test issues on big-endian systems and  
4463 - compilers with characters that are unsigned by default. The  
4464 - problems were in build and test only. There were no actual bugs  
4465 - in the qpdf library itself relating to endianness or unsigned  
4466 - characters. 4462 + - Fix some build and test issues on big-endian systems and
  4463 + compilers with characters that are unsigned by default. The
  4464 + problems were in build and test only. There were no actual bugs
  4465 + in the qpdf library itself relating to endianness or unsigned
  4466 + characters.
4467 4467
4468 - - When a dictionary has a duplicated key, report this with a  
4469 - warning. The behavior of the library in this case is unchanged,  
4470 - but the error condition is no longer silently ignored. 4468 + - When a dictionary has a duplicated key, report this with a
  4469 + warning. The behavior of the library in this case is unchanged,
  4470 + but the error condition is no longer silently ignored.
4471 4471
4472 - - When a form field's display rectangle is erroneously specified  
4473 - with inverted coordinates, detect and correct this situation.  
4474 - This avoids some form fields from being flipped when flattening  
4475 - annotations on files with this condition. 4472 + - When a form field's display rectangle is erroneously specified
  4473 + with inverted coordinates, detect and correct this situation.
  4474 + This avoids some form fields from being flipped when flattening
  4475 + annotations on files with this condition.
4476 4476
4477 9.0.0: August 31, 2019 4477 9.0.0: August 31, 2019
4478 - - Incompatible API (source-level) Changes (minor)  
4479 -  
4480 - - The method ``QUtil::strcasecmp`` has been renamed to  
4481 - ``QUtil::str_compare_nocase``. This incompatible change is  
4482 - necessary to enable qpdf to build on platforms that define  
4483 - ``strcasecmp`` as a macro.  
4484 -  
4485 - - The ``QPDF::copyForeignObject`` method had an overloaded  
4486 - version that took a boolean parameter that was not used. If you  
4487 - were using this version, just omit the extra parameter.  
4488 -  
4489 - - There was a version ``QPDFTokenizer::expectInlineImage`` that  
4490 - took no arguments. This version has been removed since it  
4491 - caused the tokenizer to return incorrect inline images. A new  
4492 - version was added some time ago that produces correct output.  
4493 - This is a very low level method that doesn't make sense to call  
4494 - outside of qpdf's lexical engine. There are higher level  
4495 - methods for tokenizing content streams.  
4496 -  
4497 - - Change ``QPDFOutlineDocumentHelper::getTopLevelOutlines`` and  
4498 - ``QPDFOutlineObjectHelper::getKids`` to return a  
4499 - ``std::vector`` instead of a ``std::list`` of  
4500 - ``QPDFOutlineObjectHelper`` objects.  
4501 -  
4502 - - Remove method ``QPDFTokenizer::allowPoundAnywhereInName``. This  
4503 - function would allow creation of name tokens whose value would  
4504 - change when unparsed, which is never the correct behavior.  
4505 -  
4506 - - CLI Enhancements  
4507 -  
4508 - - The @1@option@1@--replace-input@2@option@2@ option may be given  
4509 - in place of an output file name. This causes qpdf to overwrite  
4510 - the input file with the output. See the description of  
4511 - @1@option@1@--replace-input@2@option@2@ in `Basic  
4512 - Options <#ref.basic-options>`__ for more details.  
4513 -  
4514 - - The @1@option@1@--recompress-flate@2@option@2@ instructs  
4515 - @1@command@1@qpdf@2@command@2@ to recompress streams that are  
4516 - already compressed with ``/FlateDecode``. Useful with  
4517 - @1@option@1@--compression-level@2@option@2@.  
4518 -  
4519 - - The  
4520 - @1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@  
4521 - sets the zlib compression level used for any streams compressed  
4522 - by ``/FlateDecode``. Most effective when combined with  
4523 - @1@option@1@--recompress-flate@2@option@2@.  
4524 -  
4525 - - Library Enhancements  
4526 -  
4527 - - A new namespace ``QIntC``, provided by  
4528 - @1@filename@1@qpdf/QIntC.hh@2@filename@2@, provides safe  
4529 - conversion methods between different integer types. These  
4530 - conversion methods do range checking to ensure that the cast  
4531 - can be performed with no loss of information. Every use of  
4532 - ``static_cast`` in the library was inspected to see if it could  
4533 - use one of these safe converters instead. See `Casting  
4534 - Policy <#ref.casting>`__ for additional details.  
4535 -  
4536 - - Method ``QPDF::anyWarnings`` tells whether there have been any  
4537 - warnings without clearing the list of warnings.  
4538 -  
4539 - - Method ``QPDF::closeInputSource`` closes or otherwise releases  
4540 - the input source. This enables the input file to be deleted or  
4541 - renamed.  
4542 -  
4543 - - New methods have been added to ``QUtil`` for converting back  
4544 - and forth between strings and unsigned integers:  
4545 - ``uint_to_string``, ``uint_to_string_base``,  
4546 - ``string_to_uint``, and ``string_to_ull``.  
4547 -  
4548 - - New methods have been added to ``QPDFObjectHandle`` that return  
4549 - the value of ``Integer`` objects as ``int`` or ``unsigned int``  
4550 - with range checking and sensible fallback values, and a new  
4551 - method was added to return an unsigned value. This makes it  
4552 - easier to write code that is safe from unintentional data loss.  
4553 - Functions: ``getUIntValue``, ``getIntValueAsInt``,  
4554 - ``getUIntValueAsUInt``.  
4555 -  
4556 - - When parsing content streams with  
4557 - ``QPDFObjectHandle::ParserCallbacks``, in place of the method  
4558 - ``handleObject(QPDFObjectHandle)``, the developer may override  
4559 - ``handleObject(QPDFObjectHandle, size_t offset, size_t  
4560 - length)``. If this method is defined, it will  
4561 - be invoked with the object along with its offset and length  
4562 - within the overall contents being parsed. Intervening spaces  
4563 - and comments are not included in offset and length.  
4564 - Additionally, a new method ``contentSize(size_t)`` may be  
4565 - implemented. If present, it will be called prior to the first  
4566 - call to ``handleObject`` with the total size in bytes of the  
4567 - combined contents.  
4568 -  
4569 - - New methods ``QPDF::userPasswordMatched`` and  
4570 - ``QPDF::ownerPasswordMatched`` have been added to enable a  
4571 - caller to determine whether the supplied password was the user  
4572 - password, the owner password, or both. This information is also  
4573 - displayed by @1@command@1@qpdf --show-encryption@2@command@2@  
4574 - and @1@command@1@qpdf --check@2@command@2@.  
4575 -  
4576 - - Static method ``Pl_Flate::setCompressionLevel`` can be called  
4577 - to set the zlib compression level globally used by all  
4578 - instances of Pl_Flate in deflate mode.  
4579 -  
4580 - - The method ``QPDFWriter::setRecompressFlate`` can be called to  
4581 - tell ``QPDFWriter`` to uncompress and recompress streams  
4582 - already compressed with ``/FlateDecode``.  
4583 -  
4584 - - The underlying implementation of QPDF arrays has been enhanced  
4585 - to be much more memory efficient when dealing with arrays with  
4586 - lots of nulls. This enables qpdf to use drastically less memory  
4587 - for certain types of files.  
4588 -  
4589 - - When traversing the pages tree, if nodes are encountered with  
4590 - invalid types, the types are fixed, and a warning is issued.  
4591 -  
4592 - - A new helper method ``QUtil::read_file_into_memory`` was added.  
4593 -  
4594 - - All conditions previously reported by  
4595 - ``QPDF::checkLinearization()`` as errors are now presented as  
4596 - warnings.  
4597 -  
4598 - - Name tokens containing the ``#`` character not preceded by two  
4599 - hexadecimal digits, which is invalid in PDF 1.2 and above, are  
4600 - properly handled by the library: a warning is generated, and  
4601 - the name token is properly preserved, even if invalid, in the  
4602 - output. See @1@filename@1@ChangeLog@2@filename@2@ for a more  
4603 - complete description of this change.  
4604 -  
4605 - - Bug Fixes  
4606 -  
4607 - - A small handful of memory issues, assertion failures, and  
4608 - unhandled exceptions that could occur on badly mangled input  
4609 - files have been fixed. Most of these problems were found by  
4610 - Google's OSS-Fuzz project.  
4611 -  
4612 - - When @1@command@1@qpdf --check@2@command@2@ or  
4613 - @1@command@1@qpdf --check-linearization@2@command@2@ encounters  
4614 - a file with linearization warnings but not errors, it now  
4615 - properly exits with exit code 3 instead of 2.  
4616 -  
4617 - - The @1@option@1@--completion-bash@2@option@2@ and  
4618 - @1@option@1@--completion-zsh@2@option@2@ options now work  
4619 - properly when qpdf is invoked as an AppImage.  
4620 -  
4621 - - Calling ``QPDFWriter::set*EncryptionParameters`` on a  
4622 - ``QPDFWriter`` object whose output filename has not yet been  
4623 - set no longer produces a segmentation fault.  
4624 -  
4625 - - When reading encrypted files, follow the spec more closely  
4626 - regarding encryption key length. This allows qpdf to open  
4627 - encrypted files in most cases when they have invalid or missing  
4628 - /Length keys in the encryption dictionary.  
4629 -  
4630 - - Build Changes  
4631 -  
4632 - - On platforms that support it, qpdf now builds with  
4633 - @1@option@1@-fvisibility=hidden@2@option@2@. If you build qpdf  
4634 - with your own build system, this is now safe to use. This  
4635 - prevents methods that are not part of the public API from being  
4636 - exported by the shared library, and makes qpdf's ELF shared  
4637 - libraries (used on Linux, MacOS, and most other UNIX flavors)  
4638 - behave more like the Windows DLL. Since the DLL already behaves  
4639 - in much this way, it is unlikely that there are any methods  
4640 - that were accidentally not exported. However, with ELF shared  
4641 - libraries, typeinfo for some classes has to be explicitly  
4642 - exported. If there are problems in dynamically linked code  
4643 - catching exceptions or subclassing, this could be the reason.  
4644 - If you see this, please report a bug at  
4645 - https://github.com/qpdf/qpdf/issues/.  
4646 -  
4647 - - QPDF is now compiled with integer conversion and sign  
4648 - conversion warnings enabled. Numerous changes were made to the  
4649 - library to make this safe.  
4650 -  
4651 - - QPDF's @1@command@1@make install@2@command@2@ target explicitly  
4652 - specifies the mode to use when installing files instead of  
4653 - relying the user's umask. It was previously doing this for some  
4654 - files but not others.  
4655 -  
4656 - - If @1@command@1@pkg-config@2@command@2@ is available, use it to  
4657 - locate @1@filename@1@libjpeg@2@filename@2@ and  
4658 - @1@filename@1@zlib@2@filename@2@ dependencies, falling back on  
4659 - old behavior if unsuccessful.  
4660 -  
4661 - - Other Notes  
4662 -  
4663 - - QPDF has been fully integrated into `Google's OSS-Fuzz  
4664 - project <https://github.com/google/oss-fuzz>`__. This project  
4665 - exercises code with randomly mutated inputs and is great for  
4666 - discovering hidden security crashes and security issues.  
4667 - Several bugs found by oss-fuzz have already been fixed in qpdf. 4478 + - Incompatible API (source-level) Changes (minor)
  4479 +
  4480 + - The method ``QUtil::strcasecmp`` has been renamed to
  4481 + ``QUtil::str_compare_nocase``. This incompatible change is
  4482 + necessary to enable qpdf to build on platforms that define
  4483 + ``strcasecmp`` as a macro.
  4484 +
  4485 + - The ``QPDF::copyForeignObject`` method had an overloaded
  4486 + version that took a boolean parameter that was not used. If you
  4487 + were using this version, just omit the extra parameter.
  4488 +
  4489 + - There was a version ``QPDFTokenizer::expectInlineImage`` that
  4490 + took no arguments. This version has been removed since it
  4491 + caused the tokenizer to return incorrect inline images. A new
  4492 + version was added some time ago that produces correct output.
  4493 + This is a very low level method that doesn't make sense to call
  4494 + outside of qpdf's lexical engine. There are higher level
  4495 + methods for tokenizing content streams.
  4496 +
  4497 + - Change ``QPDFOutlineDocumentHelper::getTopLevelOutlines`` and
  4498 + ``QPDFOutlineObjectHelper::getKids`` to return a
  4499 + ``std::vector`` instead of a ``std::list`` of
  4500 + ``QPDFOutlineObjectHelper`` objects.
  4501 +
  4502 + - Remove method ``QPDFTokenizer::allowPoundAnywhereInName``. This
  4503 + function would allow creation of name tokens whose value would
  4504 + change when unparsed, which is never the correct behavior.
  4505 +
  4506 + - CLI Enhancements
  4507 +
  4508 + - The @1@option@1@--replace-input@2@option@2@ option may be given
  4509 + in place of an output file name. This causes qpdf to overwrite
  4510 + the input file with the output. See the description of
  4511 + @1@option@1@--replace-input@2@option@2@ in `Basic
  4512 + Options <#ref.basic-options>`__ for more details.
  4513 +
  4514 + - The @1@option@1@--recompress-flate@2@option@2@ instructs
  4515 + @1@command@1@qpdf@2@command@2@ to recompress streams that are
  4516 + already compressed with ``/FlateDecode``. Useful with
  4517 + @1@option@1@--compression-level@2@option@2@.
  4518 +
  4519 + - The
  4520 + @1@option@1@--compression-level=@1@replaceable@1@level@2@replaceable@2@@2@option@2@
  4521 + sets the zlib compression level used for any streams compressed
  4522 + by ``/FlateDecode``. Most effective when combined with
  4523 + @1@option@1@--recompress-flate@2@option@2@.
  4524 +
  4525 + - Library Enhancements
  4526 +
  4527 + - A new namespace ``QIntC``, provided by
  4528 + @1@filename@1@qpdf/QIntC.hh@2@filename@2@, provides safe
  4529 + conversion methods between different integer types. These
  4530 + conversion methods do range checking to ensure that the cast
  4531 + can be performed with no loss of information. Every use of
  4532 + ``static_cast`` in the library was inspected to see if it could
  4533 + use one of these safe converters instead. See `Casting
  4534 + Policy <#ref.casting>`__ for additional details.
  4535 +
  4536 + - Method ``QPDF::anyWarnings`` tells whether there have been any
  4537 + warnings without clearing the list of warnings.
  4538 +
  4539 + - Method ``QPDF::closeInputSource`` closes or otherwise releases
  4540 + the input source. This enables the input file to be deleted or
  4541 + renamed.
  4542 +
  4543 + - New methods have been added to ``QUtil`` for converting back
  4544 + and forth between strings and unsigned integers:
  4545 + ``uint_to_string``, ``uint_to_string_base``,
  4546 + ``string_to_uint``, and ``string_to_ull``.
  4547 +
  4548 + - New methods have been added to ``QPDFObjectHandle`` that return
  4549 + the value of ``Integer`` objects as ``int`` or ``unsigned int``
  4550 + with range checking and sensible fallback values, and a new
  4551 + method was added to return an unsigned value. This makes it
  4552 + easier to write code that is safe from unintentional data loss.
  4553 + Functions: ``getUIntValue``, ``getIntValueAsInt``,
  4554 + ``getUIntValueAsUInt``.
  4555 +
  4556 + - When parsing content streams with
  4557 + ``QPDFObjectHandle::ParserCallbacks``, in place of the method
  4558 + ``handleObject(QPDFObjectHandle)``, the developer may override
  4559 + ``handleObject(QPDFObjectHandle, size_t offset, size_t
  4560 + length)``. If this method is defined, it will
  4561 + be invoked with the object along with its offset and length
  4562 + within the overall contents being parsed. Intervening spaces
  4563 + and comments are not included in offset and length.
  4564 + Additionally, a new method ``contentSize(size_t)`` may be
  4565 + implemented. If present, it will be called prior to the first
  4566 + call to ``handleObject`` with the total size in bytes of the
  4567 + combined contents.
  4568 +
  4569 + - New methods ``QPDF::userPasswordMatched`` and
  4570 + ``QPDF::ownerPasswordMatched`` have been added to enable a
  4571 + caller to determine whether the supplied password was the user
  4572 + password, the owner password, or both. This information is also
  4573 + displayed by @1@command@1@qpdf --show-encryption@2@command@2@
  4574 + and @1@command@1@qpdf --check@2@command@2@.
  4575 +
  4576 + - Static method ``Pl_Flate::setCompressionLevel`` can be called
  4577 + to set the zlib compression level globally used by all
  4578 + instances of Pl_Flate in deflate mode.
  4579 +
  4580 + - The method ``QPDFWriter::setRecompressFlate`` can be called to
  4581 + tell ``QPDFWriter`` to uncompress and recompress streams
  4582 + already compressed with ``/FlateDecode``.
  4583 +
  4584 + - The underlying implementation of QPDF arrays has been enhanced
  4585 + to be much more memory efficient when dealing with arrays with
  4586 + lots of nulls. This enables qpdf to use drastically less memory
  4587 + for certain types of files.
  4588 +
  4589 + - When traversing the pages tree, if nodes are encountered with
  4590 + invalid types, the types are fixed, and a warning is issued.
  4591 +
  4592 + - A new helper method ``QUtil::read_file_into_memory`` was added.
  4593 +
  4594 + - All conditions previously reported by
  4595 + ``QPDF::checkLinearization()`` as errors are now presented as
  4596 + warnings.
  4597 +
  4598 + - Name tokens containing the ``#`` character not preceded by two
  4599 + hexadecimal digits, which is invalid in PDF 1.2 and above, are
  4600 + properly handled by the library: a warning is generated, and
  4601 + the name token is properly preserved, even if invalid, in the
  4602 + output. See @1@filename@1@ChangeLog@2@filename@2@ for a more
  4603 + complete description of this change.
  4604 +
  4605 + - Bug Fixes
  4606 +
  4607 + - A small handful of memory issues, assertion failures, and
  4608 + unhandled exceptions that could occur on badly mangled input
  4609 + files have been fixed. Most of these problems were found by
  4610 + Google's OSS-Fuzz project.
  4611 +
  4612 + - When @1@command@1@qpdf --check@2@command@2@ or
  4613 + @1@command@1@qpdf --check-linearization@2@command@2@ encounters
  4614 + a file with linearization warnings but not errors, it now
  4615 + properly exits with exit code 3 instead of 2.
  4616 +
  4617 + - The @1@option@1@--completion-bash@2@option@2@ and
  4618 + @1@option@1@--completion-zsh@2@option@2@ options now work
  4619 + properly when qpdf is invoked as an AppImage.
  4620 +
  4621 + - Calling ``QPDFWriter::set*EncryptionParameters`` on a
  4622 + ``QPDFWriter`` object whose output filename has not yet been
  4623 + set no longer produces a segmentation fault.
  4624 +
  4625 + - When reading encrypted files, follow the spec more closely
  4626 + regarding encryption key length. This allows qpdf to open
  4627 + encrypted files in most cases when they have invalid or missing
  4628 + /Length keys in the encryption dictionary.
  4629 +
  4630 + - Build Changes
  4631 +
  4632 + - On platforms that support it, qpdf now builds with
  4633 + @1@option@1@-fvisibility=hidden@2@option@2@. If you build qpdf
  4634 + with your own build system, this is now safe to use. This
  4635 + prevents methods that are not part of the public API from being
  4636 + exported by the shared library, and makes qpdf's ELF shared
  4637 + libraries (used on Linux, MacOS, and most other UNIX flavors)
  4638 + behave more like the Windows DLL. Since the DLL already behaves
  4639 + in much this way, it is unlikely that there are any methods
  4640 + that were accidentally not exported. However, with ELF shared
  4641 + libraries, typeinfo for some classes has to be explicitly
  4642 + exported. If there are problems in dynamically linked code
  4643 + catching exceptions or subclassing, this could be the reason.
  4644 + If you see this, please report a bug at
  4645 + https://github.com/qpdf/qpdf/issues/.
  4646 +
  4647 + - QPDF is now compiled with integer conversion and sign
  4648 + conversion warnings enabled. Numerous changes were made to the
  4649 + library to make this safe.
  4650 +
  4651 + - QPDF's @1@command@1@make install@2@command@2@ target explicitly
  4652 + specifies the mode to use when installing files instead of
  4653 + relying the user's umask. It was previously doing this for some
  4654 + files but not others.
  4655 +
  4656 + - If @1@command@1@pkg-config@2@command@2@ is available, use it to
  4657 + locate @1@filename@1@libjpeg@2@filename@2@ and
  4658 + @1@filename@1@zlib@2@filename@2@ dependencies, falling back on
  4659 + old behavior if unsuccessful.
  4660 +
  4661 + - Other Notes
  4662 +
  4663 + - QPDF has been fully integrated into `Google's OSS-Fuzz
  4664 + project <https://github.com/google/oss-fuzz>`__. This project
  4665 + exercises code with randomly mutated inputs and is great for
  4666 + discovering hidden security crashes and security issues.
  4667 + Several bugs found by oss-fuzz have already been fixed in qpdf.
4668 4668
4669 8.4.2: May 18, 2019 4669 8.4.2: May 18, 2019
4670 This release has just one change: correction of a buffer overrun in 4670 This release has just one change: correction of a buffer overrun in
@@ -4672,1560 +4672,1560 @@ For a detailed list of changes, please see the file @@ -4672,1560 +4672,1560 @@ For a detailed list of changes, please see the file
4672 update. There are no code changes that affect non-Windows releases. 4672 update. There are no code changes that affect non-Windows releases.
4673 4673
4674 8.4.1: April 27, 2019 4674 8.4.1: April 27, 2019
4675 - - Enhancements  
4676 -  
4677 - - When @1@command@1@qpdf --version@2@command@2@ is run, it will  
4678 - detect if the qpdf CLI was built with a different version of  
4679 - qpdf than the library, which may indicate a problem with the  
4680 - installation.  
4681 -  
4682 - - New option @1@option@1@--remove-page-labels@2@option@2@ will  
4683 - remove page labels before generating output. This used to  
4684 - happen if you ran @1@command@1@qpdf --empty --pages ..  
4685 - --@2@command@2@, but the behavior changed in qpdf 8.3.0. This  
4686 - option enables people who were relying on the old behavior to  
4687 - get it again.  
4688 -  
4689 - - New option  
4690 - @1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@  
4691 - can be used to override number of files that qpdf will use to  
4692 - trigger the behavior of not keeping all files open when merging  
4693 - files. This may be necessary if your system allows fewer than  
4694 - the default value of 200 files to be open at the same time.  
4695 -  
4696 - - Bug Fixes  
4697 -  
4698 - - Handle Unicode characters in filenames on Windows. The changes  
4699 - to support Unicode on the CLI in Windows broke Unicode  
4700 - filenames for Windows.  
4701 -  
4702 - - Slightly tighten logic that determines whether an object is a  
4703 - page. This should resolve problems in some rare files where  
4704 - some non-page objects were passing qpdf's test for whether  
4705 - something was a page, thus causing them to be erroneously lost  
4706 - during page splitting operations.  
4707 -  
4708 - - Revert change that included preservation of outlines  
4709 - (bookmarks) in @1@option@1@--split-pages@2@option@2@. The way  
4710 - it was implemented in 8.3.0 and 8.4.0 caused a very significant  
4711 - degradation of performance for splitting certain files. A  
4712 - future release of qpdf may re-introduce the behavior in a more  
4713 - performant and also more correct fashion.  
4714 -  
4715 - - In JSON mode, add missing leading 0 to decimal values between  
4716 - -1 and 1 even if not present in the input. The JSON  
4717 - specification requires the leading 0. The PDF specification  
4718 - does not. 4675 + - Enhancements
  4676 +
  4677 + - When @1@command@1@qpdf --version@2@command@2@ is run, it will
  4678 + detect if the qpdf CLI was built with a different version of
  4679 + qpdf than the library, which may indicate a problem with the
  4680 + installation.
  4681 +
  4682 + - New option @1@option@1@--remove-page-labels@2@option@2@ will
  4683 + remove page labels before generating output. This used to
  4684 + happen if you ran @1@command@1@qpdf --empty --pages ..
  4685 + --@2@command@2@, but the behavior changed in qpdf 8.3.0. This
  4686 + option enables people who were relying on the old behavior to
  4687 + get it again.
  4688 +
  4689 + - New option
  4690 + @1@option@1@--keep-files-open-threshold=@1@replaceable@1@count@2@replaceable@2@@2@option@2@
  4691 + can be used to override number of files that qpdf will use to
  4692 + trigger the behavior of not keeping all files open when merging
  4693 + files. This may be necessary if your system allows fewer than
  4694 + the default value of 200 files to be open at the same time.
  4695 +
  4696 + - Bug Fixes
  4697 +
  4698 + - Handle Unicode characters in filenames on Windows. The changes
  4699 + to support Unicode on the CLI in Windows broke Unicode
  4700 + filenames for Windows.
  4701 +
  4702 + - Slightly tighten logic that determines whether an object is a
  4703 + page. This should resolve problems in some rare files where
  4704 + some non-page objects were passing qpdf's test for whether
  4705 + something was a page, thus causing them to be erroneously lost
  4706 + during page splitting operations.
  4707 +
  4708 + - Revert change that included preservation of outlines
  4709 + (bookmarks) in @1@option@1@--split-pages@2@option@2@. The way
  4710 + it was implemented in 8.3.0 and 8.4.0 caused a very significant
  4711 + degradation of performance for splitting certain files. A
  4712 + future release of qpdf may re-introduce the behavior in a more
  4713 + performant and also more correct fashion.
  4714 +
  4715 + - In JSON mode, add missing leading 0 to decimal values between
  4716 + -1 and 1 even if not present in the input. The JSON
  4717 + specification requires the leading 0. The PDF specification
  4718 + does not.
4719 4719
4720 8.4.0: February 1, 2019 4720 8.4.0: February 1, 2019
4721 - - Command-line Enhancements  
4722 -  
4723 - - *Non-compatible CLI change:* The qpdf command-line tool  
4724 - interprets passwords given at the command-line differently from  
4725 - previous releases when the passwords contain non-ASCII  
4726 - characters. In some cases, the behavior differs from previous  
4727 - releases. For a discussion of the current behavior, please see  
4728 - `Unicode Passwords <#ref.unicode-passwords>`__. The  
4729 - incompatibilities are as follows:  
4730 -  
4731 - - On Windows, qpdf now receives all command-line options as  
4732 - Unicode strings if it can figure out the appropriate  
4733 - compile/link options. This is enabled at least for MSVC and  
4734 - mingw builds. That means that if non-ASCII strings are  
4735 - passed to the qpdf CLI in Windows, qpdf will now correctly  
4736 - receive them. In the past, they would have either been  
4737 - encoded as Windows code page 1252 (also known as "Windows  
4738 - ANSI" or as something unintelligible. In almost all cases,  
4739 - qpdf is able to properly interpret Unicode arguments now,  
4740 - whereas in the past, it would almost never interpret them  
4741 - properly. The result is that non-ASCII passwords given to  
4742 - the qpdf CLI on Windows now have a much greater chance of  
4743 - creating PDF files that can be opened by a variety of  
4744 - readers. In the past, usually files encrypted from the  
4745 - Windows CLI using non-ASCII passwords would not be readable  
4746 - by most viewers. Note that the current version of qpdf is  
4747 - able to decrypt files that it previously created using the  
4748 - previously supplied password.  
4749 -  
4750 - - The PDF specification requires passwords to be encoded as  
4751 - UTF-8 for 256-bit encryption and with PDF Doc encoding for  
4752 - 40-bit or 128-bit encryption. Older versions of qpdf left it  
4753 - up to the user to provide passwords with the correct  
4754 - encoding. The qpdf CLI now detects when a password is given  
4755 - with UTF-8 encoding and automatically transcodes it to what  
4756 - the PDF spec requires. While this is almost always the  
4757 - correct behavior, it is possible to override the behavior if  
4758 - there is some reason to do so. This is discussed in more  
4759 - depth in `Unicode Passwords <#ref.unicode-passwords>`__.  
4760 -  
4761 - - New options  
4762 - @1@option@1@--externalize-inline-images@2@option@2@,  
4763 - @1@option@1@--ii-min-bytes@2@option@2@, and  
4764 - @1@option@1@--keep-inline-images@2@option@2@ control qpdf's  
4765 - handling of inline images and possible conversion of them to  
4766 - regular images. By default,  
4767 - @1@option@1@--optimize-images@2@option@2@ now also applies to  
4768 - inline images. These options are discussed in `Advanced  
4769 - Transformation Options <#ref.advanced-transformation>`__.  
4770 -  
4771 - - Add options @1@option@1@--overlay@2@option@2@ and  
4772 - @1@option@1@--underlay@2@option@2@ for overlaying or  
4773 - underlaying pages of other files onto output pages. See  
4774 - `Overlay and Underlay Options <#ref.overlay-underlay>`__ for  
4775 - details.  
4776 -  
4777 - - When opening an encrypted file with a password, if the  
4778 - specified password doesn't work and the password contains any  
4779 - non-ASCII characters, qpdf will try a number of alternative  
4780 - passwords to try to compensate for possible character encoding  
4781 - errors. This behavior can be suppressed with the  
4782 - @1@option@1@--suppress-password-recovery@2@option@2@ option.  
4783 - See `Unicode Passwords <#ref.unicode-passwords>`__ for a full  
4784 - discussion.  
4785 -  
4786 - - Add the @1@option@1@--password-mode@2@option@2@ option to  
4787 - fine-tune how qpdf interprets password arguments, especially  
4788 - when they contain non-ASCII characters. See `Unicode  
4789 - Passwords <#ref.unicode-passwords>`__ for more information.  
4790 -  
4791 - - In the @1@option@1@--pages@2@option@2@ option, it is now  
4792 - possible to copy the same page more than once from the same  
4793 - file without using the previous workaround of specifying two  
4794 - different paths to the same file.  
4795 -  
4796 - - In the @1@option@1@--pages@2@option@2@ option, allow use of "."  
4797 - as a shortcut for the primary input file. That way, you can do  
4798 - @1@command@1@qpdf in.pdf --pages . 1-2 -- out.pdf@2@command@2@  
4799 - instead of having to repeat @1@filename@1@in.pdf@2@filename@2@  
4800 - in the command.  
4801 -  
4802 - - When encrypting with 128-bit and 256-bit encryption, new  
4803 - encryption options @1@option@1@--assemble@2@option@2@,  
4804 - @1@option@1@--annotate@2@option@2@,  
4805 - @1@option@1@--form@2@option@2@, and  
4806 - @1@option@1@--modify-other@2@option@2@ allow more fine-grained  
4807 - granularity in configuring options. Before, the  
4808 - @1@option@1@--modify@2@option@2@ option only configured certain  
4809 - predefined groups of permissions.  
4810 -  
4811 - - Bug Fixes and Enhancements  
4812 -  
4813 - - *Potential data-loss bug:* Versions of qpdf between 8.1.0 and  
4814 - 8.3.0 had a bug that could cause page splitting and merging  
4815 - operations to drop some font or image resources if the PDF  
4816 - file's internal structure shared these resource lists across  
4817 - pages and if some but not all of the pages in the output did  
4818 - not reference all the fonts and images. Using the  
4819 - @1@option@1@--preserve-unreferenced-resources@2@option@2@  
4820 - option would work around the incorrect behavior. This bug was  
4821 - the result of a typo in the code and a deficiency in the test  
4822 - suite. The case that triggered the error was known, just not  
4823 - handled properly. This case is now exercised in qpdf's test  
4824 - suite and properly handled.  
4825 -  
4826 - - When optimizing images, detect and refuse to optimize images  
4827 - that can't be converted to JPEG because of bit depth or color  
4828 - space.  
4829 -  
4830 - - Linearization and page manipulation APIs now detect and recover  
4831 - from files that have duplicate Page objects in the pages tree.  
4832 -  
4833 - - Using older option  
4834 - @1@option@1@--stream-data=compress@2@option@2@ with object  
4835 - streams, object streams and xref streams were not compressed.  
4836 -  
4837 - - When the tokenizer returns inline image tokens, delimiters  
4838 - following ``ID`` and ``EI`` operators are no longer excluded.  
4839 - This makes it possible to reliably extract the actual image  
4840 - data.  
4841 -  
4842 - - Library Enhancements  
4843 -  
4844 - - Add method ``QPDFPageObjectHelper::externalizeInlineImages`` to  
4845 - convert inline images to regular images.  
4846 -  
4847 - - Add method ``QUtil::possible_repaired_encodings()`` to generate  
4848 - a list of strings that represent other ways the given string  
4849 - could have been encoded. This is the method the QPDF CLI uses  
4850 - to generate the strings it tries when recovering incorrectly  
4851 - encoded Unicode passwords.  
4852 -  
4853 - - Add new versions of  
4854 - ``QPDFWriter::setR{3,4,5,6}EncryptionParameters`` that allow  
4855 - more granular setting of permissions bits. See  
4856 - @1@filename@1@QPDFWriter.hh@2@filename@2@ for details.  
4857 -  
4858 - - Add new versions of the transcoders from UTF-8 to single-byte  
4859 - coding systems in ``QUtil`` that report success or failure  
4860 - rather than just substituting a specified unknown character.  
4861 -  
4862 - - Add method ``QUtil::analyze_encoding()`` to determine whether a  
4863 - string has high-bit characters and is appears to be UTF-16 or  
4864 - valid UTF-8 encoding.  
4865 -  
4866 - - Add new method ``QPDFPageObjectHelper::shallowCopyPage()`` to  
4867 - copy a new page that is a "shallow copy" of a page. The  
4868 - resulting object is an indirect object ready to be passed to  
4869 - ``QPDFPageDocumentHelper::addPage()`` for either the original  
4870 - ``QPDF`` object or a different one. This is what the  
4871 - @1@command@1@qpdf@2@command@2@ command-line tool uses to copy  
4872 - the same page multiple times from the same file during  
4873 - splitting and merging operations.  
4874 -  
4875 - - Add method ``QPDF::getUniqueId()``, which returns a unique  
4876 - identifier for the given QPDF object. The identifier will be  
4877 - unique across the life of the application. The returned value  
4878 - can be safely used as a map key.  
4879 -  
4880 - - Add method ``QPDF::setImmediateCopyFrom``. This further  
4881 - enhances qpdf's ability to allow a ``QPDF`` object from which  
4882 - objects are being copied to go out of scope before the  
4883 - destination object is written. If you call this method on a  
4884 - ``QPDF`` instances, objects copied *from* this instance will be  
4885 - copied immediately instead of lazily. This option uses more  
4886 - memory but allows the source object to go out of scope before  
4887 - the destination object is written in all cases. See comments in  
4888 - @1@filename@1@QPDF.hh@2@filename@2@ for details.  
4889 -  
4890 - - Add method ``QPDFPageObjectHelper::getAttribute`` for  
4891 - retrieving an attribute from the page dictionary taking  
4892 - inheritance into consideration, and optionally making a copy if  
4893 - your intention is to modify the attribute.  
4894 -  
4895 - - Fix long-standing limitation of  
4896 - ``QPDFPageObjectHelper::getPageImages`` so that it now properly  
4897 - reports images from inherited resources dictionaries,  
4898 - eliminating the need to call  
4899 - ``QPDFPageDocumentHelper::pushInheritedAttributesToPage`` in  
4900 - this case.  
4901 -  
4902 - - Add method ``QPDFObjectHandle::getUniqueResourceName`` for  
4903 - finding an unused name in a resource dictionary.  
4904 -  
4905 - - Add method ``QPDFPageObjectHelper::getFormXObjectForPage`` for  
4906 - generating a form XObject equivalent to a page. The resulting  
4907 - object can be used in the same file or copied to another file  
4908 - with ``copyForeignObject``. This can be useful for implementing  
4909 - underlay, overlay, n-up, thumbnails, or any other functionality  
4910 - requiring replication of pages in other contexts.  
4911 -  
4912 - - Add method ``QPDFPageObjectHelper::placeFormXObject`` for  
4913 - generating content stream text that places a given form XObject  
4914 - on a page, centered and fit within a specified rectangle. This  
4915 - method takes care of computing the proper transformation matrix  
4916 - and may optionally compensate for rotation or scaling of the  
4917 - destination page.  
4918 -  
4919 - - Build Improvements  
4920 -  
4921 - - Add new configure option  
4922 - @1@option@1@--enable-avoid-windows-handle@2@option@2@, which  
4923 - causes the preprocessor symbol ``AVOID_WINDOWS_HANDLE`` to be  
4924 - defined. When defined, qpdf will avoid referencing the Windows  
4925 - ``HANDLE`` type, which is disallowed with certain versions of  
4926 - the Windows SDK.  
4927 -  
4928 - - For Windows builds, attempt to determine what options, if any,  
4929 - have to be passed to the compiler and linker to enable use of  
4930 - ``wmain``. This causes the preprocessor symbol  
4931 - ``WINDOWS_WMAIN`` to be defined. If you do your own builds with  
4932 - other compilers, you can define this symbol to cause ``wmain``  
4933 - to be used. This is needed to allow the Windows  
4934 - @1@command@1@qpdf@2@command@2@ command to receive Unicode  
4935 - command-line options. 4721 + - Command-line Enhancements
  4722 +
  4723 + - *Non-compatible CLI change:* The qpdf command-line tool
  4724 + interprets passwords given at the command-line differently from
  4725 + previous releases when the passwords contain non-ASCII
  4726 + characters. In some cases, the behavior differs from previous
  4727 + releases. For a discussion of the current behavior, please see
  4728 + `Unicode Passwords <#ref.unicode-passwords>`__. The
  4729 + incompatibilities are as follows:
  4730 +
  4731 + - On Windows, qpdf now receives all command-line options as
  4732 + Unicode strings if it can figure out the appropriate
  4733 + compile/link options. This is enabled at least for MSVC and
  4734 + mingw builds. That means that if non-ASCII strings are
  4735 + passed to the qpdf CLI in Windows, qpdf will now correctly
  4736 + receive them. In the past, they would have either been
  4737 + encoded as Windows code page 1252 (also known as "Windows
  4738 + ANSI" or as something unintelligible. In almost all cases,
  4739 + qpdf is able to properly interpret Unicode arguments now,
  4740 + whereas in the past, it would almost never interpret them
  4741 + properly. The result is that non-ASCII passwords given to
  4742 + the qpdf CLI on Windows now have a much greater chance of
  4743 + creating PDF files that can be opened by a variety of
  4744 + readers. In the past, usually files encrypted from the
  4745 + Windows CLI using non-ASCII passwords would not be readable
  4746 + by most viewers. Note that the current version of qpdf is
  4747 + able to decrypt files that it previously created using the
  4748 + previously supplied password.
  4749 +
  4750 + - The PDF specification requires passwords to be encoded as
  4751 + UTF-8 for 256-bit encryption and with PDF Doc encoding for
  4752 + 40-bit or 128-bit encryption. Older versions of qpdf left it
  4753 + up to the user to provide passwords with the correct
  4754 + encoding. The qpdf CLI now detects when a password is given
  4755 + with UTF-8 encoding and automatically transcodes it to what
  4756 + the PDF spec requires. While this is almost always the
  4757 + correct behavior, it is possible to override the behavior if
  4758 + there is some reason to do so. This is discussed in more
  4759 + depth in `Unicode Passwords <#ref.unicode-passwords>`__.
  4760 +
  4761 + - New options
  4762 + @1@option@1@--externalize-inline-images@2@option@2@,
  4763 + @1@option@1@--ii-min-bytes@2@option@2@, and
  4764 + @1@option@1@--keep-inline-images@2@option@2@ control qpdf's
  4765 + handling of inline images and possible conversion of them to
  4766 + regular images. By default,
  4767 + @1@option@1@--optimize-images@2@option@2@ now also applies to
  4768 + inline images. These options are discussed in `Advanced
  4769 + Transformation Options <#ref.advanced-transformation>`__.
  4770 +
  4771 + - Add options @1@option@1@--overlay@2@option@2@ and
  4772 + @1@option@1@--underlay@2@option@2@ for overlaying or
  4773 + underlaying pages of other files onto output pages. See
  4774 + `Overlay and Underlay Options <#ref.overlay-underlay>`__ for
  4775 + details.
  4776 +
  4777 + - When opening an encrypted file with a password, if the
  4778 + specified password doesn't work and the password contains any
  4779 + non-ASCII characters, qpdf will try a number of alternative
  4780 + passwords to try to compensate for possible character encoding
  4781 + errors. This behavior can be suppressed with the
  4782 + @1@option@1@--suppress-password-recovery@2@option@2@ option.
  4783 + See `Unicode Passwords <#ref.unicode-passwords>`__ for a full
  4784 + discussion.
  4785 +
  4786 + - Add the @1@option@1@--password-mode@2@option@2@ option to
  4787 + fine-tune how qpdf interprets password arguments, especially
  4788 + when they contain non-ASCII characters. See `Unicode
  4789 + Passwords <#ref.unicode-passwords>`__ for more information.
  4790 +
  4791 + - In the @1@option@1@--pages@2@option@2@ option, it is now
  4792 + possible to copy the same page more than once from the same
  4793 + file without using the previous workaround of specifying two
  4794 + different paths to the same file.
  4795 +
  4796 + - In the @1@option@1@--pages@2@option@2@ option, allow use of "."
  4797 + as a shortcut for the primary input file. That way, you can do
  4798 + @1@command@1@qpdf in.pdf --pages . 1-2 -- out.pdf@2@command@2@
  4799 + instead of having to repeat @1@filename@1@in.pdf@2@filename@2@
  4800 + in the command.
  4801 +
  4802 + - When encrypting with 128-bit and 256-bit encryption, new
  4803 + encryption options @1@option@1@--assemble@2@option@2@,
  4804 + @1@option@1@--annotate@2@option@2@,
  4805 + @1@option@1@--form@2@option@2@, and
  4806 + @1@option@1@--modify-other@2@option@2@ allow more fine-grained
  4807 + granularity in configuring options. Before, the
  4808 + @1@option@1@--modify@2@option@2@ option only configured certain
  4809 + predefined groups of permissions.
  4810 +
  4811 + - Bug Fixes and Enhancements
  4812 +
  4813 + - *Potential data-loss bug:* Versions of qpdf between 8.1.0 and
  4814 + 8.3.0 had a bug that could cause page splitting and merging
  4815 + operations to drop some font or image resources if the PDF
  4816 + file's internal structure shared these resource lists across
  4817 + pages and if some but not all of the pages in the output did
  4818 + not reference all the fonts and images. Using the
  4819 + @1@option@1@--preserve-unreferenced-resources@2@option@2@
  4820 + option would work around the incorrect behavior. This bug was
  4821 + the result of a typo in the code and a deficiency in the test
  4822 + suite. The case that triggered the error was known, just not
  4823 + handled properly. This case is now exercised in qpdf's test
  4824 + suite and properly handled.
  4825 +
  4826 + - When optimizing images, detect and refuse to optimize images
  4827 + that can't be converted to JPEG because of bit depth or color
  4828 + space.
  4829 +
  4830 + - Linearization and page manipulation APIs now detect and recover
  4831 + from files that have duplicate Page objects in the pages tree.
  4832 +
  4833 + - Using older option
  4834 + @1@option@1@--stream-data=compress@2@option@2@ with object
  4835 + streams, object streams and xref streams were not compressed.
  4836 +
  4837 + - When the tokenizer returns inline image tokens, delimiters
  4838 + following ``ID`` and ``EI`` operators are no longer excluded.
  4839 + This makes it possible to reliably extract the actual image
  4840 + data.
  4841 +
  4842 + - Library Enhancements
  4843 +
  4844 + - Add method ``QPDFPageObjectHelper::externalizeInlineImages`` to
  4845 + convert inline images to regular images.
  4846 +
  4847 + - Add method ``QUtil::possible_repaired_encodings()`` to generate
  4848 + a list of strings that represent other ways the given string
  4849 + could have been encoded. This is the method the QPDF CLI uses
  4850 + to generate the strings it tries when recovering incorrectly
  4851 + encoded Unicode passwords.
  4852 +
  4853 + - Add new versions of
  4854 + ``QPDFWriter::setR{3,4,5,6}EncryptionParameters`` that allow
  4855 + more granular setting of permissions bits. See
  4856 + @1@filename@1@QPDFWriter.hh@2@filename@2@ for details.
  4857 +
  4858 + - Add new versions of the transcoders from UTF-8 to single-byte
  4859 + coding systems in ``QUtil`` that report success or failure
  4860 + rather than just substituting a specified unknown character.
  4861 +
  4862 + - Add method ``QUtil::analyze_encoding()`` to determine whether a
  4863 + string has high-bit characters and is appears to be UTF-16 or
  4864 + valid UTF-8 encoding.
  4865 +
  4866 + - Add new method ``QPDFPageObjectHelper::shallowCopyPage()`` to
  4867 + copy a new page that is a "shallow copy" of a page. The
  4868 + resulting object is an indirect object ready to be passed to
  4869 + ``QPDFPageDocumentHelper::addPage()`` for either the original
  4870 + ``QPDF`` object or a different one. This is what the
  4871 + @1@command@1@qpdf@2@command@2@ command-line tool uses to copy
  4872 + the same page multiple times from the same file during
  4873 + splitting and merging operations.
  4874 +
  4875 + - Add method ``QPDF::getUniqueId()``, which returns a unique
  4876 + identifier for the given QPDF object. The identifier will be
  4877 + unique across the life of the application. The returned value
  4878 + can be safely used as a map key.
  4879 +
  4880 + - Add method ``QPDF::setImmediateCopyFrom``. This further
  4881 + enhances qpdf's ability to allow a ``QPDF`` object from which
  4882 + objects are being copied to go out of scope before the
  4883 + destination object is written. If you call this method on a
  4884 + ``QPDF`` instances, objects copied *from* this instance will be
  4885 + copied immediately instead of lazily. This option uses more
  4886 + memory but allows the source object to go out of scope before
  4887 + the destination object is written in all cases. See comments in
  4888 + @1@filename@1@QPDF.hh@2@filename@2@ for details.
  4889 +
  4890 + - Add method ``QPDFPageObjectHelper::getAttribute`` for
  4891 + retrieving an attribute from the page dictionary taking
  4892 + inheritance into consideration, and optionally making a copy if
  4893 + your intention is to modify the attribute.
  4894 +
  4895 + - Fix long-standing limitation of
  4896 + ``QPDFPageObjectHelper::getPageImages`` so that it now properly
  4897 + reports images from inherited resources dictionaries,
  4898 + eliminating the need to call
  4899 + ``QPDFPageDocumentHelper::pushInheritedAttributesToPage`` in
  4900 + this case.
  4901 +
  4902 + - Add method ``QPDFObjectHandle::getUniqueResourceName`` for
  4903 + finding an unused name in a resource dictionary.
  4904 +
  4905 + - Add method ``QPDFPageObjectHelper::getFormXObjectForPage`` for
  4906 + generating a form XObject equivalent to a page. The resulting
  4907 + object can be used in the same file or copied to another file
  4908 + with ``copyForeignObject``. This can be useful for implementing
  4909 + underlay, overlay, n-up, thumbnails, or any other functionality
  4910 + requiring replication of pages in other contexts.
  4911 +
  4912 + - Add method ``QPDFPageObjectHelper::placeFormXObject`` for
  4913 + generating content stream text that places a given form XObject
  4914 + on a page, centered and fit within a specified rectangle. This
  4915 + method takes care of computing the proper transformation matrix
  4916 + and may optionally compensate for rotation or scaling of the
  4917 + destination page.
  4918 +
  4919 + - Build Improvements
  4920 +
  4921 + - Add new configure option
  4922 + @1@option@1@--enable-avoid-windows-handle@2@option@2@, which
  4923 + causes the preprocessor symbol ``AVOID_WINDOWS_HANDLE`` to be
  4924 + defined. When defined, qpdf will avoid referencing the Windows
  4925 + ``HANDLE`` type, which is disallowed with certain versions of
  4926 + the Windows SDK.
  4927 +
  4928 + - For Windows builds, attempt to determine what options, if any,
  4929 + have to be passed to the compiler and linker to enable use of
  4930 + ``wmain``. This causes the preprocessor symbol
  4931 + ``WINDOWS_WMAIN`` to be defined. If you do your own builds with
  4932 + other compilers, you can define this symbol to cause ``wmain``
  4933 + to be used. This is needed to allow the Windows
  4934 + @1@command@1@qpdf@2@command@2@ command to receive Unicode
  4935 + command-line options.
4936 4936
4937 8.3.0: January 7, 2019 4937 8.3.0: January 7, 2019
4938 - - Command-line Enhancements  
4939 -  
4940 - - Shell completion: you can now use eval @1@command@1@$(qpdf  
4941 - --completion-bash)@2@command@2@ and eval @1@command@1@$(qpdf  
4942 - --completion-zsh)@2@command@2@ to enable shell completion for  
4943 - bash and zsh.  
4944 -  
4945 - - Page numbers (also known as page labels) are now preserved when  
4946 - merging and splitting files with the  
4947 - @1@option@1@--pages@2@option@2@ and  
4948 - @1@option@1@--split-pages@2@option@2@ options.  
4949 -  
4950 - - Bookmarks are partially preserved when splitting pages with the  
4951 - @1@option@1@--split-pages@2@option@2@ option. Specifically, the  
4952 - outlines dictionary and some supporting metadata are copied  
4953 - into the split files. The result is that all bookmarks from the  
4954 - original file appear, those that point to pages that are  
4955 - preserved work, and those that point to pages that are not  
4956 - preserved don't do anything. This is an interim step toward  
4957 - proper support for bookmarks in splitting and merging  
4958 - operations.  
4959 -  
4960 - - Page collation: add new option  
4961 - @1@option@1@--collate@2@option@2@. When specified, the  
4962 - semantics of @1@option@1@--pages@2@option@2@ change from  
4963 - concatenation to collation. See `Page Selection  
4964 - Options <#ref.page-selection>`__ for examples and discussion.  
4965 -  
4966 - - Generation of information in JSON format, primarily to  
4967 - facilitate use of qpdf from languages other than C++. Add new  
4968 - options @1@option@1@--json@2@option@2@,  
4969 - @1@option@1@--json-key@2@option@2@, and  
4970 - @1@option@1@--json-object@2@option@2@ to generate a JSON  
4971 - representation of the PDF file. Run @1@command@1@qpdf  
4972 - --json-help@2@command@2@ to get a description of the JSON  
4973 - format. For more information, see `QPDF JSON <#ref.json>`__.  
4974 -  
4975 - - The @1@option@1@--generate-appearances@2@option@2@ flag will  
4976 - cause qpdf to generate appearances for form fields if the PDF  
4977 - file indicates that form field appearances are out of date.  
4978 - This can happen when PDF forms are filled in by a program that  
4979 - doesn't know how to regenerate the appearances of the filled-in  
4980 - fields.  
4981 -  
4982 - - The @1@option@1@--flatten-annotations@2@option@2@ flag can be  
4983 - used to *flatten* annotations, including form fields.  
4984 - Ordinarily, annotations are drawn separately from the page.  
4985 - Flattening annotations is the process of combining their  
4986 - appearances into the page's contents. You might want to do this  
4987 - if you are going to rotate or combine pages using a tool that  
4988 - doesn't understand about annotations. You may also want to use  
4989 - @1@option@1@--generate-appearances@2@option@2@ when using this  
4990 - flag since annotations for outdated form fields are not  
4991 - flattened as that would cause loss of information.  
4992 -  
4993 - - The @1@option@1@--optimize-images@2@option@2@ flag tells qpdf  
4994 - to recompresses every image using DCT (JPEG) compression as  
4995 - long as the image is not already compressed with lossy  
4996 - compression and recompressing the image reduces its size. The  
4997 - additional options @1@option@1@--oi-min-width@2@option@2@,  
4998 - @1@option@1@--oi-min-height@2@option@2@, and  
4999 - @1@option@1@--oi-min-area@2@option@2@ prevent recompression of  
5000 - images whose width, height, or pixel area (widthย ร—ย height) are  
5001 - below a specified threshold.  
5002 -  
5003 - - The @1@option@1@--show-object@2@option@2@ option can now be  
5004 - given as @1@option@1@--show-object=trailer@2@option@2@ to show  
5005 - the trailer dictionary.  
5006 -  
5007 - - Bug Fixes and Enhancements  
5008 -  
5009 - - QPDF now automatically detects and recovers from dangling  
5010 - references. If a PDF file contained an indirect reference to a  
5011 - non-existent object, which is valid, when adding a new object  
5012 - to the file, it was possible for the new object to take the  
5013 - object ID of the dangling reference, thereby causing the  
5014 - dangling reference to point to the new object. This case is now  
5015 - prevented.  
5016 -  
5017 - - Fixes to form field setting code: strings are always written in  
5018 - UTF-16 format, and checkboxes and radio buttons are handled  
5019 - properly with respect to synchronization of values and  
5020 - appearance states.  
5021 -  
5022 - - The ``QPDF::checkLinearization()`` no longer causes the program  
5023 - to crash when it detects problems with linearization data.  
5024 - Instead, it issues a normal warning or error.  
5025 -  
5026 - - Ordinarily qpdf treats an argument of the form  
5027 - @1@option@1@@file@2@option@2@ to mean that command-line options  
5028 - should be read from @1@filename@1@file@2@filename@2@. Now, if  
5029 - @1@filename@1@file@2@filename@2@ does not exist but  
5030 - @1@filename@1@@file@2@filename@2@ does, qpdf will treat  
5031 - @1@filename@1@@file@2@filename@2@ as a regular option. This  
5032 - makes it possible to work more easily with PDF files whose  
5033 - names happen to start with the ``@`` character.  
5034 -  
5035 - - Library Enhancements  
5036 -  
5037 - - Remove the restriction in most cases that the source QPDF  
5038 - object used in a ``QPDF::copyForeignObject`` call has to stick  
5039 - around until the destination QPDF is written. The exceptional  
5040 - case is when the source stream gets is data using a  
5041 - QPDFObjectHandle::StreamDataProvider. For a more in-depth  
5042 - discussion, see comments around ``copyForeignObject`` in  
5043 - @1@filename@1@QPDF.hh@2@filename@2@.  
5044 -  
5045 - - Add new method ``QPDFWriter::getFinalVersion()``, which returns  
5046 - the PDF version that will ultimately be written to the final  
5047 - file. See comments in @1@filename@1@QPDFWriter.hh@2@filename@2@  
5048 - for some restrictions on its use.  
5049 -  
5050 - - Add several methods for transcoding strings to some of the  
5051 - character sets used in PDF files: ``QUtil::utf8_to_ascii``,  
5052 - ``QUtil::utf8_to_win_ansi``, ``QUtil::utf8_to_mac_roman``, and  
5053 - ``QUtil::utf8_to_utf16``. For the single-byte encodings that  
5054 - support only a limited character sets, these methods replace  
5055 - unsupported characters with a specified substitute.  
5056 -  
5057 - - Add new methods to ``QPDFAnnotationObjectHelper`` and  
5058 - ``QPDFFormFieldObjectHelper`` for querying flags and  
5059 - interpretation of different field types. Define constants in  
5060 - @1@filename@1@qpdf/Constants.h@2@filename@2@ to help with  
5061 - interpretation of flag values.  
5062 -  
5063 - - Add new methods  
5064 - ``QPDFAcroFormDocumentHelper::generateAppearancesIfNeeded`` and  
5065 - ``QPDFFormFieldObjectHelper::generateAppearance`` for  
5066 - generating appearance streams. See discussion in  
5067 - @1@filename@1@QPDFFormFieldObjectHelper.hh@2@filename@2@ for  
5068 - limitations.  
5069 -  
5070 - - Add two new helper functions for dealing with resource  
5071 - dictionaries: ``QPDFObjectHandle::getResourceNames()`` returns  
5072 - a list of all second-level keys, which correspond to the names  
5073 - of resources, and ``QPDFObjectHandle::mergeResources()`` merges  
5074 - two resources dictionaries as long as they have non-conflicting  
5075 - keys. These methods are useful for certain types of objects  
5076 - that resolve resources from multiple places, such as form  
5077 - fields.  
5078 -  
5079 - - Add methods ``QPDFPageDocumentHelper::flattenAnnotations()``  
5080 - and  
5081 - ``QPDFAnnotationObjectHelper::getPageContentForAppearance()``  
5082 - for handling low-level details of annotation flattening.  
5083 -  
5084 - - Add new helper classes: ``QPDFOutlineDocumentHelper``,  
5085 - ``QPDFOutlineObjectHelper``, ``QPDFPageLabelDocumentHelper``,  
5086 - ``QPDFNameTreeObjectHelper``, and  
5087 - ``QPDFNumberTreeObjectHelper``.  
5088 -  
5089 - - Add method ``QPDFObjectHandle::getJSON()`` that returns a JSON  
5090 - representation of the object. Call ``serialize()`` on the  
5091 - result to convert it to a string.  
5092 -  
5093 - - Add a simple JSON serializer. This is not a complete or  
5094 - general-purpose JSON library. It allows assembly and  
5095 - serialization of JSON structures with some restrictions, which  
5096 - are described in the header file. This is the serializer used  
5097 - by qpdf's new JSON representation.  
5098 -  
5099 - - Add new ``QPDFObjectHandle::Matrix`` class along with a few  
5100 - convenience methods for dealing with six-element numerical  
5101 - arrays as matrices.  
5102 -  
5103 - - Add new method ``QPDFObjectHandle::wrapInArray``, which returns  
5104 - the object itself if it is an array, or an array containing the  
5105 - object otherwise. This is a common construct in PDF. This  
5106 - method prevents you from having to explicitly test whether  
5107 - something is a single element or an array.  
5108 -  
5109 - - Build Improvements  
5110 -  
5111 - - It is no longer necessary to run  
5112 - @1@command@1@autogen.sh@2@command@2@ to build from a pristine  
5113 - checkout. Automatically generated files are now committed so  
5114 - that it is possible to build on platforms without autoconf  
5115 - directly from a clean checkout of the repository. The  
5116 - @1@command@1@configure@2@command@2@ script detects if the files  
5117 - are out of date when it also determines that the tools are  
5118 - present to regenerate them.  
5119 -  
5120 - - Pull requests and the master branch are now built automatically  
5121 - in `Azure  
5122 - Pipelines <https://dev.azure.com/qpdf/qpdf/_build>`__, which is  
5123 - free for open source projects. The build includes Linux, mac,  
5124 - Windows 32-bit and 64-bit with mingw and MSVC, and an AppImage  
5125 - build. Official qpdf releases are now built with Azure  
5126 - Pipelines.  
5127 -  
5128 - - Notes for Packagers  
5129 -  
5130 - - A new section has been added to the documentation with notes  
5131 - for packagers. Please see `Notes for  
5132 - Packagers <#ref.packaging>`__.  
5133 -  
5134 - - The qpdf detects out-of-date automatically generated files. If  
5135 - your packaging system automatically refreshes libtool or  
5136 - autoconf files, it could cause this check to fail. To avoid  
5137 - this problem, pass  
5138 - @1@option@1@--disable-check-autofiles@2@option@2@ to  
5139 - @1@command@1@configure@2@command@2@.  
5140 -  
5141 - - If you would like to have qpdf completion enabled  
5142 - automatically, you can install completion files in the  
5143 - distribution's default location. You can find sample completion  
5144 - files to install in the @1@filename@1@completions@2@filename@2@  
5145 - directory. 4938 + - Command-line Enhancements
  4939 +
  4940 + - Shell completion: you can now use eval @1@command@1@$(qpdf
  4941 + --completion-bash)@2@command@2@ and eval @1@command@1@$(qpdf
  4942 + --completion-zsh)@2@command@2@ to enable shell completion for
  4943 + bash and zsh.
  4944 +
  4945 + - Page numbers (also known as page labels) are now preserved when
  4946 + merging and splitting files with the
  4947 + @1@option@1@--pages@2@option@2@ and
  4948 + @1@option@1@--split-pages@2@option@2@ options.
  4949 +
  4950 + - Bookmarks are partially preserved when splitting pages with the
  4951 + @1@option@1@--split-pages@2@option@2@ option. Specifically, the
  4952 + outlines dictionary and some supporting metadata are copied
  4953 + into the split files. The result is that all bookmarks from the
  4954 + original file appear, those that point to pages that are
  4955 + preserved work, and those that point to pages that are not
  4956 + preserved don't do anything. This is an interim step toward
  4957 + proper support for bookmarks in splitting and merging
  4958 + operations.
  4959 +
  4960 + - Page collation: add new option
  4961 + @1@option@1@--collate@2@option@2@. When specified, the
  4962 + semantics of @1@option@1@--pages@2@option@2@ change from
  4963 + concatenation to collation. See `Page Selection
  4964 + Options <#ref.page-selection>`__ for examples and discussion.
  4965 +
  4966 + - Generation of information in JSON format, primarily to
  4967 + facilitate use of qpdf from languages other than C++. Add new
  4968 + options @1@option@1@--json@2@option@2@,
  4969 + @1@option@1@--json-key@2@option@2@, and
  4970 + @1@option@1@--json-object@2@option@2@ to generate a JSON
  4971 + representation of the PDF file. Run @1@command@1@qpdf
  4972 + --json-help@2@command@2@ to get a description of the JSON
  4973 + format. For more information, see `QPDF JSON <#ref.json>`__.
  4974 +
  4975 + - The @1@option@1@--generate-appearances@2@option@2@ flag will
  4976 + cause qpdf to generate appearances for form fields if the PDF
  4977 + file indicates that form field appearances are out of date.
  4978 + This can happen when PDF forms are filled in by a program that
  4979 + doesn't know how to regenerate the appearances of the filled-in
  4980 + fields.
  4981 +
  4982 + - The @1@option@1@--flatten-annotations@2@option@2@ flag can be
  4983 + used to *flatten* annotations, including form fields.
  4984 + Ordinarily, annotations are drawn separately from the page.
  4985 + Flattening annotations is the process of combining their
  4986 + appearances into the page's contents. You might want to do this
  4987 + if you are going to rotate or combine pages using a tool that
  4988 + doesn't understand about annotations. You may also want to use
  4989 + @1@option@1@--generate-appearances@2@option@2@ when using this
  4990 + flag since annotations for outdated form fields are not
  4991 + flattened as that would cause loss of information.
  4992 +
  4993 + - The @1@option@1@--optimize-images@2@option@2@ flag tells qpdf
  4994 + to recompresses every image using DCT (JPEG) compression as
  4995 + long as the image is not already compressed with lossy
  4996 + compression and recompressing the image reduces its size. The
  4997 + additional options @1@option@1@--oi-min-width@2@option@2@,
  4998 + @1@option@1@--oi-min-height@2@option@2@, and
  4999 + @1@option@1@--oi-min-area@2@option@2@ prevent recompression of
  5000 + images whose width, height, or pixel area (widthย ร—ย height) are
  5001 + below a specified threshold.
  5002 +
  5003 + - The @1@option@1@--show-object@2@option@2@ option can now be
  5004 + given as @1@option@1@--show-object=trailer@2@option@2@ to show
  5005 + the trailer dictionary.
  5006 +
  5007 + - Bug Fixes and Enhancements
  5008 +
  5009 + - QPDF now automatically detects and recovers from dangling
  5010 + references. If a PDF file contained an indirect reference to a
  5011 + non-existent object, which is valid, when adding a new object
  5012 + to the file, it was possible for the new object to take the
  5013 + object ID of the dangling reference, thereby causing the
  5014 + dangling reference to point to the new object. This case is now
  5015 + prevented.
  5016 +
  5017 + - Fixes to form field setting code: strings are always written in
  5018 + UTF-16 format, and checkboxes and radio buttons are handled
  5019 + properly with respect to synchronization of values and
  5020 + appearance states.
  5021 +
  5022 + - The ``QPDF::checkLinearization()`` no longer causes the program
  5023 + to crash when it detects problems with linearization data.
  5024 + Instead, it issues a normal warning or error.
  5025 +
  5026 + - Ordinarily qpdf treats an argument of the form
  5027 + @1@option@1@@file@2@option@2@ to mean that command-line options
  5028 + should be read from @1@filename@1@file@2@filename@2@. Now, if
  5029 + @1@filename@1@file@2@filename@2@ does not exist but
  5030 + @1@filename@1@@file@2@filename@2@ does, qpdf will treat
  5031 + @1@filename@1@@file@2@filename@2@ as a regular option. This
  5032 + makes it possible to work more easily with PDF files whose
  5033 + names happen to start with the ``@`` character.
  5034 +
  5035 + - Library Enhancements
  5036 +
  5037 + - Remove the restriction in most cases that the source QPDF
  5038 + object used in a ``QPDF::copyForeignObject`` call has to stick
  5039 + around until the destination QPDF is written. The exceptional
  5040 + case is when the source stream gets is data using a
  5041 + QPDFObjectHandle::StreamDataProvider. For a more in-depth
  5042 + discussion, see comments around ``copyForeignObject`` in
  5043 + @1@filename@1@QPDF.hh@2@filename@2@.
  5044 +
  5045 + - Add new method ``QPDFWriter::getFinalVersion()``, which returns
  5046 + the PDF version that will ultimately be written to the final
  5047 + file. See comments in @1@filename@1@QPDFWriter.hh@2@filename@2@
  5048 + for some restrictions on its use.
  5049 +
  5050 + - Add several methods for transcoding strings to some of the
  5051 + character sets used in PDF files: ``QUtil::utf8_to_ascii``,
  5052 + ``QUtil::utf8_to_win_ansi``, ``QUtil::utf8_to_mac_roman``, and
  5053 + ``QUtil::utf8_to_utf16``. For the single-byte encodings that
  5054 + support only a limited character sets, these methods replace
  5055 + unsupported characters with a specified substitute.
  5056 +
  5057 + - Add new methods to ``QPDFAnnotationObjectHelper`` and
  5058 + ``QPDFFormFieldObjectHelper`` for querying flags and
  5059 + interpretation of different field types. Define constants in
  5060 + @1@filename@1@qpdf/Constants.h@2@filename@2@ to help with
  5061 + interpretation of flag values.
  5062 +
  5063 + - Add new methods
  5064 + ``QPDFAcroFormDocumentHelper::generateAppearancesIfNeeded`` and
  5065 + ``QPDFFormFieldObjectHelper::generateAppearance`` for
  5066 + generating appearance streams. See discussion in
  5067 + @1@filename@1@QPDFFormFieldObjectHelper.hh@2@filename@2@ for
  5068 + limitations.
  5069 +
  5070 + - Add two new helper functions for dealing with resource
  5071 + dictionaries: ``QPDFObjectHandle::getResourceNames()`` returns
  5072 + a list of all second-level keys, which correspond to the names
  5073 + of resources, and ``QPDFObjectHandle::mergeResources()`` merges
  5074 + two resources dictionaries as long as they have non-conflicting
  5075 + keys. These methods are useful for certain types of objects
  5076 + that resolve resources from multiple places, such as form
  5077 + fields.
  5078 +
  5079 + - Add methods ``QPDFPageDocumentHelper::flattenAnnotations()``
  5080 + and
  5081 + ``QPDFAnnotationObjectHelper::getPageContentForAppearance()``
  5082 + for handling low-level details of annotation flattening.
  5083 +
  5084 + - Add new helper classes: ``QPDFOutlineDocumentHelper``,
  5085 + ``QPDFOutlineObjectHelper``, ``QPDFPageLabelDocumentHelper``,
  5086 + ``QPDFNameTreeObjectHelper``, and
  5087 + ``QPDFNumberTreeObjectHelper``.
  5088 +
  5089 + - Add method ``QPDFObjectHandle::getJSON()`` that returns a JSON
  5090 + representation of the object. Call ``serialize()`` on the
  5091 + result to convert it to a string.
  5092 +
  5093 + - Add a simple JSON serializer. This is not a complete or
  5094 + general-purpose JSON library. It allows assembly and
  5095 + serialization of JSON structures with some restrictions, which
  5096 + are described in the header file. This is the serializer used
  5097 + by qpdf's new JSON representation.
  5098 +
  5099 + - Add new ``QPDFObjectHandle::Matrix`` class along with a few
  5100 + convenience methods for dealing with six-element numerical
  5101 + arrays as matrices.
  5102 +
  5103 + - Add new method ``QPDFObjectHandle::wrapInArray``, which returns
  5104 + the object itself if it is an array, or an array containing the
  5105 + object otherwise. This is a common construct in PDF. This
  5106 + method prevents you from having to explicitly test whether
  5107 + something is a single element or an array.
  5108 +
  5109 + - Build Improvements
  5110 +
  5111 + - It is no longer necessary to run
  5112 + @1@command@1@autogen.sh@2@command@2@ to build from a pristine
  5113 + checkout. Automatically generated files are now committed so
  5114 + that it is possible to build on platforms without autoconf
  5115 + directly from a clean checkout of the repository. The
  5116 + @1@command@1@configure@2@command@2@ script detects if the files
  5117 + are out of date when it also determines that the tools are
  5118 + present to regenerate them.
  5119 +
  5120 + - Pull requests and the master branch are now built automatically
  5121 + in `Azure
  5122 + Pipelines <https://dev.azure.com/qpdf/qpdf/_build>`__, which is
  5123 + free for open source projects. The build includes Linux, mac,
  5124 + Windows 32-bit and 64-bit with mingw and MSVC, and an AppImage
  5125 + build. Official qpdf releases are now built with Azure
  5126 + Pipelines.
  5127 +
  5128 + - Notes for Packagers
  5129 +
  5130 + - A new section has been added to the documentation with notes
  5131 + for packagers. Please see `Notes for
  5132 + Packagers <#ref.packaging>`__.
  5133 +
  5134 + - The qpdf detects out-of-date automatically generated files. If
  5135 + your packaging system automatically refreshes libtool or
  5136 + autoconf files, it could cause this check to fail. To avoid
  5137 + this problem, pass
  5138 + @1@option@1@--disable-check-autofiles@2@option@2@ to
  5139 + @1@command@1@configure@2@command@2@.
  5140 +
  5141 + - If you would like to have qpdf completion enabled
  5142 + automatically, you can install completion files in the
  5143 + distribution's default location. You can find sample completion
  5144 + files to install in the @1@filename@1@completions@2@filename@2@
  5145 + directory.
5146 5146
5147 8.2.1: August 18, 2018 5147 8.2.1: August 18, 2018
5148 - - Command-line Enhancements 5148 + - Command-line Enhancements
5149 5149
5150 - - Add  
5151 - @1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@  
5152 - to override default determination of whether to keep files open  
5153 - when merging. Please see the discussion of  
5154 - @1@option@1@--keep-files-open@2@option@2@ in `Basic  
5155 - Options <#ref.basic-options>`__ for additional details. 5150 + - Add
  5151 + @1@option@1@--keep-files-open=@1@replaceable@1@[yn]@2@replaceable@2@@2@option@2@
  5152 + to override default determination of whether to keep files open
  5153 + when merging. Please see the discussion of
  5154 + @1@option@1@--keep-files-open@2@option@2@ in `Basic
  5155 + Options <#ref.basic-options>`__ for additional details.
5156 5156
5157 8.2.0: August 16, 2018 5157 8.2.0: August 16, 2018
5158 - - Command-line Enhancements 5158 + - Command-line Enhancements
5159 5159
5160 - - Add @1@option@1@--no-warn@2@option@2@ option to suppress  
5161 - issuing warning messages. If there are any conditions that  
5162 - would have caused warnings to be issued, the exit status is  
5163 - still 3. 5160 + - Add @1@option@1@--no-warn@2@option@2@ option to suppress
  5161 + issuing warning messages. If there are any conditions that
  5162 + would have caused warnings to be issued, the exit status is
  5163 + still 3.
5164 5164
5165 - - Bug Fixes and Optimizations 5165 + - Bug Fixes and Optimizations
5166 5166
5167 - - Performance fix: optimize page merging operation to avoid  
5168 - unnecessary open/close calls on files being merged. This solves  
5169 - a dramatic slow-down that was observed when merging certain  
5170 - types of files. 5167 + - Performance fix: optimize page merging operation to avoid
  5168 + unnecessary open/close calls on files being merged. This solves
  5169 + a dramatic slow-down that was observed when merging certain
  5170 + types of files.
5171 5171
5172 - - Optimize how memory was used for the TIFF predictor,  
5173 - drastically improving performance and memory usage for files  
5174 - containing high-resolution images compressed with Flate using  
5175 - the TIFF predictor. 5172 + - Optimize how memory was used for the TIFF predictor,
  5173 + drastically improving performance and memory usage for files
  5174 + containing high-resolution images compressed with Flate using
  5175 + the TIFF predictor.
5176 5176
5177 - - Bug fix: end of line characters were not properly handled  
5178 - inside strings in some cases. 5177 + - Bug fix: end of line characters were not properly handled
  5178 + inside strings in some cases.
5179 5179
5180 - - Bug fix: using @1@option@1@--progress@2@option@2@ on very small  
5181 - files could cause an infinite loop. 5180 + - Bug fix: using @1@option@1@--progress@2@option@2@ on very small
  5181 + files could cause an infinite loop.
5182 5182
5183 - - API enhancements 5183 + - API enhancements
5184 5184
5185 - - Add new class ``QPDFSystemError``, derived from  
5186 - ``std::runtime_error``, which is now thrown by  
5187 - ``QUtil::throw_system_error``. This enables the triggering  
5188 - ``errno`` value to be retrieved. 5185 + - Add new class ``QPDFSystemError``, derived from
  5186 + ``std::runtime_error``, which is now thrown by
  5187 + ``QUtil::throw_system_error``. This enables the triggering
  5188 + ``errno`` value to be retrieved.
5189 5189
5190 - - Add ``ClosedFileInputSource::stayOpen`` method, enabling a  
5191 - ``ClosedFileInputSource`` to stay open during manually  
5192 - indicated periods of high activity, thus reducing the overhead  
5193 - of frequent open/close operations. 5190 + - Add ``ClosedFileInputSource::stayOpen`` method, enabling a
  5191 + ``ClosedFileInputSource`` to stay open during manually
  5192 + indicated periods of high activity, thus reducing the overhead
  5193 + of frequent open/close operations.
5194 5194
5195 - - Build Changes 5195 + - Build Changes
5196 5196
5197 - - For the mingw builds, change the name of the DLL import library  
5198 - from @1@filename@1@libqpdf.a@2@filename@2@ to  
5199 - @1@filename@1@libqpdf.dll.a@2@filename@2@ to more accurately  
5200 - reflect that it is an import library rather than a static  
5201 - library. This potentially clears the way for supporting a  
5202 - static library in the future, though presently, the qpdf  
5203 - Windows build only builds the DLL and executables. 5197 + - For the mingw builds, change the name of the DLL import library
  5198 + from @1@filename@1@libqpdf.a@2@filename@2@ to
  5199 + @1@filename@1@libqpdf.dll.a@2@filename@2@ to more accurately
  5200 + reflect that it is an import library rather than a static
  5201 + library. This potentially clears the way for supporting a
  5202 + static library in the future, though presently, the qpdf
  5203 + Windows build only builds the DLL and executables.
5204 5204
5205 8.1.0: June 23, 2018 5205 8.1.0: June 23, 2018
5206 - - Usability Improvements  
5207 -  
5208 - - When splitting files, qpdf detects fonts and images that the  
5209 - document metadata claims are referenced from a page but are not  
5210 - actually referenced and omits them from the output file. This  
5211 - change can cause a significant reduction in the size of split  
5212 - PDF files for files created by some software packages. In some  
5213 - cases, it can also make page splitting slower. Prior versions  
5214 - of qpdf would believe the document metadata and sometimes  
5215 - include all the images from all the other pages even though the  
5216 - pages were no longer present. In the unlikely event that the  
5217 - old behavior should be desired, or if you have a case where  
5218 - page splitting is very slow, the old behavior (and speed) can  
5219 - be enabled by specifying  
5220 - @1@option@1@--preserve-unreferenced-resources@2@option@2@. For  
5221 - additional details, please see `Advanced Transformation  
5222 - Options <#ref.advanced-transformation>`__.  
5223 -  
5224 - - When merging multiple PDF files, qpdf no longer leaves all the  
5225 - files open. This makes it possible to merge numbers of files  
5226 - that may exceed the operating system's limit for the maximum  
5227 - number of open files.  
5228 -  
5229 - - The @1@option@1@--rotate@2@option@2@ option's syntax has been  
5230 - extended to make the page range optional. If you specify  
5231 - @1@option@1@--rotate=@1@replaceable@1@angle@2@replaceable@2@@2@option@2@  
5232 - without specifying a page range, the rotation will be applied  
5233 - to all pages. This can be especially useful for adjusting a PDF  
5234 - created from a multi-page document that was scanned upside  
5235 - down.  
5236 -  
5237 - - When merging multiple files, the  
5238 - @1@option@1@--verbose@2@option@2@ option now prints information  
5239 - about each file as it operates on that file.  
5240 -  
5241 - - When the @1@option@1@--progress@2@option@2@ option is  
5242 - specified, qpdf will print a running indicator of its best  
5243 - guess at how far through the writing process it is. Note that,  
5244 - as with all progress meters, it's an approximation. This option  
5245 - is implemented in a way that makes it useful for software that  
5246 - uses the qpdf library; see API Enhancements below.  
5247 -  
5248 - - Bug Fixes  
5249 -  
5250 - - Properly decrypt files that use revision 3 of the standard  
5251 - security handler but use 40 bit keys (even though revision 3  
5252 - supports 128-bit keys).  
5253 -  
5254 - - Limit depth of nested data structures to prevent crashes from  
5255 - certain types of malformed (malicious) PDFs.  
5256 -  
5257 - - In "newline before endstream" mode, insert the required extra  
5258 - newline before the ``endstream`` at the end of object streams.  
5259 - This one case was previously omitted.  
5260 -  
5261 - - API Enhancements  
5262 -  
5263 - - The first round of higher level "helper" interfaces has been  
5264 - introduced. These are designed to provide a more convenient way  
5265 - of interacting with certain document features than using  
5266 - ``QPDFObjectHandle`` directly. For details on helpers, see  
5267 - `Helper Classes <#ref.helper-classes>`__. Specific additional  
5268 - interfaces are described below.  
5269 -  
5270 - - Add two new document helper classes: ``QPDFPageDocumentHelper``  
5271 - for working with pages, and ``QPDFAcroFormDocumentHelper`` for  
5272 - working with interactive forms. No old methods have been  
5273 - removed, but ``QPDFPageDocumentHelper`` is now the preferred  
5274 - way to perform operations on pages rather than calling the old  
5275 - methods in ``QPDFObjectHandle`` and ``QPDF`` directly. Comments  
5276 - in the header files direct you to the new interfaces. Please  
5277 - see the header files and @1@filename@1@ChangeLog@2@filename@2@  
5278 - for additional details.  
5279 -  
5280 - - Add three new object helper class: ``QPDFPageObjectHelper`` for  
5281 - pages, ``QPDFFormFieldObjectHelper`` for interactive form  
5282 - fields, and ``QPDFAnnotationObjectHelper`` for annotations. All  
5283 - three classes are fairly sparse at the moment, but they have  
5284 - some useful, basic functionality.  
5285 -  
5286 - - A new example program  
5287 - @1@filename@1@examples/pdf-set-form-values.cc@2@filename@2@ has  
5288 - been added that illustrates use of the new document and object  
5289 - helpers.  
5290 -  
5291 - - The method ``QPDFWriter::registerProgressReporter`` has been  
5292 - added. This method allows you to register a function that is  
5293 - called by ``QPDFWriter`` to update your idea of the percentage  
5294 - it thinks it is through writing its output. Client programs can  
5295 - use this to implement reasonably accurate progress meters. The  
5296 - @1@command@1@qpdf@2@command@2@ command line tool uses this to  
5297 - implement its @1@option@1@--progress@2@option@2@ option.  
5298 -  
5299 - - New methods ``QPDFObjectHandle::newUnicodeString`` and  
5300 - ``QPDFObject::unparseBinary`` have been added to allow for more  
5301 - convenient creation of strings that are explicitly encoded  
5302 - using big-endian UTF-16. This is useful for creating strings  
5303 - that appear outside of content streams, such as labels, form  
5304 - fields, outlines, document metadata, etc.  
5305 -  
5306 - - A new class ``QPDFObjectHandle::Rectangle`` has been added to  
5307 - ease working with PDF rectangles, which are just arrays of four  
5308 - numeric values. 5206 + - Usability Improvements
  5207 +
  5208 + - When splitting files, qpdf detects fonts and images that the
  5209 + document metadata claims are referenced from a page but are not
  5210 + actually referenced and omits them from the output file. This
  5211 + change can cause a significant reduction in the size of split
  5212 + PDF files for files created by some software packages. In some
  5213 + cases, it can also make page splitting slower. Prior versions
  5214 + of qpdf would believe the document metadata and sometimes
  5215 + include all the images from all the other pages even though the
  5216 + pages were no longer present. In the unlikely event that the
  5217 + old behavior should be desired, or if you have a case where
  5218 + page splitting is very slow, the old behavior (and speed) can
  5219 + be enabled by specifying
  5220 + @1@option@1@--preserve-unreferenced-resources@2@option@2@. For
  5221 + additional details, please see `Advanced Transformation
  5222 + Options <#ref.advanced-transformation>`__.
  5223 +
  5224 + - When merging multiple PDF files, qpdf no longer leaves all the
  5225 + files open. This makes it possible to merge numbers of files
  5226 + that may exceed the operating system's limit for the maximum
  5227 + number of open files.
  5228 +
  5229 + - The @1@option@1@--rotate@2@option@2@ option's syntax has been
  5230 + extended to make the page range optional. If you specify
  5231 + @1@option@1@--rotate=@1@replaceable@1@angle@2@replaceable@2@@2@option@2@
  5232 + without specifying a page range, the rotation will be applied
  5233 + to all pages. This can be especially useful for adjusting a PDF
  5234 + created from a multi-page document that was scanned upside
  5235 + down.
  5236 +
  5237 + - When merging multiple files, the
  5238 + @1@option@1@--verbose@2@option@2@ option now prints information
  5239 + about each file as it operates on that file.
  5240 +
  5241 + - When the @1@option@1@--progress@2@option@2@ option is
  5242 + specified, qpdf will print a running indicator of its best
  5243 + guess at how far through the writing process it is. Note that,
  5244 + as with all progress meters, it's an approximation. This option
  5245 + is implemented in a way that makes it useful for software that
  5246 + uses the qpdf library; see API Enhancements below.
  5247 +
  5248 + - Bug Fixes
  5249 +
  5250 + - Properly decrypt files that use revision 3 of the standard
  5251 + security handler but use 40 bit keys (even though revision 3
  5252 + supports 128-bit keys).
  5253 +
  5254 + - Limit depth of nested data structures to prevent crashes from
  5255 + certain types of malformed (malicious) PDFs.
  5256 +
  5257 + - In "newline before endstream" mode, insert the required extra
  5258 + newline before the ``endstream`` at the end of object streams.
  5259 + This one case was previously omitted.
  5260 +
  5261 + - API Enhancements
  5262 +
  5263 + - The first round of higher level "helper" interfaces has been
  5264 + introduced. These are designed to provide a more convenient way
  5265 + of interacting with certain document features than using
  5266 + ``QPDFObjectHandle`` directly. For details on helpers, see
  5267 + `Helper Classes <#ref.helper-classes>`__. Specific additional
  5268 + interfaces are described below.
  5269 +
  5270 + - Add two new document helper classes: ``QPDFPageDocumentHelper``
  5271 + for working with pages, and ``QPDFAcroFormDocumentHelper`` for
  5272 + working with interactive forms. No old methods have been
  5273 + removed, but ``QPDFPageDocumentHelper`` is now the preferred
  5274 + way to perform operations on pages rather than calling the old
  5275 + methods in ``QPDFObjectHandle`` and ``QPDF`` directly. Comments
  5276 + in the header files direct you to the new interfaces. Please
  5277 + see the header files and @1@filename@1@ChangeLog@2@filename@2@
  5278 + for additional details.
  5279 +
  5280 + - Add three new object helper class: ``QPDFPageObjectHelper`` for
  5281 + pages, ``QPDFFormFieldObjectHelper`` for interactive form
  5282 + fields, and ``QPDFAnnotationObjectHelper`` for annotations. All
  5283 + three classes are fairly sparse at the moment, but they have
  5284 + some useful, basic functionality.
  5285 +
  5286 + - A new example program
  5287 + @1@filename@1@examples/pdf-set-form-values.cc@2@filename@2@ has
  5288 + been added that illustrates use of the new document and object
  5289 + helpers.
  5290 +
  5291 + - The method ``QPDFWriter::registerProgressReporter`` has been
  5292 + added. This method allows you to register a function that is
  5293 + called by ``QPDFWriter`` to update your idea of the percentage
  5294 + it thinks it is through writing its output. Client programs can
  5295 + use this to implement reasonably accurate progress meters. The
  5296 + @1@command@1@qpdf@2@command@2@ command line tool uses this to
  5297 + implement its @1@option@1@--progress@2@option@2@ option.
  5298 +
  5299 + - New methods ``QPDFObjectHandle::newUnicodeString`` and
  5300 + ``QPDFObject::unparseBinary`` have been added to allow for more
  5301 + convenient creation of strings that are explicitly encoded
  5302 + using big-endian UTF-16. This is useful for creating strings
  5303 + that appear outside of content streams, such as labels, form
  5304 + fields, outlines, document metadata, etc.
  5305 +
  5306 + - A new class ``QPDFObjectHandle::Rectangle`` has been added to
  5307 + ease working with PDF rectangles, which are just arrays of four
  5308 + numeric values.
5309 5309
5310 8.0.2: March 6, 2018 5310 8.0.2: March 6, 2018
5311 - - When a loop is detected while following cross reference streams or  
5312 - tables, treat this as damage instead of silently ignoring the  
5313 - previous table. This prevents loss of otherwise recoverable data  
5314 - in some damaged files. 5311 + - When a loop is detected while following cross reference streams or
  5312 + tables, treat this as damage instead of silently ignoring the
  5313 + previous table. This prevents loss of otherwise recoverable data
  5314 + in some damaged files.
5315 5315
5316 - - Properly handle pages with no contents. 5316 + - Properly handle pages with no contents.
5317 5317
5318 8.0.1: March 4, 2018 5318 8.0.1: March 4, 2018
5319 - - Disregard data check errors when uncompressing ``/FlateDecode``  
5320 - streams. This is consistent with most other PDF readers and allows  
5321 - qpdf to recover data from another class of malformed PDF files. 5319 + - Disregard data check errors when uncompressing ``/FlateDecode``
  5320 + streams. This is consistent with most other PDF readers and allows
  5321 + qpdf to recover data from another class of malformed PDF files.
5322 5322
5323 - - On the command line when specifying page ranges, support preceding  
5324 - a page number by "r" to indicate that it should be counted from  
5325 - the end. For example, the range ``r3-r1`` would indicate the last  
5326 - three pages of a document. 5323 + - On the command line when specifying page ranges, support preceding
  5324 + a page number by "r" to indicate that it should be counted from
  5325 + the end. For example, the range ``r3-r1`` would indicate the last
  5326 + three pages of a document.
5327 5327
5328 8.0.0: February 25, 2018 5328 8.0.0: February 25, 2018
5329 - - Packaging and Distribution Changes  
5330 -  
5331 - - QPDF is now distributed as an  
5332 - `AppImage <https://appimage.org/>`__ in addition to all the  
5333 - other ways it is distributed. The AppImage can be found in the  
5334 - download area with the other packages. Thanks to Kurt Pfeifle  
5335 - and Simon Peter for their contributions.  
5336 -  
5337 - - Bug Fixes  
5338 -  
5339 - - ``QPDFObjectHandle::getUTF8Val`` now properly treats  
5340 - non-Unicode strings as encoded with PDF Doc Encoding.  
5341 -  
5342 - - Improvements to handling of objects in PDF files that are not  
5343 - of the expected type. In most cases, qpdf will be able to warn  
5344 - for such cases rather than fail with an exception. Previous  
5345 - versions of qpdf would sometimes fail with errors such as  
5346 - "operation for dictionary object attempted on object of wrong  
5347 - type". This situation should be mostly or entirely eliminated  
5348 - now.  
5349 -  
5350 - - Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line  
5351 - Tool. All new options listed here are documented in more detail in  
5352 - `Running QPDF <#ref.using>`__.  
5353 -  
5354 - - The option  
5355 - @1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@  
5356 - has been added for debugging qpdf's linearization code.  
5357 -  
5358 - - The option @1@option@1@--coalesce-contents@2@option@2@ can be  
5359 - used to combine content streams of a page whose contents are an  
5360 - array of streams into a single stream.  
5361 -  
5362 - - API Enhancements. All new API calls are documented in their  
5363 - respective classes' header files. There are no non-compatible  
5364 - changes to the API.  
5365 -  
5366 - - Add function ``qpdf_check_pdf`` to the C API. This function  
5367 - does basic checking that is a subset of what @1@command@1@qpdf  
5368 - --check@2@command@2@ performs.  
5369 -  
5370 - - Major enhancements to the lexical layer of qpdf. For a complete  
5371 - list of enhancements, please refer to the  
5372 - @1@filename@1@ChangeLog@2@filename@2@ file. Most of the changes  
5373 - result in improvements to qpdf's ability handle erroneous  
5374 - files. It is also possible for programs to handle whitespace,  
5375 - comments, and inline images as tokens.  
5376 -  
5377 - - New API for working with PDF content streams at a lexical  
5378 - level. The new class ``QPDFObjectHandle::TokenFilter`` allows  
5379 - the developer to provide token handlers. Token filters can be  
5380 - used with several different methods in ``QPDFObjectHandle`` as  
5381 - well as with a lower-level interface. See comments in  
5382 - @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ as well as the  
5383 - new examples  
5384 - @1@filename@1@examples/pdf-filter-tokens.cc@2@filename@2@ and  
5385 - @1@filename@1@examples/pdf-count-strings.cc@2@filename@2@ for  
5386 - details. 5329 + - Packaging and Distribution Changes
  5330 +
  5331 + - QPDF is now distributed as an
  5332 + `AppImage <https://appimage.org/>`__ in addition to all the
  5333 + other ways it is distributed. The AppImage can be found in the
  5334 + download area with the other packages. Thanks to Kurt Pfeifle
  5335 + and Simon Peter for their contributions.
  5336 +
  5337 + - Bug Fixes
  5338 +
  5339 + - ``QPDFObjectHandle::getUTF8Val`` now properly treats
  5340 + non-Unicode strings as encoded with PDF Doc Encoding.
  5341 +
  5342 + - Improvements to handling of objects in PDF files that are not
  5343 + of the expected type. In most cases, qpdf will be able to warn
  5344 + for such cases rather than fail with an exception. Previous
  5345 + versions of qpdf would sometimes fail with errors such as
  5346 + "operation for dictionary object attempted on object of wrong
  5347 + type". This situation should be mostly or entirely eliminated
  5348 + now.
  5349 +
  5350 + - Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line
  5351 + Tool. All new options listed here are documented in more detail in
  5352 + `Running QPDF <#ref.using>`__.
  5353 +
  5354 + - The option
  5355 + @1@option@1@--linearize-pass1=@1@replaceable@1@file@2@replaceable@2@@2@option@2@
  5356 + has been added for debugging qpdf's linearization code.
  5357 +
  5358 + - The option @1@option@1@--coalesce-contents@2@option@2@ can be
  5359 + used to combine content streams of a page whose contents are an
  5360 + array of streams into a single stream.
  5361 +
  5362 + - API Enhancements. All new API calls are documented in their
  5363 + respective classes' header files. There are no non-compatible
  5364 + changes to the API.
  5365 +
  5366 + - Add function ``qpdf_check_pdf`` to the C API. This function
  5367 + does basic checking that is a subset of what @1@command@1@qpdf
  5368 + --check@2@command@2@ performs.
  5369 +
  5370 + - Major enhancements to the lexical layer of qpdf. For a complete
  5371 + list of enhancements, please refer to the
  5372 + @1@filename@1@ChangeLog@2@filename@2@ file. Most of the changes
  5373 + result in improvements to qpdf's ability handle erroneous
  5374 + files. It is also possible for programs to handle whitespace,
  5375 + comments, and inline images as tokens.
  5376 +
  5377 + - New API for working with PDF content streams at a lexical
  5378 + level. The new class ``QPDFObjectHandle::TokenFilter`` allows
  5379 + the developer to provide token handlers. Token filters can be
  5380 + used with several different methods in ``QPDFObjectHandle`` as
  5381 + well as with a lower-level interface. See comments in
  5382 + @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ as well as the
  5383 + new examples
  5384 + @1@filename@1@examples/pdf-filter-tokens.cc@2@filename@2@ and
  5385 + @1@filename@1@examples/pdf-count-strings.cc@2@filename@2@ for
  5386 + details.
5387 5387
5388 7.1.1: February 4, 2018 5388 7.1.1: February 4, 2018
5389 - - Bug fix: files whose /ID fields were other than 16 bytes long can  
5390 - now be properly linearized 5389 + - Bug fix: files whose /ID fields were other than 16 bytes long can
  5390 + now be properly linearized
5391 5391
5392 - - A few compile and link issues have been corrected for some  
5393 - platforms. 5392 + - A few compile and link issues have been corrected for some
  5393 + platforms.
5394 5394
5395 7.1.0: January 14, 2018 5395 7.1.0: January 14, 2018
5396 - - PDF files contain streams that may be compressed with various  
5397 - compression algorithms which, in some cases, may be enhanced by  
5398 - various predictor functions. Previously only the PNG up predictor  
5399 - was supported. In this version, all the PNG predictors as well as  
5400 - the TIFF predictor are supported. This increases the range of  
5401 - files that qpdf is able to handle.  
5402 -  
5403 - - QPDF now allows a raw encryption key to be specified in place of a  
5404 - password when opening encrypted files, and will optionally display  
5405 - the encryption key used by a file. This is a non-standard  
5406 - operation, but it can be useful in certain situations. Please see  
5407 - the discussion of @1@option@1@--password-is-hex-key@2@option@2@ in  
5408 - `Basic Options <#ref.basic-options>`__ or the comments around  
5409 - ``QPDF::setPasswordIsHexKey`` in  
5410 - @1@filename@1@QPDF.hh@2@filename@2@ for additional details.  
5411 -  
5412 - - Bug fix: numbers ending with a trailing decimal point are now  
5413 - properly recognized as numbers.  
5414 -  
5415 - - Bug fix: when building qpdf from source on some platforms  
5416 - (especially MacOS), the build could get confused by older versions  
5417 - of qpdf installed on the system. This has been corrected. 5396 + - PDF files contain streams that may be compressed with various
  5397 + compression algorithms which, in some cases, may be enhanced by
  5398 + various predictor functions. Previously only the PNG up predictor
  5399 + was supported. In this version, all the PNG predictors as well as
  5400 + the TIFF predictor are supported. This increases the range of
  5401 + files that qpdf is able to handle.
  5402 +
  5403 + - QPDF now allows a raw encryption key to be specified in place of a
  5404 + password when opening encrypted files, and will optionally display
  5405 + the encryption key used by a file. This is a non-standard
  5406 + operation, but it can be useful in certain situations. Please see
  5407 + the discussion of @1@option@1@--password-is-hex-key@2@option@2@ in
  5408 + `Basic Options <#ref.basic-options>`__ or the comments around
  5409 + ``QPDF::setPasswordIsHexKey`` in
  5410 + @1@filename@1@QPDF.hh@2@filename@2@ for additional details.
  5411 +
  5412 + - Bug fix: numbers ending with a trailing decimal point are now
  5413 + properly recognized as numbers.
  5414 +
  5415 + - Bug fix: when building qpdf from source on some platforms
  5416 + (especially MacOS), the build could get confused by older versions
  5417 + of qpdf installed on the system. This has been corrected.
5418 5418
5419 7.0.0: September 15, 2017 5419 7.0.0: September 15, 2017
5420 - - Packaging and Distribution Changes  
5421 -  
5422 - - QPDF's primary license is now `version 2.0 of the Apache  
5423 - License <http://www.apache.org/licenses/LICENSE-2.0>`__ rather  
5424 - than version 2.0 of the Artistic License. You may still, at  
5425 - your option, consider qpdf to be licensed with version 2.0 of  
5426 - the Artistic license.  
5427 -  
5428 - - QPDF no longer has a dependency on the PCRE (Perl-Compatible  
5429 - Regular Expression) library. QPDF now has an added dependency  
5430 - on the JPEG library.  
5431 -  
5432 - - Bug Fixes  
5433 -  
5434 - - This release contains many bug fixes for various infinite  
5435 - loops, memory leaks, and other memory errors that could be  
5436 - encountered with specially crafted or otherwise erroneous PDF  
5437 - files.  
5438 -  
5439 - - New Features  
5440 -  
5441 - - QPDF now supports reading and writing streams encoded with JPEG  
5442 - or RunLength encoding. Library API enhancements and  
5443 - command-line options have been added to control this behavior.  
5444 - See command-line options  
5445 - @1@option@1@--compress-streams@2@option@2@ and  
5446 - @1@option@1@--decode-level@2@option@2@ and methods  
5447 - ``QPDFWriter::setCompressStreams`` and  
5448 - ``QPDFWriter::setDecodeLevel``.  
5449 -  
5450 - - QPDF is much better at recovering from broken files. In most  
5451 - cases, qpdf will skip invalid objects and will preserve broken  
5452 - stream data by not attempting to filter broken streams. QPDF is  
5453 - now able to recover or at least not crash on dozens of broken  
5454 - test files I have received over the past few years.  
5455 -  
5456 - - Page rotation is now supported and accessible from both the  
5457 - library and the command line.  
5458 -  
5459 - - ``QPDFWriter`` supports writing files in a way that preserves  
5460 - PCLm compliance in support of driverless printing. This is very  
5461 - specialized and is only useful to applications that already  
5462 - know how to create PCLm files.  
5463 -  
5464 - - Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line  
5465 - Tool. All new options listed here are documented in more detail in  
5466 - `Running QPDF <#ref.using>`__.  
5467 -  
5468 - - Command-line arguments can now be read from files or standard  
5469 - input using ``@file`` or ``@-`` syntax. Please see `Basic  
5470 - Invocation <#ref.invocation>`__.  
5471 -  
5472 - - @1@option@1@--rotate@2@option@2@: request page rotation  
5473 -  
5474 - - @1@option@1@--newline-before-endstream@2@option@2@: ensure that  
5475 - a newline appears before every ``endstream`` keyword in the  
5476 - file; used to prevent qpdf from breaking PDF/A compliance on  
5477 - already compliant files.  
5478 -  
5479 - - @1@option@1@--preserve-unreferenced@2@option@2@: preserve  
5480 - unreferenced objects in the input PDF  
5481 -  
5482 - - @1@option@1@--split-pages@2@option@2@: break output into chunks  
5483 - with fixed numbers of pages  
5484 -  
5485 - - @1@option@1@--verbose@2@option@2@: print the name of each  
5486 - output file that is created  
5487 -  
5488 - - @1@option@1@--compress-streams@2@option@2@ and  
5489 - @1@option@1@--decode-level@2@option@2@ replace  
5490 - @1@option@1@--stream-data@2@option@2@ for improving granularity  
5491 - of controlling compression and decompression of stream data.  
5492 - The @1@option@1@--stream-data@2@option@2@ option will remain  
5493 - available.  
5494 -  
5495 - - When running @1@command@1@qpdf --check@2@command@2@ with other  
5496 - options, checks are always run first. This enables qpdf to  
5497 - perform its full recovery logic before outputting other  
5498 - information. This can be especially useful when manually  
5499 - recovering broken files, looking at qpdf's regenerated cross  
5500 - reference table, or other similar operations.  
5501 -  
5502 - - Process @1@command@1@--pages@2@command@2@ earlier so that other  
5503 - options like @1@option@1@--show-pages@2@option@2@ or  
5504 - @1@option@1@--split-pages@2@option@2@ can operate on the file  
5505 - after page splitting/merging has occurred.  
5506 -  
5507 - - API Changes. All new API calls are documented in their respective  
5508 - classes' header files.  
5509 -  
5510 - - ``QPDFObjectHandle::rotatePage``: apply rotation to a page  
5511 - object  
5512 -  
5513 - - ``QPDFWriter::setNewlineBeforeEndstream``: force newline to  
5514 - appear before ``endstream``  
5515 -  
5516 - - ``QPDFWriter::setPreserveUnreferencedObjects``: preserve  
5517 - unreferenced objects that appear in the input PDF. The default  
5518 - behavior is to discard them.  
5519 -  
5520 - - New ``Pipeline`` types ``Pl_RunLength`` and ``Pl_DCT`` are  
5521 - available for developers who wish to produce or consume  
5522 - RunLength or DCT stream data directly. The  
5523 - @1@filename@1@examples/pdf-create.cc@2@filename@2@ example  
5524 - illustrates their use.  
5525 -  
5526 - - ``QPDFWriter::setCompressStreams`` and  
5527 - ``QPDFWriter::setDecodeLevel`` methods control handling of  
5528 - different types of stream compression.  
5529 -  
5530 - - Add new C API functions ``qpdf_set_compress_streams``,  
5531 - ``qpdf_set_decode_level``,  
5532 - ``qpdf_set_preserve_unreferenced_objects``, and  
5533 - ``qpdf_set_newline_before_endstream`` corresponding to the new  
5534 - ``QPDFWriter`` methods. 5420 + - Packaging and Distribution Changes
  5421 +
  5422 + - QPDF's primary license is now `version 2.0 of the Apache
  5423 + License <http://www.apache.org/licenses/LICENSE-2.0>`__ rather
  5424 + than version 2.0 of the Artistic License. You may still, at
  5425 + your option, consider qpdf to be licensed with version 2.0 of
  5426 + the Artistic license.
  5427 +
  5428 + - QPDF no longer has a dependency on the PCRE (Perl-Compatible
  5429 + Regular Expression) library. QPDF now has an added dependency
  5430 + on the JPEG library.
  5431 +
  5432 + - Bug Fixes
  5433 +
  5434 + - This release contains many bug fixes for various infinite
  5435 + loops, memory leaks, and other memory errors that could be
  5436 + encountered with specially crafted or otherwise erroneous PDF
  5437 + files.
  5438 +
  5439 + - New Features
  5440 +
  5441 + - QPDF now supports reading and writing streams encoded with JPEG
  5442 + or RunLength encoding. Library API enhancements and
  5443 + command-line options have been added to control this behavior.
  5444 + See command-line options
  5445 + @1@option@1@--compress-streams@2@option@2@ and
  5446 + @1@option@1@--decode-level@2@option@2@ and methods
  5447 + ``QPDFWriter::setCompressStreams`` and
  5448 + ``QPDFWriter::setDecodeLevel``.
  5449 +
  5450 + - QPDF is much better at recovering from broken files. In most
  5451 + cases, qpdf will skip invalid objects and will preserve broken
  5452 + stream data by not attempting to filter broken streams. QPDF is
  5453 + now able to recover or at least not crash on dozens of broken
  5454 + test files I have received over the past few years.
  5455 +
  5456 + - Page rotation is now supported and accessible from both the
  5457 + library and the command line.
  5458 +
  5459 + - ``QPDFWriter`` supports writing files in a way that preserves
  5460 + PCLm compliance in support of driverless printing. This is very
  5461 + specialized and is only useful to applications that already
  5462 + know how to create PCLm files.
  5463 +
  5464 + - Enhancements to the @1@command@1@qpdf@2@command@2@ Command-line
  5465 + Tool. All new options listed here are documented in more detail in
  5466 + `Running QPDF <#ref.using>`__.
  5467 +
  5468 + - Command-line arguments can now be read from files or standard
  5469 + input using ``@file`` or ``@-`` syntax. Please see `Basic
  5470 + Invocation <#ref.invocation>`__.
  5471 +
  5472 + - @1@option@1@--rotate@2@option@2@: request page rotation
  5473 +
  5474 + - @1@option@1@--newline-before-endstream@2@option@2@: ensure that
  5475 + a newline appears before every ``endstream`` keyword in the
  5476 + file; used to prevent qpdf from breaking PDF/A compliance on
  5477 + already compliant files.
  5478 +
  5479 + - @1@option@1@--preserve-unreferenced@2@option@2@: preserve
  5480 + unreferenced objects in the input PDF
  5481 +
  5482 + - @1@option@1@--split-pages@2@option@2@: break output into chunks
  5483 + with fixed numbers of pages
  5484 +
  5485 + - @1@option@1@--verbose@2@option@2@: print the name of each
  5486 + output file that is created
  5487 +
  5488 + - @1@option@1@--compress-streams@2@option@2@ and
  5489 + @1@option@1@--decode-level@2@option@2@ replace
  5490 + @1@option@1@--stream-data@2@option@2@ for improving granularity
  5491 + of controlling compression and decompression of stream data.
  5492 + The @1@option@1@--stream-data@2@option@2@ option will remain
  5493 + available.
  5494 +
  5495 + - When running @1@command@1@qpdf --check@2@command@2@ with other
  5496 + options, checks are always run first. This enables qpdf to
  5497 + perform its full recovery logic before outputting other
  5498 + information. This can be especially useful when manually
  5499 + recovering broken files, looking at qpdf's regenerated cross
  5500 + reference table, or other similar operations.
  5501 +
  5502 + - Process @1@command@1@--pages@2@command@2@ earlier so that other
  5503 + options like @1@option@1@--show-pages@2@option@2@ or
  5504 + @1@option@1@--split-pages@2@option@2@ can operate on the file
  5505 + after page splitting/merging has occurred.
  5506 +
  5507 + - API Changes. All new API calls are documented in their respective
  5508 + classes' header files.
  5509 +
  5510 + - ``QPDFObjectHandle::rotatePage``: apply rotation to a page
  5511 + object
  5512 +
  5513 + - ``QPDFWriter::setNewlineBeforeEndstream``: force newline to
  5514 + appear before ``endstream``
  5515 +
  5516 + - ``QPDFWriter::setPreserveUnreferencedObjects``: preserve
  5517 + unreferenced objects that appear in the input PDF. The default
  5518 + behavior is to discard them.
  5519 +
  5520 + - New ``Pipeline`` types ``Pl_RunLength`` and ``Pl_DCT`` are
  5521 + available for developers who wish to produce or consume
  5522 + RunLength or DCT stream data directly. The
  5523 + @1@filename@1@examples/pdf-create.cc@2@filename@2@ example
  5524 + illustrates their use.
  5525 +
  5526 + - ``QPDFWriter::setCompressStreams`` and
  5527 + ``QPDFWriter::setDecodeLevel`` methods control handling of
  5528 + different types of stream compression.
  5529 +
  5530 + - Add new C API functions ``qpdf_set_compress_streams``,
  5531 + ``qpdf_set_decode_level``,
  5532 + ``qpdf_set_preserve_unreferenced_objects``, and
  5533 + ``qpdf_set_newline_before_endstream`` corresponding to the new
  5534 + ``QPDFWriter`` methods.
5535 5535
5536 6.0.0: November 10, 2015 5536 6.0.0: November 10, 2015
5537 - - Implement @1@option@1@--deterministic-id@2@option@2@ command-line  
5538 - option and ``QPDFWriter::setDeterministicID`` as well as C API  
5539 - function ``qpdf_set_deterministic_ID`` for generating a  
5540 - deterministic ID for non-encrypted files. When this option is  
5541 - selected, the ID of the file depends on the contents of the output  
5542 - file, and not on transient items such as the timestamp or output  
5543 - file name. 5537 + - Implement @1@option@1@--deterministic-id@2@option@2@ command-line
  5538 + option and ``QPDFWriter::setDeterministicID`` as well as C API
  5539 + function ``qpdf_set_deterministic_ID`` for generating a
  5540 + deterministic ID for non-encrypted files. When this option is
  5541 + selected, the ID of the file depends on the contents of the output
  5542 + file, and not on transient items such as the timestamp or output
  5543 + file name.
5544 5544
5545 - - Make qpdf more tolerant of files whose xref table entries are not  
5546 - the correct length. 5545 + - Make qpdf more tolerant of files whose xref table entries are not
  5546 + the correct length.
5547 5547
5548 5.1.3: May 24, 2015 5548 5.1.3: May 24, 2015
5549 - - Bug fix: fix-qdf was not properly handling files that contained  
5550 - object streams with more than 255 objects in them. 5549 + - Bug fix: fix-qdf was not properly handling files that contained
  5550 + object streams with more than 255 objects in them.
5551 5551
5552 - - Bug fix: qpdf was not properly initializing Microsoft's secure  
5553 - crypto provider on fresh Windows installations that had not had  
5554 - any keys created yet. 5552 + - Bug fix: qpdf was not properly initializing Microsoft's secure
  5553 + crypto provider on fresh Windows installations that had not had
  5554 + any keys created yet.
5555 5555
5556 - - Fix a few errors found by Gynvael Coldwind and Mateusz Jurczyk of  
5557 - the Google Security Team. Please see the ChangeLog for details. 5556 + - Fix a few errors found by Gynvael Coldwind and Mateusz Jurczyk of
  5557 + the Google Security Team. Please see the ChangeLog for details.
5558 5558
5559 - - Properly handle pages that have no contents at all. There were  
5560 - many cases in which qpdf handled this fine, but a few methods  
5561 - blindly obtained page contents with handling the possibility that  
5562 - there were no contents. 5559 + - Properly handle pages that have no contents at all. There were
  5560 + many cases in which qpdf handled this fine, but a few methods
  5561 + blindly obtained page contents with handling the possibility that
  5562 + there were no contents.
5563 5563
5564 - - Make qpdf more robust for a few more kinds of problems that may  
5565 - occur in invalid PDF files. 5564 + - Make qpdf more robust for a few more kinds of problems that may
  5565 + occur in invalid PDF files.
5566 5566
5567 5.1.2: June 7, 2014 5567 5.1.2: June 7, 2014
5568 - - Bug fix: linearizing files could create a corrupted output file  
5569 - under extremely unlikely file size circumstances. See ChangeLog  
5570 - for details. The odds of getting hit by this are very low, though  
5571 - one person did. 5568 + - Bug fix: linearizing files could create a corrupted output file
  5569 + under extremely unlikely file size circumstances. See ChangeLog
  5570 + for details. The odds of getting hit by this are very low, though
  5571 + one person did.
5572 5572
5573 - - Bug fix: qpdf would fail to write files that had streams with  
5574 - decode parameters referencing other streams. 5573 + - Bug fix: qpdf would fail to write files that had streams with
  5574 + decode parameters referencing other streams.
5575 5575
5576 - - New example program: @1@command@1@pdf-split-pages@2@command@2@:  
5577 - efficiently split PDF files into individual pages. The example  
5578 - program does this more efficiently than using @1@command@1@qpdf  
5579 - --pages@2@command@2@ to do it. 5576 + - New example program: @1@command@1@pdf-split-pages@2@command@2@:
  5577 + efficiently split PDF files into individual pages. The example
  5578 + program does this more efficiently than using @1@command@1@qpdf
  5579 + --pages@2@command@2@ to do it.
5580 5580
5581 - - Packaging fix: Visual C++ binaries did not support Windows XP.  
5582 - This has been rectified by updating the compilers used to generate  
5583 - the release binaries. 5581 + - Packaging fix: Visual C++ binaries did not support Windows XP.
  5582 + This has been rectified by updating the compilers used to generate
  5583 + the release binaries.
5584 5584
5585 5.1.1: January 14, 2014 5585 5.1.1: January 14, 2014
5586 - - Performance fix: copying foreign objects could be very slow with  
5587 - certain types of files. This was most likely to be visible during  
5588 - page splitting and was due to traversing the same objects multiple  
5589 - times in some cases. 5586 + - Performance fix: copying foreign objects could be very slow with
  5587 + certain types of files. This was most likely to be visible during
  5588 + page splitting and was due to traversing the same objects multiple
  5589 + times in some cases.
5590 5590
5591 5.1.0: December 17, 2013 5591 5.1.0: December 17, 2013
5592 - - Added runtime option (``QUtil::setRandomDataProvider``) to supply  
5593 - your own random data provider. You can use this if you want to  
5594 - avoid using the OS-provided secure random number generation  
5595 - facility or stdlib's less secure version. See comments in  
5596 - include/qpdf/QUtil.hh for details. 5592 + - Added runtime option (``QUtil::setRandomDataProvider``) to supply
  5593 + your own random data provider. You can use this if you want to
  5594 + avoid using the OS-provided secure random number generation
  5595 + facility or stdlib's less secure version. See comments in
  5596 + include/qpdf/QUtil.hh for details.
5597 5597
5598 - - Fixed image comparison tests to not create 12-bit-per-pixel images  
5599 - since some versions of tiffcmp have bugs in comparing them in some  
5600 - cases. This increases the disk space required by the image  
5601 - comparison tests, which are off by default anyway. 5598 + - Fixed image comparison tests to not create 12-bit-per-pixel images
  5599 + since some versions of tiffcmp have bugs in comparing them in some
  5600 + cases. This increases the disk space required by the image
  5601 + comparison tests, which are off by default anyway.
5602 5602
5603 - - Introduce a number of small fixes for compilation on the latest  
5604 - clang in MacOS and the latest Visual C++ in Windows. 5603 + - Introduce a number of small fixes for compilation on the latest
  5604 + clang in MacOS and the latest Visual C++ in Windows.
5605 5605
5606 - - Be able to handle broken files that end the xref table header with  
5607 - a space instead of a newline. 5606 + - Be able to handle broken files that end the xref table header with
  5607 + a space instead of a newline.
5608 5608
5609 5.0.1: October 18, 2013 5609 5.0.1: October 18, 2013
5610 - - Thanks to a detailed review by Florian Weimer and the Red Hat  
5611 - Product Security Team, this release includes a number of  
5612 - non-user-visible security hardening changes. Please see the  
5613 - ChangeLog file in the source distribution for the complete list.  
5614 -  
5615 - - When available, operating system-specific secure random number  
5616 - generation is used for generating initialization vectors and other  
5617 - random values used during encryption or file creation. For the  
5618 - Windows build, this results in an added dependency on Microsoft's  
5619 - cryptography API. To disable the OS-specific cryptography and use  
5620 - the old version, pass the  
5621 - @1@option@1@--enable-insecure-random@2@option@2@ option to  
5622 - @1@command@1@./configure@2@command@2@.  
5623 -  
5624 - - The @1@command@1@qpdf@2@command@2@ command-line tool now issues a  
5625 - warning when @1@option@1@-accessibility=n@2@option@2@ is specified  
5626 - for newer encryption versions stating that the option is ignored.  
5627 - qpdf, per the spec, has always ignored this flag, but it  
5628 - previously did so silently. This warning is issued only by the  
5629 - command-line tool, not by the library. The library's handling of  
5630 - this flag is unchanged. 5610 + - Thanks to a detailed review by Florian Weimer and the Red Hat
  5611 + Product Security Team, this release includes a number of
  5612 + non-user-visible security hardening changes. Please see the
  5613 + ChangeLog file in the source distribution for the complete list.
  5614 +
  5615 + - When available, operating system-specific secure random number
  5616 + generation is used for generating initialization vectors and other
  5617 + random values used during encryption or file creation. For the
  5618 + Windows build, this results in an added dependency on Microsoft's
  5619 + cryptography API. To disable the OS-specific cryptography and use
  5620 + the old version, pass the
  5621 + @1@option@1@--enable-insecure-random@2@option@2@ option to
  5622 + @1@command@1@./configure@2@command@2@.
  5623 +
  5624 + - The @1@command@1@qpdf@2@command@2@ command-line tool now issues a
  5625 + warning when @1@option@1@-accessibility=n@2@option@2@ is specified
  5626 + for newer encryption versions stating that the option is ignored.
  5627 + qpdf, per the spec, has always ignored this flag, but it
  5628 + previously did so silently. This warning is issued only by the
  5629 + command-line tool, not by the library. The library's handling of
  5630 + this flag is unchanged.
5631 5631
5632 5.0.0: July 10, 2013 5632 5.0.0: July 10, 2013
5633 - - Bug fix: previous versions of qpdf would lose objects with  
5634 - generation != 0 when generating object streams. Fixing this  
5635 - required changes to the public API.  
5636 -  
5637 - - Removed methods from public API that were only supposed to be  
5638 - called by QPDFWriter and couldn't realistically be called anywhere  
5639 - else. See ChangeLog for details.  
5640 -  
5641 - - New ``QPDFObjGen`` class added to represent an object  
5642 - ID/generation pair. ``QPDFObjectHandle::getObjGen()`` is now  
5643 - preferred over ``QPDFObjectHandle::getObjectID()`` and  
5644 - ``QPDFObjectHandle::getGeneration()`` as it makes it less likely  
5645 - for people to accidentally write code that ignores the generation  
5646 - number. See @1@filename@1@QPDF.hh@2@filename@2@ and  
5647 - @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for additional  
5648 - notes.  
5649 -  
5650 - - Add @1@option@1@--show-npages@2@option@2@ command-line option to  
5651 - the @1@command@1@qpdf@2@command@2@ command to show the number of  
5652 - pages in a file.  
5653 -  
5654 - - Allow omission of the page range within  
5655 - @1@option@1@--pages@2@option@2@ for the  
5656 - @1@command@1@qpdf@2@command@2@ command. When omitted, the page  
5657 - range is implicitly taken to be all the pages in the file.  
5658 -  
5659 - - Various enhancements were made to support different types of  
5660 - broken files or broken readers. Details can be found in  
5661 - @1@filename@1@ChangeLog@2@filename@2@. 5633 + - Bug fix: previous versions of qpdf would lose objects with
  5634 + generation != 0 when generating object streams. Fixing this
  5635 + required changes to the public API.
  5636 +
  5637 + - Removed methods from public API that were only supposed to be
  5638 + called by QPDFWriter and couldn't realistically be called anywhere
  5639 + else. See ChangeLog for details.
  5640 +
  5641 + - New ``QPDFObjGen`` class added to represent an object
  5642 + ID/generation pair. ``QPDFObjectHandle::getObjGen()`` is now
  5643 + preferred over ``QPDFObjectHandle::getObjectID()`` and
  5644 + ``QPDFObjectHandle::getGeneration()`` as it makes it less likely
  5645 + for people to accidentally write code that ignores the generation
  5646 + number. See @1@filename@1@QPDF.hh@2@filename@2@ and
  5647 + @1@filename@1@QPDFObjectHandle.hh@2@filename@2@ for additional
  5648 + notes.
  5649 +
  5650 + - Add @1@option@1@--show-npages@2@option@2@ command-line option to
  5651 + the @1@command@1@qpdf@2@command@2@ command to show the number of
  5652 + pages in a file.
  5653 +
  5654 + - Allow omission of the page range within
  5655 + @1@option@1@--pages@2@option@2@ for the
  5656 + @1@command@1@qpdf@2@command@2@ command. When omitted, the page
  5657 + range is implicitly taken to be all the pages in the file.
  5658 +
  5659 + - Various enhancements were made to support different types of
  5660 + broken files or broken readers. Details can be found in
  5661 + @1@filename@1@ChangeLog@2@filename@2@.
5662 5662
5663 4.1.0: April 14, 2013 5663 4.1.0: April 14, 2013
5664 - - Note to people including qpdf in distributions: the  
5665 - @1@filename@1@.la@2@filename@2@ files generated by libtool are now  
5666 - installed by qpdf's @1@command@1@make install@2@command@2@ target.  
5667 - Before, they were not installed. This means that if your  
5668 - distribution does not want to include  
5669 - @1@filename@1@.la@2@filename@2@ files, you must remove them as  
5670 - part of your packaging process.  
5671 -  
5672 - - Major enhancement: API enhancements have been made to support  
5673 - parsing of content streams. This enhancement includes the  
5674 - following changes:  
5675 -  
5676 - - ``QPDFObjectHandle::parseContentStream`` method parses objects  
5677 - in a content stream and calls handlers in a callback class. The  
5678 - example  
5679 - @1@filename@1@examples/pdf-parse-content.cc@2@filename@2@  
5680 - illustrates how this may be used.  
5681 -  
5682 - - ``QPDFObjectHandle`` can now represent operators and inline  
5683 - images, object types that may only appear in content streams.  
5684 -  
5685 - - Method ``QPDFObjectHandle::getTypeCode()`` returns an  
5686 - enumerated type value representing the underlying object type.  
5687 - Method ``QPDFObjectHandle::getTypeName()`` returns a text  
5688 - string describing the name of the type of a  
5689 - ``QPDFObjectHandle`` object. These methods can be used for more  
5690 - efficient parsing and debugging/diagnostic messages.  
5691 -  
5692 - - @1@command@1@qpdf --check@2@command@2@ now parses all pages'  
5693 - content streams in addition to doing other checks. While there are  
5694 - still many types of errors that cannot be detected, syntactic  
5695 - errors in content streams will now be reported.  
5696 -  
5697 - - Minor compilation enhancements have been made to facilitate easier  
5698 - for support for a broader range of compilers and compiler  
5699 - versions.  
5700 -  
5701 - - Warning flags have been moved into a separate variable in  
5702 - @1@filename@1@autoconf.mk@2@filename@2@  
5703 -  
5704 - - The configure flag @1@option@1@--enable-werror@2@option@2@ work  
5705 - for Microsoft compilers  
5706 -  
5707 - - All MSVC CRT security warnings have been resolved.  
5708 -  
5709 - - All C-style casts in C++ Code have been replaced by C++ casts,  
5710 - and many casts that had been included to suppress higher  
5711 - warning levels for some compilers have been removed, primarily  
5712 - for clarity. Places where integer type coercion occurs have  
5713 - been scrutinized. A new casting policy has been documented in  
5714 - the manual. This is of concern mainly to people porting qpdf to  
5715 - new platforms or compilers. It is not visible to programmers  
5716 - writing code that uses the library  
5717 -  
5718 - - Some internal limits have been removed in code that converts  
5719 - numbers to strings. This is largely invisible to users, but it  
5720 - does trigger a bug in some older versions of mingw-w64's C++  
5721 - library. See @1@filename@1@README-windows.md@2@filename@2@ in  
5722 - the source distribution if you think this may affect you. The  
5723 - copy of the DLL distributed with qpdf's binary distribution is  
5724 - not affected by this problem.  
5725 -  
5726 - - The RPM spec file previously included with qpdf has been removed.  
5727 - This is because virtually all Linux distributions include qpdf now  
5728 - that it is a dependency of CUPS filters.  
5729 -  
5730 - - A few bug fixes are included:  
5731 -  
5732 - - Overridden compressed objects are properly handled. Before,  
5733 - there were certain constructs that could cause qpdf to see old  
5734 - versions of some objects. The most usual manifestation of this  
5735 - was loss of filled in form values for certain files.  
5736 -  
5737 - - Installation no longer uses GNU/Linux-specific versions of some  
5738 - commands, so @1@command@1@make install@2@command@2@ works on  
5739 - Solaris with native tools.  
5740 -  
5741 - - The 64-bit mingw Windows binary package no longer includes a  
5742 - 32-bit DLL. 5664 + - Note to people including qpdf in distributions: the
  5665 + @1@filename@1@.la@2@filename@2@ files generated by libtool are now
  5666 + installed by qpdf's @1@command@1@make install@2@command@2@ target.
  5667 + Before, they were not installed. This means that if your
  5668 + distribution does not want to include
  5669 + @1@filename@1@.la@2@filename@2@ files, you must remove them as
  5670 + part of your packaging process.
  5671 +
  5672 + - Major enhancement: API enhancements have been made to support
  5673 + parsing of content streams. This enhancement includes the
  5674 + following changes:
  5675 +
  5676 + - ``QPDFObjectHandle::parseContentStream`` method parses objects
  5677 + in a content stream and calls handlers in a callback class. The
  5678 + example
  5679 + @1@filename@1@examples/pdf-parse-content.cc@2@filename@2@
  5680 + illustrates how this may be used.
  5681 +
  5682 + - ``QPDFObjectHandle`` can now represent operators and inline
  5683 + images, object types that may only appear in content streams.
  5684 +
  5685 + - Method ``QPDFObjectHandle::getTypeCode()`` returns an
  5686 + enumerated type value representing the underlying object type.
  5687 + Method ``QPDFObjectHandle::getTypeName()`` returns a text
  5688 + string describing the name of the type of a
  5689 + ``QPDFObjectHandle`` object. These methods can be used for more
  5690 + efficient parsing and debugging/diagnostic messages.
  5691 +
  5692 + - @1@command@1@qpdf --check@2@command@2@ now parses all pages'
  5693 + content streams in addition to doing other checks. While there are
  5694 + still many types of errors that cannot be detected, syntactic
  5695 + errors in content streams will now be reported.
  5696 +
  5697 + - Minor compilation enhancements have been made to facilitate easier
  5698 + for support for a broader range of compilers and compiler
  5699 + versions.
  5700 +
  5701 + - Warning flags have been moved into a separate variable in
  5702 + @1@filename@1@autoconf.mk@2@filename@2@
  5703 +
  5704 + - The configure flag @1@option@1@--enable-werror@2@option@2@ work
  5705 + for Microsoft compilers
  5706 +
  5707 + - All MSVC CRT security warnings have been resolved.
  5708 +
  5709 + - All C-style casts in C++ Code have been replaced by C++ casts,
  5710 + and many casts that had been included to suppress higher
  5711 + warning levels for some compilers have been removed, primarily
  5712 + for clarity. Places where integer type coercion occurs have
  5713 + been scrutinized. A new casting policy has been documented in
  5714 + the manual. This is of concern mainly to people porting qpdf to
  5715 + new platforms or compilers. It is not visible to programmers
  5716 + writing code that uses the library
  5717 +
  5718 + - Some internal limits have been removed in code that converts
  5719 + numbers to strings. This is largely invisible to users, but it
  5720 + does trigger a bug in some older versions of mingw-w64's C++
  5721 + library. See @1@filename@1@README-windows.md@2@filename@2@ in
  5722 + the source distribution if you think this may affect you. The
  5723 + copy of the DLL distributed with qpdf's binary distribution is
  5724 + not affected by this problem.
  5725 +
  5726 + - The RPM spec file previously included with qpdf has been removed.
  5727 + This is because virtually all Linux distributions include qpdf now
  5728 + that it is a dependency of CUPS filters.
  5729 +
  5730 + - A few bug fixes are included:
  5731 +
  5732 + - Overridden compressed objects are properly handled. Before,
  5733 + there were certain constructs that could cause qpdf to see old
  5734 + versions of some objects. The most usual manifestation of this
  5735 + was loss of filled in form values for certain files.
  5736 +
  5737 + - Installation no longer uses GNU/Linux-specific versions of some
  5738 + commands, so @1@command@1@make install@2@command@2@ works on
  5739 + Solaris with native tools.
  5740 +
  5741 + - The 64-bit mingw Windows binary package no longer includes a
  5742 + 32-bit DLL.
5743 5743
5744 4.0.1: January 17, 2013 5744 4.0.1: January 17, 2013
5745 - - Fix detection of binary attachments in test suite to avoid false  
5746 - test failures on some platforms.  
5747 -  
5748 - - Add clarifying comment in @1@filename@1@QPDF.hh@2@filename@2@ to  
5749 - methods that return the user password explaining that it is no  
5750 - longer possible with newer encryption formats to recover the user  
5751 - password knowing the owner password. In earlier encryption  
5752 - formats, the user password was encrypted in the file using the  
5753 - owner password. In newer encryption formats, a separate encryption  
5754 - key is used on the file, and that key is independently encrypted  
5755 - using both the user password and the owner password. 5745 + - Fix detection of binary attachments in test suite to avoid false
  5746 + test failures on some platforms.
  5747 +
  5748 + - Add clarifying comment in @1@filename@1@QPDF.hh@2@filename@2@ to
  5749 + methods that return the user password explaining that it is no
  5750 + longer possible with newer encryption formats to recover the user
  5751 + password knowing the owner password. In earlier encryption
  5752 + formats, the user password was encrypted in the file using the
  5753 + owner password. In newer encryption formats, a separate encryption
  5754 + key is used on the file, and that key is independently encrypted
  5755 + using both the user password and the owner password.
5756 5756
5757 4.0.0: December 31, 2012 5757 4.0.0: December 31, 2012
5758 - - Major enhancement: support has been added for newer encryption  
5759 - schemes supported by version X of Adobe Acrobat. This includes use  
5760 - of 127-character passwords, 256-bit encryption keys, and the  
5761 - encryption scheme specified in ISO 32000-2, the PDF 2.0  
5762 - specification. This scheme can be chosen from the command line by  
5763 - specifying use of 256-bit keys. qpdf also supports the deprecated  
5764 - encryption method used by Acrobat IX. This encryption style has  
5765 - known security weaknesses and should not be used in practice.  
5766 - However, such files exist "in the wild," so support for this  
5767 - scheme is still useful. New methods  
5768 - ``QPDFWriter::setR6EncryptionParameters`` (for the PDF 2.0 scheme)  
5769 - and ``QPDFWriter::setR5EncryptionParameters`` (for the deprecated  
5770 - scheme) have been added to enable these new encryption schemes.  
5771 - Corresponding functions have been added to the C API as well.  
5772 -  
5773 - - Full support for Adobe extension levels in PDF version  
5774 - information. Starting with PDF version 1.7, corresponding to ISO  
5775 - 32000, Adobe adds new functionality by increasing the extension  
5776 - level rather than increasing the version. This support includes  
5777 - addition of the ``QPDF::getExtensionLevel`` method for retrieving  
5778 - the document's extension level, addition of versions of  
5779 - ``QPDFWriter::setMinimumPDFVersion`` and  
5780 - ``QPDFWriter::forcePDFVersion`` that accept an extension level,  
5781 - and extended syntax for specifying forced and minimum versions on  
5782 - the command line as described in `Advanced Transformation  
5783 - Options <#ref.advanced-transformation>`__. Corresponding functions  
5784 - have been added to the C API as well.  
5785 -  
5786 - - Minor fixes to prevent qpdf from referencing objects in the file  
5787 - that are not referenced in the file's overall structure. Most  
5788 - files don't have any such objects, but some files have contain  
5789 - unreferenced objects with errors, so these fixes prevent qpdf from  
5790 - needlessly rejecting or complaining about such objects.  
5791 -  
5792 - - Add new generalized methods for reading and writing files from/to  
5793 - programmer-defined sources. The method  
5794 - ``QPDF::processInputSource`` allows the programmer to use any  
5795 - input source for the input file, and  
5796 - ``QPDFWriter::setOutputPipeline`` allows the programmer to write  
5797 - the output file through any pipeline. These methods would make it  
5798 - possible to perform any number of specialized operations, such as  
5799 - accessing external storage systems, creating bindings for qpdf in  
5800 - other programming languages that have their own I/O systems, etc.  
5801 -  
5802 - - Add new method ``QPDF::getEncryptionKey`` for retrieving the  
5803 - underlying encryption key used in the file.  
5804 -  
5805 - - This release includes a small handful of non-compatible API  
5806 - changes. While effort is made to avoid such changes, all the  
5807 - non-compatible API changes in this version were to parts of the  
5808 - API that would likely never be used outside the library itself. In  
5809 - all cases, the altered methods or structures were parts of the  
5810 - ``QPDF`` that were public to enable them to be called from either  
5811 - ``QPDFWriter`` or were part of validation code that was  
5812 - over-zealous in reporting problems in parts of the file that would  
5813 - not ordinarily be referenced. In no case did any of the removed  
5814 - methods do anything worse that falsely report error conditions in  
5815 - files that were broken in ways that didn't matter. The following  
5816 - public parts of the ``QPDF`` class were changed in a  
5817 - non-compatible way:  
5818 -  
5819 - - Updated nested ``QPDF::EncryptionData`` class to add fields  
5820 - needed by the newer encryption formats, member variables  
5821 - changed to private so that future changes will not require  
5822 - breaking backward compatibility.  
5823 -  
5824 - - Added additional parameters to ``compute_data_key``, which is  
5825 - used by ``QPDFWriter`` to compute the encryption key used to  
5826 - encrypt a specific object.  
5827 -  
5828 - - Removed the method ``flattenScalarReferences``. This method was  
5829 - previously used prior to writing a new PDF file, but it has the  
5830 - undesired side effect of causing qpdf to read objects in the  
5831 - file that were not referenced. Some otherwise files have  
5832 - unreferenced objects with errors in them, so this could cause  
5833 - qpdf to reject files that would be accepted by virtually all  
5834 - other PDF readers. In fact, qpdf relied on only a very small  
5835 - part of what flattenScalarReferences did, so only this part has  
5836 - been preserved, and it is now done directly inside  
5837 - ``QPDFWriter``.  
5838 -  
5839 - - Removed the method ``decodeStreams``. This method was used by  
5840 - the @1@option@1@--check@2@option@2@ option of the  
5841 - @1@command@1@qpdf@2@command@2@ command-line tool to force all  
5842 - streams in the file to be decoded, but it also suffered from  
5843 - the problem of opening otherwise unreferenced streams and thus  
5844 - could report false positive. The  
5845 - @1@option@1@--check@2@option@2@ option now causes qpdf to go  
5846 - through all the motions of writing a new file based on the  
5847 - original one, so it will always reference and check exactly  
5848 - those parts of a file that any ordinary viewer would check.  
5849 -  
5850 - - Removed the method ``trimTrailerForWrite``. This method was  
5851 - used by ``QPDFWriter`` to modify the original QPDF object by  
5852 - removing fields from the trailer dictionary that wouldn't apply  
5853 - to the newly written file. This functionality, though generally  
5854 - harmless, was a poor implementation and has been replaced by  
5855 - having QPDFWriter filter these out when copying the trailer  
5856 - rather than modifying the original QPDF object. (Note that qpdf  
5857 - never modifies the original file itself.)  
5858 -  
5859 - - Allow the PDF header to appear anywhere in the first 1024 bytes of  
5860 - the file. This is consistent with what other readers do.  
5861 -  
5862 - - Fix the @1@command@1@pkg-config@2@command@2@ files to list zlib  
5863 - and pcre in ``Requires.private`` to better support static linking  
5864 - using @1@command@1@pkg-config@2@command@2@. 5758 + - Major enhancement: support has been added for newer encryption
  5759 + schemes supported by version X of Adobe Acrobat. This includes use
  5760 + of 127-character passwords, 256-bit encryption keys, and the
  5761 + encryption scheme specified in ISO 32000-2, the PDF 2.0
  5762 + specification. This scheme can be chosen from the command line by
  5763 + specifying use of 256-bit keys. qpdf also supports the deprecated
  5764 + encryption method used by Acrobat IX. This encryption style has
  5765 + known security weaknesses and should not be used in practice.
  5766 + However, such files exist "in the wild," so support for this
  5767 + scheme is still useful. New methods
  5768 + ``QPDFWriter::setR6EncryptionParameters`` (for the PDF 2.0 scheme)
  5769 + and ``QPDFWriter::setR5EncryptionParameters`` (for the deprecated
  5770 + scheme) have been added to enable these new encryption schemes.
  5771 + Corresponding functions have been added to the C API as well.
  5772 +
  5773 + - Full support for Adobe extension levels in PDF version
  5774 + information. Starting with PDF version 1.7, corresponding to ISO
  5775 + 32000, Adobe adds new functionality by increasing the extension
  5776 + level rather than increasing the version. This support includes
  5777 + addition of the ``QPDF::getExtensionLevel`` method for retrieving
  5778 + the document's extension level, addition of versions of
  5779 + ``QPDFWriter::setMinimumPDFVersion`` and
  5780 + ``QPDFWriter::forcePDFVersion`` that accept an extension level,
  5781 + and extended syntax for specifying forced and minimum versions on
  5782 + the command line as described in `Advanced Transformation
  5783 + Options <#ref.advanced-transformation>`__. Corresponding functions
  5784 + have been added to the C API as well.
  5785 +
  5786 + - Minor fixes to prevent qpdf from referencing objects in the file
  5787 + that are not referenced in the file's overall structure. Most
  5788 + files don't have any such objects, but some files have contain
  5789 + unreferenced objects with errors, so these fixes prevent qpdf from
  5790 + needlessly rejecting or complaining about such objects.
  5791 +
  5792 + - Add new generalized methods for reading and writing files from/to
  5793 + programmer-defined sources. The method
  5794 + ``QPDF::processInputSource`` allows the programmer to use any
  5795 + input source for the input file, and
  5796 + ``QPDFWriter::setOutputPipeline`` allows the programmer to write
  5797 + the output file through any pipeline. These methods would make it
  5798 + possible to perform any number of specialized operations, such as
  5799 + accessing external storage systems, creating bindings for qpdf in
  5800 + other programming languages that have their own I/O systems, etc.
  5801 +
  5802 + - Add new method ``QPDF::getEncryptionKey`` for retrieving the
  5803 + underlying encryption key used in the file.
  5804 +
  5805 + - This release includes a small handful of non-compatible API
  5806 + changes. While effort is made to avoid such changes, all the
  5807 + non-compatible API changes in this version were to parts of the
  5808 + API that would likely never be used outside the library itself. In
  5809 + all cases, the altered methods or structures were parts of the
  5810 + ``QPDF`` that were public to enable them to be called from either
  5811 + ``QPDFWriter`` or were part of validation code that was
  5812 + over-zealous in reporting problems in parts of the file that would
  5813 + not ordinarily be referenced. In no case did any of the removed
  5814 + methods do anything worse that falsely report error conditions in
  5815 + files that were broken in ways that didn't matter. The following
  5816 + public parts of the ``QPDF`` class were changed in a
  5817 + non-compatible way:
  5818 +
  5819 + - Updated nested ``QPDF::EncryptionData`` class to add fields
  5820 + needed by the newer encryption formats, member variables
  5821 + changed to private so that future changes will not require
  5822 + breaking backward compatibility.
  5823 +
  5824 + - Added additional parameters to ``compute_data_key``, which is
  5825 + used by ``QPDFWriter`` to compute the encryption key used to
  5826 + encrypt a specific object.
  5827 +
  5828 + - Removed the method ``flattenScalarReferences``. This method was
  5829 + previously used prior to writing a new PDF file, but it has the
  5830 + undesired side effect of causing qpdf to read objects in the
  5831 + file that were not referenced. Some otherwise files have
  5832 + unreferenced objects with errors in them, so this could cause
  5833 + qpdf to reject files that would be accepted by virtually all
  5834 + other PDF readers. In fact, qpdf relied on only a very small
  5835 + part of what flattenScalarReferences did, so only this part has
  5836 + been preserved, and it is now done directly inside
  5837 + ``QPDFWriter``.
  5838 +
  5839 + - Removed the method ``decodeStreams``. This method was used by
  5840 + the @1@option@1@--check@2@option@2@ option of the
  5841 + @1@command@1@qpdf@2@command@2@ command-line tool to force all
  5842 + streams in the file to be decoded, but it also suffered from
  5843 + the problem of opening otherwise unreferenced streams and thus
  5844 + could report false positive. The
  5845 + @1@option@1@--check@2@option@2@ option now causes qpdf to go
  5846 + through all the motions of writing a new file based on the
  5847 + original one, so it will always reference and check exactly
  5848 + those parts of a file that any ordinary viewer would check.
  5849 +
  5850 + - Removed the method ``trimTrailerForWrite``. This method was
  5851 + used by ``QPDFWriter`` to modify the original QPDF object by
  5852 + removing fields from the trailer dictionary that wouldn't apply
  5853 + to the newly written file. This functionality, though generally
  5854 + harmless, was a poor implementation and has been replaced by
  5855 + having QPDFWriter filter these out when copying the trailer
  5856 + rather than modifying the original QPDF object. (Note that qpdf
  5857 + never modifies the original file itself.)
  5858 +
  5859 + - Allow the PDF header to appear anywhere in the first 1024 bytes of
  5860 + the file. This is consistent with what other readers do.
  5861 +
  5862 + - Fix the @1@command@1@pkg-config@2@command@2@ files to list zlib
  5863 + and pcre in ``Requires.private`` to better support static linking
  5864 + using @1@command@1@pkg-config@2@command@2@.
5865 5865
5866 3.0.2: September 6, 2012 5866 3.0.2: September 6, 2012
5867 - - Bug fix: ``QPDFWriter::setOutputMemory`` did not work when not  
5868 - used with ``QPDFWriter::setStaticID``, which made it pretty much  
5869 - useless. This has been fixed. 5867 + - Bug fix: ``QPDFWriter::setOutputMemory`` did not work when not
  5868 + used with ``QPDFWriter::setStaticID``, which made it pretty much
  5869 + useless. This has been fixed.
5870 5870
5871 - - New API call ``QPDFWriter::setExtraHeaderText`` inserts additional  
5872 - text near the header of the PDF file. The intended use case is to  
5873 - insert comments that may be consumed by a downstream application,  
5874 - though other use cases may exist. 5871 + - New API call ``QPDFWriter::setExtraHeaderText`` inserts additional
  5872 + text near the header of the PDF file. The intended use case is to
  5873 + insert comments that may be consumed by a downstream application,
  5874 + though other use cases may exist.
5875 5875
5876 3.0.1: August 11, 2012 5876 3.0.1: August 11, 2012
5877 - - Version 3.0.0 included addition of files for  
5878 - @1@command@1@pkg-config@2@command@2@, but this was not mentioned  
5879 - in the release notes. The release notes for 3.0.0 were updated to  
5880 - mention this. 5877 + - Version 3.0.0 included addition of files for
  5878 + @1@command@1@pkg-config@2@command@2@, but this was not mentioned
  5879 + in the release notes. The release notes for 3.0.0 were updated to
  5880 + mention this.
5881 5881
5882 - - Bug fix: if an object stream ended with a scalar object not  
5883 - followed by space, qpdf would incorrectly report that it  
5884 - encountered a premature EOF. This bug has been in qpdf since  
5885 - versionย 2.0. 5882 + - Bug fix: if an object stream ended with a scalar object not
  5883 + followed by space, qpdf would incorrectly report that it
  5884 + encountered a premature EOF. This bug has been in qpdf since
  5885 + versionย 2.0.
5886 5886
5887 3.0.0: August 2, 2012 5887 3.0.0: August 2, 2012
5888 - - Acknowledgment: I would like to express gratitude for the  
5889 - contributions of Tobias Hoffmann toward the release of qpdf  
5890 - version 3.0. He is responsible for most of the implementation and  
5891 - design of the new API for manipulating pages, and contributed code  
5892 - and ideas for many of the improvements made in version 3.0.  
5893 - Without his work, this release would certainly not have happened  
5894 - as soon as it did, if at all.  
5895 -  
5896 - - *Non-compatible API change:* The version of  
5897 - ``QPDFObjectHandle::replaceStreamData`` that uses a  
5898 - ``StreamDataProvider`` no longer requires (or accepts) a  
5899 - ``length`` parameter. See  
5900 - `appendix_title <#ref.upgrading-to-3.0>`__ for an explanation.  
5901 - While care is taken to avoid non-compatible API changes in  
5902 - general, an exception was made this time because the new interface  
5903 - offers an opportunity to significantly simplify calling code.  
5904 -  
5905 - - Support has been added for large files. The test suite verifies  
5906 - support for files larger than 4 gigabytes, and manual testing has  
5907 - verified support for files larger than 10 gigabytes. Large file  
5908 - support is available for both 32-bit and 64-bit platforms as long  
5909 - as the compiler and underlying platforms support it.  
5910 -  
5911 - - Support for page selection (splitting and merging PDF files) has  
5912 - been added to the @1@command@1@qpdf@2@command@2@ command-line  
5913 - tool. See `Page Selection Options <#ref.page-selection>`__.  
5914 -  
5915 - - Options have been added to the @1@command@1@qpdf@2@command@2@  
5916 - command-line tool for copying encryption parameters from another  
5917 - file. See `Basic Options <#ref.basic-options>`__.  
5918 -  
5919 - - New methods have been added to the ``QPDF`` object for adding and  
5920 - removing pages. See `Adding and Removing  
5921 - Pages <#ref.adding-and-remove-pages>`__.  
5922 -  
5923 - - New methods have been added to the ``QPDF`` object for copying  
5924 - objects from other PDF files. See `Copying Objects From Other PDF  
5925 - Files <#ref.foreign-objects>`__  
5926 -  
5927 - - A new method ``QPDFObjectHandle::parse`` has been added for  
5928 - constructing ``QPDFObjectHandle`` objects from a string  
5929 - description.  
5930 -  
5931 - - Methods have been added to ``QPDFWriter`` to allow writing to an  
5932 - already open stdio ``FILE*`` addition to writing to standard  
5933 - output or a named file. Methods have been added to ``QPDF`` to be  
5934 - able to process a file from an already open stdio ``FILE*``. This  
5935 - makes it possible to read and write PDF from secure temporary  
5936 - files that have been unlinked prior to being fully read or  
5937 - written.  
5938 -  
5939 - - The ``QPDF::emptyPDF`` can be used to allow creation of PDF files  
5940 - from scratch. The example  
5941 - @1@filename@1@examples/pdf-create.cc@2@filename@2@ illustrates how  
5942 - it can be used.  
5943 -  
5944 - - Several methods to take ``PointerHolder<Buffer>`` can now also  
5945 - accept ``std::string`` arguments.  
5946 -  
5947 - - Many new convenience methods have been added to the library, most  
5948 - in ``QPDFObjectHandle``. See @1@filename@1@ChangeLog@2@filename@2@  
5949 - for a full list.  
5950 -  
5951 - - When building on a platform that supports ELF shared libraries  
5952 - (such as Linux), symbol versions are enabled by default. They can  
5953 - be disabled by passing  
5954 - @1@option@1@--disable-ld-version-script@2@option@2@ to  
5955 - @1@command@1@./configure@2@command@2@.  
5956 -  
5957 - - The file @1@filename@1@libqpdf.pc@2@filename@2@ is now installed  
5958 - to support @1@command@1@pkg-config@2@command@2@.  
5959 -  
5960 - - Image comparison tests are off by default now since they are not  
5961 - needed to verify a correct build or port of qpdf. They are needed  
5962 - only when changing the actual PDF output generated by qpdf. You  
5963 - should enable them if you are making deep changes to qpdf itself.  
5964 - See @1@filename@1@README.md@2@filename@2@ for details.  
5965 -  
5966 - - Large file tests are off by default but can be turned on with  
5967 - @1@command@1@./configure@2@command@2@ or by setting an environment  
5968 - variable before running the test suite. See  
5969 - @1@filename@1@README.md@2@filename@2@ for details.  
5970 -  
5971 - - When qpdf's test suite fails, failures are not printed to the  
5972 - terminal anymore by default. Instead, find them in  
5973 - @1@filename@1@build/qtest.log@2@filename@2@. For packagers who are  
5974 - building with an autobuilder, you can add the  
5975 - @1@option@1@--enable-show-failed-test-output@2@option@2@ option to  
5976 - @1@command@1@./configure@2@command@2@ to restore the old behavior. 5888 + - Acknowledgment: I would like to express gratitude for the
  5889 + contributions of Tobias Hoffmann toward the release of qpdf
  5890 + version 3.0. He is responsible for most of the implementation and
  5891 + design of the new API for manipulating pages, and contributed code
  5892 + and ideas for many of the improvements made in version 3.0.
  5893 + Without his work, this release would certainly not have happened
  5894 + as soon as it did, if at all.
  5895 +
  5896 + - *Non-compatible API change:* The version of
  5897 + ``QPDFObjectHandle::replaceStreamData`` that uses a
  5898 + ``StreamDataProvider`` no longer requires (or accepts) a
  5899 + ``length`` parameter. See
  5900 + `appendix_title <#ref.upgrading-to-3.0>`__ for an explanation.
  5901 + While care is taken to avoid non-compatible API changes in
  5902 + general, an exception was made this time because the new interface
  5903 + offers an opportunity to significantly simplify calling code.
  5904 +
  5905 + - Support has been added for large files. The test suite verifies
  5906 + support for files larger than 4 gigabytes, and manual testing has
  5907 + verified support for files larger than 10 gigabytes. Large file
  5908 + support is available for both 32-bit and 64-bit platforms as long
  5909 + as the compiler and underlying platforms support it.
  5910 +
  5911 + - Support for page selection (splitting and merging PDF files) has
  5912 + been added to the @1@command@1@qpdf@2@command@2@ command-line
  5913 + tool. See `Page Selection Options <#ref.page-selection>`__.
  5914 +
  5915 + - Options have been added to the @1@command@1@qpdf@2@command@2@
  5916 + command-line tool for copying encryption parameters from another
  5917 + file. See `Basic Options <#ref.basic-options>`__.
  5918 +
  5919 + - New methods have been added to the ``QPDF`` object for adding and
  5920 + removing pages. See `Adding and Removing
  5921 + Pages <#ref.adding-and-remove-pages>`__.
  5922 +
  5923 + - New methods have been added to the ``QPDF`` object for copying
  5924 + objects from other PDF files. See `Copying Objects From Other PDF
  5925 + Files <#ref.foreign-objects>`__
  5926 +
  5927 + - A new method ``QPDFObjectHandle::parse`` has been added for
  5928 + constructing ``QPDFObjectHandle`` objects from a string
  5929 + description.
  5930 +
  5931 + - Methods have been added to ``QPDFWriter`` to allow writing to an
  5932 + already open stdio ``FILE*`` addition to writing to standard
  5933 + output or a named file. Methods have been added to ``QPDF`` to be
  5934 + able to process a file from an already open stdio ``FILE*``. This
  5935 + makes it possible to read and write PDF from secure temporary
  5936 + files that have been unlinked prior to being fully read or
  5937 + written.
  5938 +
  5939 + - The ``QPDF::emptyPDF`` can be used to allow creation of PDF files
  5940 + from scratch. The example
  5941 + @1@filename@1@examples/pdf-create.cc@2@filename@2@ illustrates how
  5942 + it can be used.
  5943 +
  5944 + - Several methods to take ``PointerHolder<Buffer>`` can now also
  5945 + accept ``std::string`` arguments.
  5946 +
  5947 + - Many new convenience methods have been added to the library, most
  5948 + in ``QPDFObjectHandle``. See @1@filename@1@ChangeLog@2@filename@2@
  5949 + for a full list.
  5950 +
  5951 + - When building on a platform that supports ELF shared libraries
  5952 + (such as Linux), symbol versions are enabled by default. They can
  5953 + be disabled by passing
  5954 + @1@option@1@--disable-ld-version-script@2@option@2@ to
  5955 + @1@command@1@./configure@2@command@2@.
  5956 +
  5957 + - The file @1@filename@1@libqpdf.pc@2@filename@2@ is now installed
  5958 + to support @1@command@1@pkg-config@2@command@2@.
  5959 +
  5960 + - Image comparison tests are off by default now since they are not
  5961 + needed to verify a correct build or port of qpdf. They are needed
  5962 + only when changing the actual PDF output generated by qpdf. You
  5963 + should enable them if you are making deep changes to qpdf itself.
  5964 + See @1@filename@1@README.md@2@filename@2@ for details.
  5965 +
  5966 + - Large file tests are off by default but can be turned on with
  5967 + @1@command@1@./configure@2@command@2@ or by setting an environment
  5968 + variable before running the test suite. See
  5969 + @1@filename@1@README.md@2@filename@2@ for details.
  5970 +
  5971 + - When qpdf's test suite fails, failures are not printed to the
  5972 + terminal anymore by default. Instead, find them in
  5973 + @1@filename@1@build/qtest.log@2@filename@2@. For packagers who are
  5974 + building with an autobuilder, you can add the
  5975 + @1@option@1@--enable-show-failed-test-output@2@option@2@ option to
  5976 + @1@command@1@./configure@2@command@2@ to restore the old behavior.
5977 5977
5978 2.3.1: December 28, 2011 5978 2.3.1: December 28, 2011
5979 - - Fix thread-safety problem resulting from non-thread-safe use of  
5980 - the PCRE library. 5979 + - Fix thread-safety problem resulting from non-thread-safe use of
  5980 + the PCRE library.
5981 5981
5982 - - Made a few minor documentation fixes. 5982 + - Made a few minor documentation fixes.
5983 5983
5984 - - Add workaround for a bug that appears in some versions of  
5985 - ghostscript to the test suite 5984 + - Add workaround for a bug that appears in some versions of
  5985 + ghostscript to the test suite
5986 5986
5987 - - Fix minor build issue for Visual C++ 2010. 5987 + - Fix minor build issue for Visual C++ 2010.
5988 5988
5989 2.3.0: August 11, 2011 5989 2.3.0: August 11, 2011
5990 - - Bug fix: when preserving existing encryption on encrypted files  
5991 - with cleartext metadata, older qpdf versions would generate  
5992 - password-protected files with no valid password. This operation  
5993 - now works. This bug only affected files created by copying  
5994 - existing encryption parameters; explicit encryption with  
5995 - specification of cleartext metadata worked before and continues to  
5996 - work.  
5997 -  
5998 - - Enhance ``QPDFWriter`` with a new constructor that allows you to  
5999 - delay the specification of the output file. When using this  
6000 - constructor, you may now call ``QPDFWriter::setOutputFilename`` to  
6001 - specify the output file, or you may use  
6002 - ``QPDFWriter::setOutputMemory`` to cause ``QPDFWriter`` to write  
6003 - the resulting PDF file to a memory buffer. You may then use  
6004 - ``QPDFWriter::getBuffer`` to retrieve the memory buffer.  
6005 -  
6006 - - Add new API call ``QPDF::replaceObject`` for replacing objects by  
6007 - object ID  
6008 -  
6009 - - Add new API call ``QPDF::swapObjects`` for swapping two objects by  
6010 - object ID  
6011 -  
6012 - - Add ``QPDFObjectHandle::getDictAsMap`` and  
6013 - ``QPDFObjectHandle::getArrayAsVector`` to allow retrieval of  
6014 - dictionary objects as maps and array objects as vectors.  
6015 -  
6016 - - Add functions ``qpdf_get_info_key`` and ``qpdf_set_info_key`` to  
6017 - the C API for manipulating string fields of the document's  
6018 - ``/Info`` dictionary.  
6019 -  
6020 - - Add functions ``qpdf_init_write_memory``,  
6021 - ``qpdf_get_buffer_length``, and ``qpdf_get_buffer`` to the C API  
6022 - for writing PDF files to a memory buffer instead of a file. 5990 + - Bug fix: when preserving existing encryption on encrypted files
  5991 + with cleartext metadata, older qpdf versions would generate
  5992 + password-protected files with no valid password. This operation
  5993 + now works. This bug only affected files created by copying
  5994 + existing encryption parameters; explicit encryption with
  5995 + specification of cleartext metadata worked before and continues to
  5996 + work.
  5997 +
  5998 + - Enhance ``QPDFWriter`` with a new constructor that allows you to
  5999 + delay the specification of the output file. When using this
  6000 + constructor, you may now call ``QPDFWriter::setOutputFilename`` to
  6001 + specify the output file, or you may use
  6002 + ``QPDFWriter::setOutputMemory`` to cause ``QPDFWriter`` to write
  6003 + the resulting PDF file to a memory buffer. You may then use
  6004 + ``QPDFWriter::getBuffer`` to retrieve the memory buffer.
  6005 +
  6006 + - Add new API call ``QPDF::replaceObject`` for replacing objects by
  6007 + object ID
  6008 +
  6009 + - Add new API call ``QPDF::swapObjects`` for swapping two objects by
  6010 + object ID
  6011 +
  6012 + - Add ``QPDFObjectHandle::getDictAsMap`` and
  6013 + ``QPDFObjectHandle::getArrayAsVector`` to allow retrieval of
  6014 + dictionary objects as maps and array objects as vectors.
  6015 +
  6016 + - Add functions ``qpdf_get_info_key`` and ``qpdf_set_info_key`` to
  6017 + the C API for manipulating string fields of the document's
  6018 + ``/Info`` dictionary.
  6019 +
  6020 + - Add functions ``qpdf_init_write_memory``,
  6021 + ``qpdf_get_buffer_length``, and ``qpdf_get_buffer`` to the C API
  6022 + for writing PDF files to a memory buffer instead of a file.
6023 6023
6024 2.2.4: June 25, 2011 6024 2.2.4: June 25, 2011
6025 - - Fix installation and compilation issues; no functionality changes. 6025 + - Fix installation and compilation issues; no functionality changes.
6026 6026
6027 2.2.3: April 30, 2011 6027 2.2.3: April 30, 2011
6028 - - Handle some damaged streams with incorrect characters following  
6029 - the stream keyword. 6028 + - Handle some damaged streams with incorrect characters following
  6029 + the stream keyword.
6030 6030
6031 - - Improve handling of inline images when normalizing content  
6032 - streams. 6031 + - Improve handling of inline images when normalizing content
  6032 + streams.
6033 6033
6034 - - Enhance error recovery to properly handle files that use object 0  
6035 - as a regular object, which is specifically disallowed by the spec. 6034 + - Enhance error recovery to properly handle files that use object 0
  6035 + as a regular object, which is specifically disallowed by the spec.
6036 6036
6037 2.2.2: October 4, 2010 6037 2.2.2: October 4, 2010
6038 - - Add new function ``qpdf_read_memory`` to the C API to call  
6039 - ``QPDF::processMemoryFile``. This was an omission in qpdf 2.2.1. 6038 + - Add new function ``qpdf_read_memory`` to the C API to call
  6039 + ``QPDF::processMemoryFile``. This was an omission in qpdf 2.2.1.
6040 6040
6041 2.2.1: October 1, 2010 6041 2.2.1: October 1, 2010
6042 - - Add new method ``QPDF::setOutputStreams`` to replace ``std::cout``  
6043 - and ``std::cerr`` with other streams for generation of diagnostic  
6044 - messages and error messages. This can be useful for GUIs or other  
6045 - applications that want to capture any output generated by the  
6046 - library to present to the user in some other way. Note that QPDF  
6047 - does not write to ``std::cout`` (or the specified output stream)  
6048 - except where explicitly mentioned in  
6049 - @1@filename@1@QPDF.hh@2@filename@2@, and that the only use of the  
6050 - error stream is for warnings. Note also that output of warnings is  
6051 - suppressed when ``setSuppressWarnings(true)`` is called.  
6052 -  
6053 - - Add new method ``QPDF::processMemoryFile`` for operating on PDF  
6054 - files that are loaded into memory rather than in a file on disk.  
6055 -  
6056 - - Give a warning but otherwise ignore empty PDF objects by treating  
6057 - them as null. Empty object are not permitted by the PDF  
6058 - specification but have been known to appear in some actual PDF  
6059 - files.  
6060 -  
6061 - - Handle inline image filter abbreviations when the appear as stream  
6062 - filter abbreviations. The PDF specification does not allow use of  
6063 - stream filter abbreviations in this way, but Adobe Reader and some  
6064 - other PDF readers accept them since they sometimes appear  
6065 - incorrectly in actual PDF files.  
6066 -  
6067 - - Implement miscellaneous enhancements to ``PointerHolder`` and  
6068 - ``Buffer`` to support other changes. 6042 + - Add new method ``QPDF::setOutputStreams`` to replace ``std::cout``
  6043 + and ``std::cerr`` with other streams for generation of diagnostic
  6044 + messages and error messages. This can be useful for GUIs or other
  6045 + applications that want to capture any output generated by the
  6046 + library to present to the user in some other way. Note that QPDF
  6047 + does not write to ``std::cout`` (or the specified output stream)
  6048 + except where explicitly mentioned in
  6049 + @1@filename@1@QPDF.hh@2@filename@2@, and that the only use of the
  6050 + error stream is for warnings. Note also that output of warnings is
  6051 + suppressed when ``setSuppressWarnings(true)`` is called.
  6052 +
  6053 + - Add new method ``QPDF::processMemoryFile`` for operating on PDF
  6054 + files that are loaded into memory rather than in a file on disk.
  6055 +
  6056 + - Give a warning but otherwise ignore empty PDF objects by treating
  6057 + them as null. Empty object are not permitted by the PDF
  6058 + specification but have been known to appear in some actual PDF
  6059 + files.
  6060 +
  6061 + - Handle inline image filter abbreviations when the appear as stream
  6062 + filter abbreviations. The PDF specification does not allow use of
  6063 + stream filter abbreviations in this way, but Adobe Reader and some
  6064 + other PDF readers accept them since they sometimes appear
  6065 + incorrectly in actual PDF files.
  6066 +
  6067 + - Implement miscellaneous enhancements to ``PointerHolder`` and
  6068 + ``Buffer`` to support other changes.
6069 6069
6070 2.2.0: August 14, 2010 6070 2.2.0: August 14, 2010
6071 - - Add new methods to ``QPDFObjectHandle`` (``newStream`` and  
6072 - ``replaceStreamData`` for creating new streams and replacing  
6073 - stream data. This makes it possible to perform a wide range of  
6074 - operations that were not previously possible.  
6075 -  
6076 - - Add new helper method in ``QPDFObjectHandle``  
6077 - (``addPageContents``) for appending or prepending new content  
6078 - streams to a page. This method makes it possible to manipulate  
6079 - content streams without having to be concerned whether a page's  
6080 - contents are a single stream or an array of streams.  
6081 -  
6082 - - Add new method in ``QPDFObjectHandle``: ``replaceOrRemoveKey``,  
6083 - which replaces a dictionary key with a given value unless the  
6084 - value is null, in which case it removes the key instead.  
6085 -  
6086 - - Add new method in ``QPDFObjectHandle``: ``getRawStreamData``,  
6087 - which returns the raw (unfiltered) stream data into a buffer. This  
6088 - complements the ``getStreamData`` method, which returns the  
6089 - filtered (uncompressed) stream data and can only be used when the  
6090 - stream's data is filterable.  
6091 -  
6092 - - Provide two new examples:  
6093 - @1@command@1@pdf-double-page-size@2@command@2@ and  
6094 - @1@command@1@pdf-invert-images@2@command@2@ that illustrate the  
6095 - newly added interfaces.  
6096 -  
6097 - - Fix a memory leak that would cause loss of a few bytes for every  
6098 - object involved in a cycle of object references. Thanks to Jian Ma  
6099 - for calling my attention to the leak. 6071 + - Add new methods to ``QPDFObjectHandle`` (``newStream`` and
  6072 + ``replaceStreamData`` for creating new streams and replacing
  6073 + stream data. This makes it possible to perform a wide range of
  6074 + operations that were not previously possible.
  6075 +
  6076 + - Add new helper method in ``QPDFObjectHandle``
  6077 + (``addPageContents``) for appending or prepending new content
  6078 + streams to a page. This method makes it possible to manipulate
  6079 + content streams without having to be concerned whether a page's
  6080 + contents are a single stream or an array of streams.
  6081 +
  6082 + - Add new method in ``QPDFObjectHandle``: ``replaceOrRemoveKey``,
  6083 + which replaces a dictionary key with a given value unless the
  6084 + value is null, in which case it removes the key instead.
  6085 +
  6086 + - Add new method in ``QPDFObjectHandle``: ``getRawStreamData``,
  6087 + which returns the raw (unfiltered) stream data into a buffer. This
  6088 + complements the ``getStreamData`` method, which returns the
  6089 + filtered (uncompressed) stream data and can only be used when the
  6090 + stream's data is filterable.
  6091 +
  6092 + - Provide two new examples:
  6093 + @1@command@1@pdf-double-page-size@2@command@2@ and
  6094 + @1@command@1@pdf-invert-images@2@command@2@ that illustrate the
  6095 + newly added interfaces.
  6096 +
  6097 + - Fix a memory leak that would cause loss of a few bytes for every
  6098 + object involved in a cycle of object references. Thanks to Jian Ma
  6099 + for calling my attention to the leak.
6100 6100
6101 2.1.5: April 25, 2010 6101 2.1.5: April 25, 2010
6102 - - Remove restriction of file identifier strings to 16 bytes. This  
6103 - unnecessary restriction was preventing qpdf from being able to  
6104 - encrypt or decrypt files with identifier strings that were not  
6105 - exactly 16 bytes long. The specification imposes no such  
6106 - restriction. 6102 + - Remove restriction of file identifier strings to 16 bytes. This
  6103 + unnecessary restriction was preventing qpdf from being able to
  6104 + encrypt or decrypt files with identifier strings that were not
  6105 + exactly 16 bytes long. The specification imposes no such
  6106 + restriction.
6107 6107
6108 2.1.4: April 18, 2010 6108 2.1.4: April 18, 2010
6109 - - Apply the same padding calculation fix from version 2.1.2 to the  
6110 - main cross reference stream as well. 6109 + - Apply the same padding calculation fix from version 2.1.2 to the
  6110 + main cross reference stream as well.
6111 6111
6112 - - Since @1@command@1@qpdf --check@2@command@2@ only performs limited  
6113 - checks, clarify the output to make it clear that there still may  
6114 - be errors that qpdf can't check. This should make it less  
6115 - surprising to people when another PDF reader is unable to read a  
6116 - file that qpdf thinks is okay. 6112 + - Since @1@command@1@qpdf --check@2@command@2@ only performs limited
  6113 + checks, clarify the output to make it clear that there still may
  6114 + be errors that qpdf can't check. This should make it less
  6115 + surprising to people when another PDF reader is unable to read a
  6116 + file that qpdf thinks is okay.
6117 6117
6118 2.1.3: March 27, 2010 6118 2.1.3: March 27, 2010
6119 - - Fix bug that could cause a failure when rewriting PDF files that  
6120 - contain object streams with unreferenced objects that in turn  
6121 - reference indirect scalars. 6119 + - Fix bug that could cause a failure when rewriting PDF files that
  6120 + contain object streams with unreferenced objects that in turn
  6121 + reference indirect scalars.
6122 6122
6123 - - Don't complain about (invalid) AES streams that aren't a multiple  
6124 - of 16 bytes. Instead, pad them before decrypting. 6123 + - Don't complain about (invalid) AES streams that aren't a multiple
  6124 + of 16 bytes. Instead, pad them before decrypting.
6125 6125
6126 2.1.2: January 24, 2010 6126 2.1.2: January 24, 2010
6127 - - Fix bug in padding around first half cross reference stream in  
6128 - linearized files. The bug could cause an assertion failure when  
6129 - linearizing certain unlucky files. 6127 + - Fix bug in padding around first half cross reference stream in
  6128 + linearized files. The bug could cause an assertion failure when
  6129 + linearizing certain unlucky files.
6130 6130
6131 2.1.1: December 14, 2009 6131 2.1.1: December 14, 2009
6132 - - No changes in functionality; insert missing include in an internal  
6133 - library header file to support gcc 4.4, and update test suite to  
6134 - ignore broken Adobe Reader installations. 6132 + - No changes in functionality; insert missing include in an internal
  6133 + library header file to support gcc 4.4, and update test suite to
  6134 + ignore broken Adobe Reader installations.
6135 6135
6136 2.1: October 30, 2009 6136 2.1: October 30, 2009
6137 - - This is the first version of qpdf to include Windows support. On  
6138 - Windows, it is possible to build a DLL. Additionally, a partial  
6139 - C-language API has been introduced, which makes it possible to  
6140 - call qpdf functions from non-C++ environments. I am very grateful  
6141 - to ลฝarko Gajiฤ‡ (http://zarko-gajic.iz.hr/) for tirelessly testing  
6142 - numerous pre-release versions of this DLL and providing many  
6143 - excellent suggestions on improving the interface.  
6144 -  
6145 - For programming to the C interface, please see the header file  
6146 - @1@filename@1@qpdf/qpdf-c.h@2@filename@2@ and the example  
6147 - @1@filename@1@examples/pdf-linearize.c@2@filename@2@.  
6148 -  
6149 - - ลฝarko Gajiฤ‡ has written a Delphi wrapper for qpdf, which can be  
6150 - downloaded from qpdf's download side. ลฝarko's Delphi wrapper is  
6151 - released with the same licensing terms as qpdf itself and comes  
6152 - with this disclaimer: "Delphi wrapper unit  
6153 - @1@filename@1@qpdf.pas@2@filename@2@ created by ลฝarko Gajiฤ‡  
6154 - (http://zarko-gajic.iz.hr/). Use at your own risk and for whatever  
6155 - purpose you want. No support is provided. Sample code is  
6156 - provided."  
6157 -  
6158 - - Support has been added for AES encryption and crypt filters.  
6159 - Although qpdf does not presently support files that use PKI-based  
6160 - encryption, with the addition of AES and crypt filters, qpdf is  
6161 - now be able to open most encrypted files created with newer  
6162 - versions of Acrobat or other PDF creation software. Note that I  
6163 - have not been able to get very many files encrypted in this way,  
6164 - so it's possible there could still be some cases that qpdf can't  
6165 - handle. Please report them if you find them.  
6166 -  
6167 - - Many error messages have been improved to include more information  
6168 - in hopes of making qpdf a more useful tool for PDF experts to use  
6169 - in manually recovering damaged PDF files.  
6170 -  
6171 - - Attempt to avoid compressing metadata streams if possible. This is  
6172 - consistent with other PDF creation applications.  
6173 -  
6174 - - Provide new command-line options for AES encrypt, cleartext  
6175 - metadata, and setting the minimum and forced PDF versions of  
6176 - output files.  
6177 -  
6178 - - Add additional methods to the ``QPDF`` object for querying the  
6179 - document's permissions. Although qpdf does not enforce these  
6180 - permissions, it does make them available so that applications that  
6181 - use qpdf can enforce permissions.  
6182 -  
6183 - - The @1@option@1@--check@2@option@2@ option to  
6184 - @1@command@1@qpdf@2@command@2@ has been extended to include some  
6185 - additional information.  
6186 -  
6187 - - There have been a handful of non-compatible API changes. For  
6188 - details, see `appendix_title <#ref.upgrading-to-2.1>`__. 6137 + - This is the first version of qpdf to include Windows support. On
  6138 + Windows, it is possible to build a DLL. Additionally, a partial
  6139 + C-language API has been introduced, which makes it possible to
  6140 + call qpdf functions from non-C++ environments. I am very grateful
  6141 + to ลฝarko Gajiฤ‡ (http://zarko-gajic.iz.hr/) for tirelessly testing
  6142 + numerous pre-release versions of this DLL and providing many
  6143 + excellent suggestions on improving the interface.
  6144 +
  6145 + For programming to the C interface, please see the header file
  6146 + @1@filename@1@qpdf/qpdf-c.h@2@filename@2@ and the example
  6147 + @1@filename@1@examples/pdf-linearize.c@2@filename@2@.
  6148 +
  6149 + - ลฝarko Gajiฤ‡ has written a Delphi wrapper for qpdf, which can be
  6150 + downloaded from qpdf's download side. ลฝarko's Delphi wrapper is
  6151 + released with the same licensing terms as qpdf itself and comes
  6152 + with this disclaimer: "Delphi wrapper unit
  6153 + @1@filename@1@qpdf.pas@2@filename@2@ created by ลฝarko Gajiฤ‡
  6154 + (http://zarko-gajic.iz.hr/). Use at your own risk and for whatever
  6155 + purpose you want. No support is provided. Sample code is
  6156 + provided."
  6157 +
  6158 + - Support has been added for AES encryption and crypt filters.
  6159 + Although qpdf does not presently support files that use PKI-based
  6160 + encryption, with the addition of AES and crypt filters, qpdf is
  6161 + now be able to open most encrypted files created with newer
  6162 + versions of Acrobat or other PDF creation software. Note that I
  6163 + have not been able to get very many files encrypted in this way,
  6164 + so it's possible there could still be some cases that qpdf can't
  6165 + handle. Please report them if you find them.
  6166 +
  6167 + - Many error messages have been improved to include more information
  6168 + in hopes of making qpdf a more useful tool for PDF experts to use
  6169 + in manually recovering damaged PDF files.
  6170 +
  6171 + - Attempt to avoid compressing metadata streams if possible. This is
  6172 + consistent with other PDF creation applications.
  6173 +
  6174 + - Provide new command-line options for AES encrypt, cleartext
  6175 + metadata, and setting the minimum and forced PDF versions of
  6176 + output files.
  6177 +
  6178 + - Add additional methods to the ``QPDF`` object for querying the
  6179 + document's permissions. Although qpdf does not enforce these
  6180 + permissions, it does make them available so that applications that
  6181 + use qpdf can enforce permissions.
  6182 +
  6183 + - The @1@option@1@--check@2@option@2@ option to
  6184 + @1@command@1@qpdf@2@command@2@ has been extended to include some
  6185 + additional information.
  6186 +
  6187 + - There have been a handful of non-compatible API changes. For
  6188 + details, see `appendix_title <#ref.upgrading-to-2.1>`__.
6189 6189
6190 2.0.6: May 3, 2009 6190 2.0.6: May 3, 2009
6191 - - Do not attempt to uncompress streams that have decode parameters  
6192 - we don't recognize. Earlier versions of qpdf would have rejected  
6193 - files with such streams. 6191 + - Do not attempt to uncompress streams that have decode parameters
  6192 + we don't recognize. Earlier versions of qpdf would have rejected
  6193 + files with such streams.
6194 6194
6195 2.0.5: March 10, 2009 6195 2.0.5: March 10, 2009
6196 - - Improve error handling in the LZW decoder, and fix a small error  
6197 - introduced in the previous version with regard to handling full  
6198 - tables. The LZW decoder has been more strongly verified in this  
6199 - release. 6196 + - Improve error handling in the LZW decoder, and fix a small error
  6197 + introduced in the previous version with regard to handling full
  6198 + tables. The LZW decoder has been more strongly verified in this
  6199 + release.
6200 6200
6201 2.0.4: February 21, 2009 6201 2.0.4: February 21, 2009
6202 - - Include proper support for LZW streams encoded without the "early  
6203 - code change" flag. Special thanks to Atom Smasher who reported the  
6204 - problem and provided an input file compressed in this way, which I  
6205 - did not previously have. 6202 + - Include proper support for LZW streams encoded without the "early
  6203 + code change" flag. Special thanks to Atom Smasher who reported the
  6204 + problem and provided an input file compressed in this way, which I
  6205 + did not previously have.
6206 6206
6207 - - Implement some improvements to file recovery logic. 6207 + - Implement some improvements to file recovery logic.
6208 6208
6209 2.0.3: February 15, 2009 6209 2.0.3: February 15, 2009
6210 - - Compile cleanly with gcc 4.4. 6210 + - Compile cleanly with gcc 4.4.
6211 6211
6212 - - Handle strings encoded as UTF-16BE properly. 6212 + - Handle strings encoded as UTF-16BE properly.
6213 6213
6214 2.0.2: June 30, 2008 6214 2.0.2: June 30, 2008
6215 - - Update test suite to work properly with a  
6216 - non-@1@command@1@bash@2@command@2@  
6217 - @1@filename@1@/bin/sh@2@filename@2@ and with Perl 5.10. No changes  
6218 - were made to the actual qpdf source code itself for this release. 6215 + - Update test suite to work properly with a
  6216 + non-@1@command@1@bash@2@command@2@
  6217 + @1@filename@1@/bin/sh@2@filename@2@ and with Perl 5.10. No changes
  6218 + were made to the actual qpdf source code itself for this release.
6219 6219
6220 2.0.1: May 6, 2008 6220 2.0.1: May 6, 2008
6221 - - No changes in functionality or interface. This release includes  
6222 - fixes to the source code so that qpdf compiles properly and passes  
6223 - its test suite on a broader range of platforms. See  
6224 - @1@filename@1@ChangeLog@2@filename@2@ in the source distribution  
6225 - for details. 6221 + - No changes in functionality or interface. This release includes
  6222 + fixes to the source code so that qpdf compiles properly and passes
  6223 + its test suite on a broader range of platforms. See
  6224 + @1@filename@1@ChangeLog@2@filename@2@ in the source distribution
  6225 + for details.
6226 6226
6227 2.0: April 29, 2008 6227 2.0: April 29, 2008
6228 - - First public release. 6228 + - First public release.
6229 6229
6230 .. _ref.upgrading-to-2.1: 6230 .. _ref.upgrading-to-2.1:
6231 6231
@@ -6240,46 +6240,46 @@ you may have to update your code. The changes are enumerated here. There @@ -6240,46 +6240,46 @@ you may have to update your code. The changes are enumerated here. There
6240 are also some new interfaces; for those, please refer to the header 6240 are also some new interfaces; for those, please refer to the header
6241 files. 6241 files.
6242 6242
6243 -- QPDF's exception handling mechanism now uses ``std::logic_error`` for  
6244 - internal errors and ``std::runtime_error`` for runtime errors in  
6245 - favor of the now removed ``QEXC`` classes used in previous versions.  
6246 - The ``QEXC`` exception classes predated the addition of the  
6247 - @1@filename@1@<stdexcept>@2@filename@2@ header file to the C++  
6248 - standard library. Most of the exceptions thrown by the qpdf library  
6249 - itself are still of type ``QPDFExc`` which is now derived from  
6250 - ``std::runtime_error``. Programs that caught an instance of  
6251 - ``std::exception`` and displayed it by calling the ``what()`` method  
6252 - will not need to be changed.  
6253 -  
6254 -- The ``QPDFExc`` class now internally represents various fields of the  
6255 - error condition and provides interfaces for querying them. Among the  
6256 - fields is a numeric error code that can help applications act  
6257 - differently on (a small number of) different error conditions. See  
6258 - @1@filename@1@QPDFExc.hh@2@filename@2@ for details.  
6259 -  
6260 -- Warnings can be retrieved from qpdf as instances of ``QPDFExc``  
6261 - instead of strings.  
6262 -  
6263 -- The nested ``QPDF::EncryptionData`` class's constructor takes an  
6264 - additional argument. This class is primarily intended to be used by  
6265 - ``QPDFWriter``. There's not really anything useful an end-user  
6266 - application could do with it. It probably shouldn't really be part of  
6267 - the public interface to begin with. Likewise, some of the methods for  
6268 - computing internal encryption dictionary parameters have changed to  
6269 - support ``/R=4`` encryption.  
6270 -  
6271 -- The method ``QPDF::getUserPassword`` has been removed since it didn't  
6272 - do what people would think it did. There are now two new methods:  
6273 - ``QPDF::getPaddedUserPassword`` and ``QPDF::getTrimmedUserPassword``.  
6274 - The first one does what the old ``QPDF::getUserPassword`` method used  
6275 - to do, which is to return the password with possible binary padding  
6276 - as specified by the PDF specification. The second one returns a  
6277 - human-readable password string.  
6278 -  
6279 -- The enumerated types that used to be nested in ``QPDFWriter`` have  
6280 - moved to top-level enumerated types and are now defined in the file  
6281 - @1@filename@1@qpdf/Constants.h@2@filename@2@. This enables them to be  
6282 - shared by both the C and C++ interfaces. 6243 +- QPDF's exception handling mechanism now uses ``std::logic_error`` for
  6244 + internal errors and ``std::runtime_error`` for runtime errors in
  6245 + favor of the now removed ``QEXC`` classes used in previous versions.
  6246 + The ``QEXC`` exception classes predated the addition of the
  6247 + @1@filename@1@<stdexcept>@2@filename@2@ header file to the C++
  6248 + standard library. Most of the exceptions thrown by the qpdf library
  6249 + itself are still of type ``QPDFExc`` which is now derived from
  6250 + ``std::runtime_error``. Programs that caught an instance of
  6251 + ``std::exception`` and displayed it by calling the ``what()`` method
  6252 + will not need to be changed.
  6253 +
  6254 +- The ``QPDFExc`` class now internally represents various fields of the
  6255 + error condition and provides interfaces for querying them. Among the
  6256 + fields is a numeric error code that can help applications act
  6257 + differently on (a small number of) different error conditions. See
  6258 + @1@filename@1@QPDFExc.hh@2@filename@2@ for details.
  6259 +
  6260 +- Warnings can be retrieved from qpdf as instances of ``QPDFExc``
  6261 + instead of strings.
  6262 +
  6263 +- The nested ``QPDF::EncryptionData`` class's constructor takes an
  6264 + additional argument. This class is primarily intended to be used by
  6265 + ``QPDFWriter``. There's not really anything useful an end-user
  6266 + application could do with it. It probably shouldn't really be part of
  6267 + the public interface to begin with. Likewise, some of the methods for
  6268 + computing internal encryption dictionary parameters have changed to
  6269 + support ``/R=4`` encryption.
  6270 +
  6271 +- The method ``QPDF::getUserPassword`` has been removed since it didn't
  6272 + do what people would think it did. There are now two new methods:
  6273 + ``QPDF::getPaddedUserPassword`` and ``QPDF::getTrimmedUserPassword``.
  6274 + The first one does what the old ``QPDF::getUserPassword`` method used
  6275 + to do, which is to return the password with possible binary padding
  6276 + as specified by the PDF specification. The second one returns a
  6277 + human-readable password string.
  6278 +
  6279 +- The enumerated types that used to be nested in ``QPDFWriter`` have
  6280 + moved to top-level enumerated types and are now defined in the file
  6281 + @1@filename@1@qpdf/Constants.h@2@filename@2@. This enables them to be
  6282 + shared by both the C and C++ interfaces.
6283 6283
6284 .. _ref.upgrading-to-3.0: 6284 .. _ref.upgrading-to-3.0:
6285 6285
@@ -6289,28 +6289,28 @@ Upgrading to 3.0 @@ -6289,28 +6289,28 @@ Upgrading to 3.0
6289 For the most part, the API for qpdf version 3.0 is backward compatible 6289 For the most part, the API for qpdf version 3.0 is backward compatible
6290 with versions 2.1 and later. There are two exceptions: 6290 with versions 2.1 and later. There are two exceptions:
6291 6291
6292 -- The method ``QPDFObjectHandle::replaceStreamData`` that uses a  
6293 - ``StreamDataProvider`` to provide the stream data no longer takes a  
6294 - ``length`` parameter. While it would have been easy enough to keep  
6295 - the parameter for backward compatibility, in this case, the parameter  
6296 - was removed since this provides the user an opportunity to simplify  
6297 - the calling code. This method was introduced in version 2.2. At the  
6298 - time, the ``length`` parameter was required in order to ensure that  
6299 - calls to the stream data provider returned the same length for a  
6300 - specific stream every time they were invoked. In particular, the  
6301 - linearization code depends on this. Instead, qpdf 3.0 and newer check  
6302 - for that constraint explicitly. The first time the stream data  
6303 - provider is called for a specific stream, the actual length is saved,  
6304 - and subsequent calls are required to return the same number of bytes.  
6305 - This means the calling code no longer has to compute the length in  
6306 - advance, which can be a significant simplification. If your code  
6307 - fails to compile because of the extra argument and you don't want to  
6308 - make other changes to your code, just omit the argument.  
6309 -  
6310 -- Many methods take ``long long`` instead of other integer types. Most  
6311 - if not all existing code should compile fine with this change since  
6312 - such parameters had always previously been smaller types. This change  
6313 - was required to support files larger than two gigabytes in size. 6292 +- The method ``QPDFObjectHandle::replaceStreamData`` that uses a
  6293 + ``StreamDataProvider`` to provide the stream data no longer takes a
  6294 + ``length`` parameter. While it would have been easy enough to keep
  6295 + the parameter for backward compatibility, in this case, the parameter
  6296 + was removed since this provides the user an opportunity to simplify
  6297 + the calling code. This method was introduced in version 2.2. At the
  6298 + time, the ``length`` parameter was required in order to ensure that
  6299 + calls to the stream data provider returned the same length for a
  6300 + specific stream every time they were invoked. In particular, the
  6301 + linearization code depends on this. Instead, qpdf 3.0 and newer check
  6302 + for that constraint explicitly. The first time the stream data
  6303 + provider is called for a specific stream, the actual length is saved,
  6304 + and subsequent calls are required to return the same number of bytes.
  6305 + This means the calling code no longer has to compute the length in
  6306 + advance, which can be a significant simplification. If your code
  6307 + fails to compile because of the extra argument and you don't want to
  6308 + make other changes to your code, just omit the argument.
  6309 +
  6310 +- Many methods take ``long long`` instead of other integer types. Most
  6311 + if not all existing code should compile fine with this change since
  6312 + such parameters had always previously been smaller types. This change
  6313 + was required to support files larger than two gigabytes in size.
6314 6314
6315 .. _ref.upgrading-to-4.0: 6315 .. _ref.upgrading-to-4.0:
6316 6316