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
Changes suppressed. Click to show
... ... @@ -97,26 +97,26 @@ System Requirements
97 97 The qpdf package has few external dependencies. In order to build qpdf,
98 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 121 Part of qpdf's test suite does comparisons of the contents PDF files by
122 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 135 this, the following additional requirements are required by the test
136 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 142 If you do not enable this, then you do not need to have tiff and
143 143 ghostscript.
... ... @@ -226,23 +226,23 @@ available crypto providers, and to use an external provider as the
226 226 default over the native one. This behavior can be changed with the
227 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 247 For example, if you want to guarantee that the gnutls crypto provider is
248 248 used and that the native provider is not built, you could run
... ... @@ -387,41 +387,41 @@ Notes for Packagers
387 387 If you are packaging qpdf for an operating system distribution, here are
388 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 426 .. _ref.using:
427 427  
... ... @@ -487,20 +487,20 @@ Exit Status
487 487 The exit status of @1@command@1@qpdf@2@command@2@ may be interpreted as
488 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 505 Note that @1@command@1@qpdf@2@command@2@ never exists with status ``1``.
506 506 If you get an exit status of ``1``, it was something else, like the
... ... @@ -703,39 +703,39 @@ needed transformations.
703 703 `Unicode Passwords <#ref.unicode-passwords>`__. The following modes
704 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 740 @1@option@1@--rotate=[+|-]angle[:page-range]@2@option@2@
741 741 Apply rotation to specified pages. The
... ... @@ -811,34 +811,34 @@ needed transformations.
811 811 output file. If @1@option@1@n@2@option@2@ is not specified, create
812 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 825 Page ranges are a single number in the case of single-page groups or
826 826 two numbers separated by a dash otherwise. For example, if
827 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 843 Note that outlines, threads, and other global features of the
844 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 965 @1@option@1@@1@replaceable@1@print-opt@2@replaceable@2@@2@option@2@
966 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 974 @1@option@1@--modify=@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@
975 975 Controls modify access. This way of controlling modify access has
... ... @@ -977,17 +977,17 @@ is 128, the following restriction options are available:
977 977 @1@option@1@@1@replaceable@1@modify-opt@2@replaceable@2@@2@option@2@
978 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 992 Using the @1@option@1@--modify@2@option@2@ option does not allow you
993 993 to create certain combinations of permissions such as allowing form
... ... @@ -1101,20 +1101,20 @@ is even or odd.
1101 1101  
1102 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 1119 Starting in qpdf version 8.3, you can specify the
1120 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 1134 1-5 b.pdf 6-4 c.pdf r1 -- out.pdf@2@command@2@, you would get the
1135 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 1155 Starting in qpdf version 10.2, you may specify a numeric argument to
1156 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 1161 r1 -- out.pdf@2@command@2@, you would get the following pages in this
1162 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 1182 Starting in qpdf version 8.3, when you split and merge files, any page
1183 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 1280 @1@option@1@--underlay@2@option@2@ flag and the
1281 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 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 1318 .. _ref.attachments:
1319 1319  
... ... @@ -1468,24 +1468,24 @@ following options are available:
1468 1468 @1@option@1@generalized@2@option@2@. The following options are
1469 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 1490 @1@option@1@--stream-data=@1@replaceable@1@option@2@replaceable@2@@2@option@2@
1491 1491 Controls transformation of stream data. This option predates the
... ... @@ -1495,21 +1495,21 @@ following options are available:
1495 1495 @1@option@1@@1@replaceable@1@option@2@replaceable@2@@2@option@2@ may
1496 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 1514 @1@option@1@--recompress-flate@2@option@2@
1515 1515 By default, streams already compressed with ``/FlateDecode`` are left
... ... @@ -1540,13 +1540,13 @@ following options are available:
1540 1540 @1@option@1@@1@replaceable@1@mode@2@replaceable@2@@2@option@2@ may be
1541 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 1551 @1@option@1@--preserve-unreferenced@2@option@2@
1552 1552 Tells qpdf to preserve objects that are not referenced when writing
... ... @@ -1637,14 +1637,14 @@ following options are available:
1637 1637 annotations. The @1@replaceable@1@option@2@replaceable@2@ parameter
1638 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 1649 Note that form fields are special because the annotations that are
1650 1650 used to render filled-in form fields may become out of date from the
... ... @@ -1666,25 +1666,25 @@ following options are available:
1666 1666 option. Most of these are not a problem with well-behaved PDF files.
1667 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 1689 If qpdf doesn't do a good enough job with your form, use an external
1690 1690 application to save your filled-in form before processing it with
... ... @@ -2141,41 +2141,41 @@ writes a repaired file to standard output.
2141 2141  
2142 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 2180 When editing a QDF file, any edits can be made as long as the above
2181 2181 constraints are maintained. This means that you can freely edit a page's
... ... @@ -2195,18 +2195,18 @@ object.
2195 2195 When @1@command@1@fix-qdf@2@command@2@ is run, it goes through the file
2196 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 2211 .. _ref.using-library:
2212 2212  
... ... @@ -2393,26 +2393,26 @@ Documentation
2393 2393 of the corresponding field in the JSON output. The specific
2394 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 2417 For example, the help output indicates includes a "``pagelabels``"
2418 2418 key whose value is an array of one element. That element is a
... ... @@ -2438,41 +2438,41 @@ Limitations of JSON Representation
2438 2438  
2439 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 2477 .. _json.considerations:
2478 2478  
... ... @@ -2483,34 +2483,34 @@ For the most part, the built-in JSON help tells you everything you need
2483 2483 to know about the JSON format, but there are a few non-obvious things to
2484 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 2515 .. _ref.design:
2516 2516  
... ... @@ -2703,29 +2703,29 @@ find them by looking at
2703 2703 In order to avoid creation of circular dependencies, the following
2704 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 2730 Prior to qpdf version 8.1, higher level interfaces were added as
2731 2731 "convenience functions" in either ``QPDF`` or ``QPDFObjectHandle``. For
... ... @@ -2786,55 +2786,55 @@ stream are cached.
2786 2786 The following example should clarify how ``QPDF`` processes a simple
2787 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 2839 .. _ref.casting:
2840 2840  
... ... @@ -3093,66 +3093,66 @@ This outline was written prior to implementation and is not exactly
3093 3093 accurate, but it provides a correct "notional" idea of how writing
3094 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 3157 Once we have finished the queue, all referenced objects will have been
3158 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 3307 When creating linearized PDF files from optimized PDF files, there are
3308 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 3316 .. _ref.optimization:
3317 3317  
... ... @@ -3424,17 +3424,17 @@ various other programs that create linearized files have many of these
3424 3424 same issues. These items make reference to terminology used in the
3425 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 3439 .. _ref.linearization-debugging:
3440 3440  
... ... @@ -3475,13 +3475,13 @@ Object Streams
3475 3475  
3476 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 3486 In addition, Adobe reader (at least as of version 8.0.0) appears to not
3487 3487 be able to handle having the document catalog appear in an object stream
... ... @@ -3501,11 +3501,11 @@ a regular object.
3501 3501  
3502 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 3510 Stream collections are formed with ``/Extends``. They must form a
3511 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 3555 and the may not contain indirect objects for keys required to read them,
3556 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 3574 The other fields in the xref stream, which may be indirect if desired,
3575 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 3589  
3590 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 3601 It seems standard to have the first entry in the table be ``0 0 0``
3602 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 3657 @1@filename@1@ChangeLog@2@filename@2@ in the source distribution.
3658 3658  
3659 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 4669 8.4.2: May 18, 2019
4670 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 4672 update. There are no code changes that affect non-Windows releases.
4673 4673  
4674 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 6227 2.0: April 29, 2008
6228   - - First public release.
  6228 + - First public release.
6229 6229  
6230 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 6240 are also some new interfaces; for those, please refer to the header
6241 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 6284 .. _ref.upgrading-to-3.0:
6285 6285  
... ... @@ -6289,28 +6289,28 @@ Upgrading to 3.0
6289 6289 For the most part, the API for qpdf version 3.0 is backward compatible
6290 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 6315 .. _ref.upgrading-to-4.0:
6316 6316  
... ...