octoleo/qpdf
2
1
Fork 0
mirror of https://github.com/qpdf/qpdf.git synced 2024-10-31 19:02:30 +00:00
Code Issues Releases Wiki Activity

Stop adding pre-built documentation to the source distribution

Browse Source
This commit is contained in:
Jay Berkenbilt 2021-12-21 09:23:20 -05:00
parent e058247bcf
commit 36916619f0
25 changed files with 250 additions and 163 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.github/workflows/main.yml vendored
View File

@ -21,14 +21,13 @@ on:
jobs: jobs:
Prebuild: Prebuild:
# Run steps that are needed by the Windows build but are easier to # Run steps that are needed by the Windows build but are easier to
# build on Linux. Although only the Windows builds need this, # build on Linux. Also create the documentation distribution.
# other jobs depend on it to force it to run early.
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- uses: actions/checkout@v2 - uses: actions/checkout@v2
- name: 'Run pre-build steps' - name: 'Run pre-build steps'
run: build-scripts/prebuild run: build-scripts/prebuild
- name: 'Upload extra distribution files' - name: 'Upload documentation for later build steps'
uses: actions/upload-artifact@v1 uses: actions/upload-artifact@v1
with: with:
name: doc name: doc
@ -38,6 +37,11 @@ jobs:
with: with:
name: external-libs name: external-libs
path: external-libs-dist path: external-libs-dist
- name: 'Upload doc distribution'
uses: actions/upload-artifact@v1
with:
name: distribution
path: distribution
Linux: Linux:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:

2
.gitignore vendored
View File

@ -5,8 +5,6 @@ autoconf.mk
autom4te.cache/ autom4te.cache/
config.log config.log
config.status config.status
doc
doc.zip
examples/build/ examples/build/
external-libs external-libs
fuzz/build/ fuzz/build/

8
ChangeLog
View File

@ -1,3 +1,11 @@
2021-12-21 Jay Berkenbilt <ejb@ql.org>
* Discontinue inclusion of the pre-built documentation in the
source distribution. Consult the packaging documentation in the
manual for details. The file README-doc.txt is installed in the
doc directory by default and contains information that users will
need to know to find the documentation.
2021-12-19 Jay Berkenbilt <ejb@ql.org> 2021-12-19 Jay Berkenbilt <ejb@ql.org>
* C API: clarify documentation around string lengths. Add two new * C API: clarify documentation around string lengths. Add two new

1
Makefile
View File

@ -106,7 +106,6 @@ distclean: clean
maintainer-clean: distclean maintainer-clean: distclean
$(RM) -r install-mingw* install-msvc* external-libs $(RM) -r install-mingw* install-msvc* external-libs
$(RM) -rf doc
.PHONY: $(TEST_TARGETS) .PHONY: $(TEST_TARGETS)

20
README-doc.txt Normal file
View File

@ -0,0 +1,20 @@
WHERE TO FIND THE QPDF DOCUMENTATION
Complete documentation for qpdf can be found online here:
https://qpdf.readthedocs.io
Some distributions include offline documentation typically in a
location such as /usr/share/doc/qpdf. If it isn't there, you can find
a zip file containing the documentation in the qpdf release area:
https://github.com/qpdf/qpdf/releases
Offline documentation contains the following:
* PDF: qpdf-manual.pdf
* HTML: html/index.html
* SINGLE-PAGE HTML: singlehtml/index.html
If you are reading this file from the source distribution, you can
find the documentation sources in the "manual" directory. There is
information in the manual about how to build and package the
documentation.

11
README-maintainer
View File

@ -4,10 +4,6 @@ ROUTINE DEVELOPMENT
Default: Default:
./configure CXX="g++ --std=c++14" --enable-werror
Doc:
./configure CXX="g++ --std=c++14" --enable-werror --enable-doc-maintenance ./configure CXX="g++ --std=c++14" --enable-werror --enable-doc-maintenance
Debugging: Debugging:
@ -363,13 +359,6 @@ rsync -vrlcO ./ jay_berkenbilt,qpdf@frs.sourceforge.net:/home/frs/project/q/qp/q
OTHER NOTES OTHER NOTES
To construct a source distribution from a pristine checkout,
`make_dist` does the following:
./configure --enable-doc-maintenance --enable-werror
make build_manual
make distclean
For local iteration on the AppImage generation, it works to just For local iteration on the AppImage generation, it works to just
./build-scripts/build-appimage and get the resulting AppImage from ./build-scripts/build-appimage and get the resulting AppImage from
the distribution directory. You can also pass -e SKIP_TESTS=1 the distribution directory. You can also pass -e SKIP_TESTS=1

3
README-windows-install.txt
View File

@ -6,6 +6,7 @@ have the bin directory in your path. To compile with qpdf, just add
the lib directory to your library path and the include directory to the lib directory to your library path and the include directory to
your include path. If you are going to use Pl_DCT in your code, you your include path. If you are going to use Pl_DCT in your code, you
will also need to have jpeg library development files in your build will also need to have jpeg library development files in your build
environment. Detailed documentation may be found in the doc directory. environment. Detailed documentation may be found in the doc directory
and at https://qpdf.readthedocs.io.
Enjoy! Enjoy!

14
README.md
View File

@ -67,10 +67,6 @@ Please see the section on crypto providers in the manual for more details.
The PDF file format used to rely on RC4 for encryption. Using 256-bit keys always uses AES instead, and with 128-bit keys, you can elect to use AES. qpdf does its best to warn when someone is writing a file with weak cryptographic algorithms, but qpdf must always retain support for being able to read and even write files with weak encryption to be able to fully support older PDF files and older PDF readers. The PDF file format used to rely on RC4 for encryption. Using 256-bit keys always uses AES instead, and with 128-bit keys, you can elect to use AES. qpdf does its best to warn when someone is writing a file with weak cryptographic algorithms, but qpdf must always retain support for being able to read and even write files with weak encryption to be able to fully support older PDF files and older PDF readers.
# Building from a pristine checkout
When building qpdf from a pristine checkout from version control, generated HTML and PDF documentation files are not present. You don't need them unless you are going to run `make install` and want the documentation to be installed. If you want them, you can either extract the `doc` directory from a source distribution, or you can satisfy the additional requirements for building documentation and pass `--enable-doc-maintenance` to `./configure`.
# Building from source distribution on UNIX/Linux # Building from source distribution on UNIX/Linux
For UNIX and UNIX-like systems, you can usually get by with just For UNIX and UNIX-like systems, you can usually get by with just
@ -81,7 +77,9 @@ make
make install make install
``` ```
Packagers may set DESTDIR, in which case make install will install inside of DESTDIR, as is customary with many packages. For more detailed general information, see the "INSTALL" file in this directory. If you are already accustomed to building and installing software that uses autoconf, there's nothing new for you in the INSTALL file. Note that qpdf uses `autoconf` but not `automake`. We have our own system of Makefiles that allows cross-directory dependencies, doesn't use recursive make, and works better on non-UNIX platforms. Packagers may set DESTDIR, in which case make install will install inside of DESTDIR, as is customary with many packages. Please also see the "Notes for Packagers" section of the manual.
For more detailed general information, see the "INSTALL" file in this directory. If you are already accustomed to building and installing software that uses autoconf, there's nothing new for you in the INSTALL file. Note that qpdf uses `autoconf` but not `automake`. We have our own system of Makefiles that allows cross-directory dependencies, doesn't use recursive make, and works better on non-UNIX platforms.
# Building without wchar_t # Building without wchar_t
@ -101,12 +99,14 @@ Note qpdf will never define QPDF_NO_WCHAR_T using autoconf or any other automate
QPDF is known to build and pass its test suite with mingw (latest version tested: gcc 7.2.0), mingw64 (latest version tested: 7.2.0) and Microsoft Visual C++ 2015, both 32-bit and 64-bit versions. MSYS2 is required to build as well in order to get make and other related tools. See [README-windows.md](README-windows.md) for details on how to build under Windows. QPDF is known to build and pass its test suite with mingw (latest version tested: gcc 7.2.0), mingw64 (latest version tested: 7.2.0) and Microsoft Visual C++ 2015, both 32-bit and 64-bit versions. MSYS2 is required to build as well in order to get make and other related tools. See [README-windows.md](README-windows.md) for details on how to build under Windows.
# Building Documentation
The QPDF manual is written in reStructured Text format and is build with [sphinx](https://www.sphinx-doc.org). The sources to the user manual can be found in the `manual` directory. For more detailed information, consult the [Building and Installing QPDF section of the manual](manual/installation.rst) or consult the [build-doc script used in CI](build-scripts/build-doc).
# Additional Notes on Build # Additional Notes on Build
QPDF's build system can optionally use its own built-in rules rather than using libtool and obeying the compiler specified with configure. This can be enabled by passing `--with-buildrules=buildrules` where buildrules corresponds to one of the `.mk` files (other than `rules.mk`) in the make directory. This should never be necessary on a UNIX system, but may be necessary on a Windows system. See [README-windows.md](README-windows.md) for details. QPDF's build system can optionally use its own built-in rules rather than using libtool and obeying the compiler specified with configure. This can be enabled by passing `--with-buildrules=buildrules` where buildrules corresponds to one of the `.mk` files (other than `rules.mk`) in the make directory. This should never be necessary on a UNIX system, but may be necessary on a Windows system. See [README-windows.md](README-windows.md) for details.
The QPDF package provides some executables and a software library. A user manual can be found in the "doc" directory. The sources to the user manual can be found in the `manual` directory.
The software library is just `libqpdf`, and all the header files are in the `qpdf` subdirectories of `include` and `libqpdf`. If you link statically with `-lqpdf`, then you will also need to link with `-lz` and `-ljpeg`. The shared qpdf library is linked with `-lz` and `-ljpeg`, none of qpdf's public header files directly include files from `libz`, and only `Pl_DCT.hh` includes files from `libjpeg`, so for most cases, qpdf's development files are self contained. If you need to use `Pl_DCT` in your application code, you will need to have the header files for some libjpeg distribution in your include path. The software library is just `libqpdf`, and all the header files are in the `qpdf` subdirectories of `include` and `libqpdf`. If you link statically with `-lqpdf`, then you will also need to link with `-lz` and `-ljpeg`. The shared qpdf library is linked with `-lz` and `-ljpeg`, none of qpdf's public header files directly include files from `libz`, and only `Pl_DCT.hh` includes files from `libjpeg`, so for most cases, qpdf's development files are self contained. If you need to use `Pl_DCT` in your application code, you will need to have the header files for some libjpeg distribution in your include path.
To learn about using the library, please read comments in the header files in `include/qpdf`, especially `QPDF.hh`, `QPDFObjectHandle.hh`, and To learn about using the library, please read comments in the header files in `include/qpdf`, especially `QPDF.hh`, `QPDFObjectHandle.hh`, and

1
appimage/build-appimage
View File

@ -100,6 +100,7 @@ mkdir -p $appdir
# Install build result into AppDir: # Install build result into AppDir:
make install DESTDIR=$appdir; find $appdir make install DESTDIR=$appdir; find $appdir
make doc-dist DOC_DEST=appdir/usr/share/doc/qpdf
# Change into build directory: # Change into build directory:
cd $here/build cd $here/build

17
build-scripts/build-doc Executable file
View File

@ -0,0 +1,17 @@
#!/bin/bash
# The manual references this file.
cd $(dirname $0)/..
set -ex
sudo apt-get update
sudo apt-get -y install \
autoconf build-essential zlib1g-dev libjpeg-dev \
python3-pip texlive-latex-extra latexmk
pip3 install sphinx sphinx_rtd_theme
./configure --enable-doc-maintenance
make -j$(nproc) doc-dist DOC_DEST=doc
zip -r doc.zip doc
version=$(egrep '^release' manual/conf.py | cut -d"'" -f 2)
mv doc qpdf-${version}-doc
mkdir distribution
zip -r distribution/qpdf-${version}-doc.zip qpdf-${version}-doc
sha256sum distribution/*

8
build-scripts/build-linux
View File

@ -3,10 +3,8 @@ set -ex
sudo apt-get update sudo apt-get update
sudo apt-get -y install \ sudo apt-get -y install \
autoconf build-essential zlib1g-dev libjpeg-dev libgnutls28-dev \ autoconf build-essential zlib1g-dev libjpeg-dev libgnutls28-dev \
libssl-dev python3-pip texlive-latex-extra latexmk \ libssl-dev libtiff-tools ghostscript
inkscape imagemagick libtiff-tools ghostscript ./configure --enable-werror \
pip3 install sphinx sphinx_rtd_theme
./configure --enable-werror --enable-doc-maintenance \
--enable-crypto-native --enable-crypto-openssl --enable-crypto-gnutls \ --enable-crypto-native --enable-crypto-openssl --enable-crypto-gnutls \
--enable-show-failed-test-output --enable-test-compare-images --enable-show-failed-test-output --enable-test-compare-images
make -j$(nproc) -k make -j$(nproc) -k
@ -16,7 +14,7 @@ for i in $(./qpdf/build/qpdf --show-crypto); do
done done
export TMPDIR=$PWD/dist-tmp export TMPDIR=$PWD/dist-tmp
rm -rf $TMPDIR rm -rf $TMPDIR
./make_dist --ci --no-tests ./make_dist --ci
mkdir distribution mkdir distribution
cp $TMPDIR/qpdf*-ci.tar.gz distribution cp $TMPDIR/qpdf*-ci.tar.gz distribution
sha256sum distribution/* sha256sum distribution/*

10
build-scripts/prebuild
View File

@ -1,12 +1,4 @@
#!/bin/bash #!/bin/bash
cd $(dirname $0)/.. cd $(dirname $0)/..
set -ex build-scripts/build-doc
sudo apt-get update
sudo apt-get -y install \
autoconf build-essential zlib1g-dev libjpeg-dev \
python3-pip texlive-latex-extra latexmk inkscape imagemagick
pip3 install sphinx sphinx_rtd_theme
./configure --enable-doc-maintenance
make -j$(nproc) build_manual
zip -r doc.zip doc/*html doc/*.pdf
build-scripts/download-external-libs build-scripts/download-external-libs

11
make/installwin.mk
View File

@ -8,7 +8,6 @@ installwin: all
mkdir $(DEST)/lib mkdir $(DEST)/lib
mkdir $(DEST)/include mkdir $(DEST)/include
mkdir $(DEST)/include/qpdf mkdir $(DEST)/include/qpdf
mkdir $(DEST)/doc
cp libqpdf/$(OUTPUT_DIR)/$(IMPORT_LIB_NAME) $(DEST)/lib cp libqpdf/$(OUTPUT_DIR)/$(IMPORT_LIB_NAME) $(DEST)/lib
cp libqpdf/$(OUTPUT_DIR)/qpdf*.dll $(DEST)/bin cp libqpdf/$(OUTPUT_DIR)/qpdf*.dll $(DEST)/bin
perl copy_dlls libqpdf/$(OUTPUT_DIR)/qpdf*.dll $(DEST)/bin $(OBJDUMP) $(WINDOWS_WORDSIZE) perl copy_dlls libqpdf/$(OUTPUT_DIR)/qpdf*.dll $(DEST)/bin $(OBJDUMP) $(WINDOWS_WORDSIZE)
@ -17,12 +16,6 @@ installwin: all
cp qpdf/$(OUTPUT_DIR)/fix-qdf.exe $(DEST)/bin cp qpdf/$(OUTPUT_DIR)/fix-qdf.exe $(DEST)/bin
cp include/qpdf/*.h $(DEST)/include/qpdf cp include/qpdf/*.h $(DEST)/include/qpdf
cp include/qpdf/*.hh $(DEST)/include/qpdf cp include/qpdf/*.hh $(DEST)/include/qpdf
if [ -f doc/qpdf-manual.pdf ]; then \ if [ -d doc ]; then \
cp doc/qpdf-manual.pdf $(DEST)/doc; \ cp -r doc $(DEST); \
fi
if [ -d doc/html ]; then \
cp -r doc/html $(DEST)/doc; \
fi
if [ -d doc/singlehtml ]; then \
cp -r doc/singlehtml $(DEST)/doc; \
fi fi

12
make/libtool.mk
View File

@ -137,13 +137,5 @@ install: all install-libs
$(LIBTOOL) --mode=install ./install-sh \ $(LIBTOOL) --mode=install ./install-sh \
qpdf/$(OUTPUT_DIR)/fix-qdf \ qpdf/$(OUTPUT_DIR)/fix-qdf \
$(DESTDIR)$(bindir)/fix-qdf $(DESTDIR)$(bindir)/fix-qdf
if [ -f doc/qpdf-manual.pdf ]; then \ ./install-sh -m 0644 README-doc.txt $(DESTDIR)$(docdir); \
./install-sh -m 0644 doc/qpdf-manual.pdf $(DESTDIR)$(docdir); \ ./install-sh -m 0644 manual/$(OUTPUT_DIR)/*.1 $(DESTDIR)$(mandir)/man1
fi
if [ -d doc/html ]; then \
cp -r doc/html $(DESTDIR)/$(docdir); \
fi
if [ -d doc/singlehtml ]; then \
cp -r doc/singlehtml $(DESTDIR)/$(docdir); \
fi
./install-sh -m 0644 doc/*.1 $(DESTDIR)$(mandir)/man1

16
make_dist
View File

@ -1,7 +1,7 @@
#!/usr/bin/env perl #!/usr/bin/env perl
# #
# This program creates a source distribution of qpdf. For details, # This program creates a source distribution of qpdf. For details,
# see README-maintainer.md. # see README-maintainer.
# #
require 5.008; require 5.008;
@ -16,7 +16,6 @@ use File::Path qw(rmtree make_path);
my $whoami = basename($0); my $whoami = basename($0);
my $tmp = $ENV{'TMPDIR'} || '/tmp'; my $tmp = $ENV{'TMPDIR'} || '/tmp';
my $run_tests = 1;
my $keep_tmp = 0; my $keep_tmp = 0;
my $ci_mode = 0; my $ci_mode = 0;
my $version = undef; my $version = undef;
@ -24,7 +23,7 @@ foreach my $arg (@ARGV)
{ {
if ($arg eq '--no-tests') if ($arg eq '--no-tests')
{ {
$run_tests = 0; # ignore for compatibility
} }
elsif ($arg eq '--keep-tmp') elsif ($arg eq '--keep-tmp')
{ {
@ -93,19 +92,8 @@ if ($version_error)
die "$whoami: version numbers are not consistent\n"; die "$whoami: version numbers are not consistent\n";
} }
run("./configure --disable-shared --enable-doc-maintenance --enable-werror");
run("make -j8 build_manual");
run("make distclean");
cd($tmp); cd($tmp);
run("tar czvf $distname.tar.gz-candidate $distname"); run("tar czvf $distname.tar.gz-candidate $distname");
if ($run_tests)
{
cd($tmpdir);
run("./configure");
run("make -j8");
run("make check");
cd($tmp);
}
my $distfile = ($ci_mode ? "$distname-ci.tar.gz" : "$distname.tar.gz"); my $distfile = ($ci_mode ? "$distname-ci.tar.gz" : "$distname.tar.gz");
rename "$distname.tar.gz-candidate", $distfile or die; rename "$distname.tar.gz-candidate", $distfile or die;

3
manual/README
View File

@ -1,3 +0,0 @@
This directory contains sources to the documentation. If you are
looking for pre-built documentation, please look in the "doc"
directory.

39
manual/build.mk
View File

@ -6,7 +6,10 @@ HTML_TARGET := $(HTML_OUT)/index.html
PDF_OUT := $(DOC_OUT)/latex PDF_OUT := $(DOC_OUT)/latex
PDF_TARGET := $(PDF_OUT)/qpdf.pdf PDF_TARGET := $(PDF_OUT)/qpdf.pdf
TARGETS_manual := doc/qpdf.1 doc/fix-qdf.1 doc/zlib-flate.1 TARGETS_manual := \
$(DOC_OUT)/qpdf.1 \
$(DOC_OUT)/fix-qdf.1 \
$(DOC_OUT)/zlib-flate.1
ifeq ($(BUILD_HTML),1) ifeq ($(BUILD_HTML),1)
TARGETS_manual += $(HTML_TARGET) $(S_HTML_TARGET) TARGETS_manual += $(HTML_TARGET) $(S_HTML_TARGET)
endif endif
@ -22,23 +25,31 @@ MANUAL_DEPS = $(wildcard manual/*.rst) manual/conf.py
# the error "_pickle.UnpicklingError: pickle data was truncated" # the error "_pickle.UnpicklingError: pickle data was truncated"
$(HTML_TARGET): $(MANUAL_DEPS) $(HTML_TARGET): $(MANUAL_DEPS)
$(SPHINX) -M html manual $(DOC_OUT) -W $(SPHINX) -M html manual $(DOC_OUT) -W
mkdir -p doc
rm -rf doc/html
cp -r $(DOC_OUT)/html doc
$(S_HTML_TARGET): $(MANUAL_DEPS) | $(HTML_TARGET) $(S_HTML_TARGET): $(MANUAL_DEPS) | $(HTML_TARGET)
$(SPHINX) -M singlehtml manual $(DOC_OUT) -W $(SPHINX) -M singlehtml manual $(DOC_OUT) -W
mkdir -p doc
rm -rf doc/singlehtml
cp -r $(DOC_OUT)/singlehtml doc
$(PDF_TARGET): $(MANUAL_DEPS) | $(S_HTML_TARGET) $(HTML_TARGET) $(PDF_TARGET): $(MANUAL_DEPS) | $(S_HTML_TARGET) $(HTML_TARGET)
$(SPHINX) -M latexpdf manual $(DOC_OUT) -W $(SPHINX) -M latexpdf manual $(DOC_OUT) -W
mkdir -p doc
cp $(PDF_TARGET) doc/qpdf-manual.pdf
doc/%.1: manual/%.1.in $(DOC_OUT)/%.1: manual/%.1.in
mkdir -p doc sed -e 's:@PACKAGE_VERSION@:$(PACKAGE_VERSION):g' < $< > $@
sed -e 's:@PACKAGE_VERSION@:$(PACKAGE_VERSION):g' \
-e 's:@docdir@:$(docdir):g' \ # The doc-dist target must not removed $(DOC_DEST) so that it works to
< $< > $@ # do stuff like make doc-dist DOC_DEST=$(DESTDIR)/$(docdir). Make sure
# what this does is consistent with ../README-doc.txt and the
# information in the manual and ../README.md.
.PHONY: doc-dist
doc-dist: build_manual
@if test x"$(DOC_DEST)" = x; then \
echo DOC_DEST must be set 1>& 2; \
false; \
fi
if test -d $(DOC_DEST); then \
$(RM) -rf $(DOC_DEST)/*html $(DOC_DEST)/*.pdf; \
else \
mkdir -p $(DOC_DEST); \
fi
cp -r $(DOC_OUT)/html doc
cp -r $(DOC_OUT)/singlehtml doc
cp $(PDF_TARGET) $(DOC_DEST)/qpdf-manual.pdf

1
manual/conf.py
View File

@ -11,6 +11,7 @@ import sphinx_rtd_theme # noQA F401
project = 'QPDF' project = 'QPDF'
copyright = '2005-2021, Jay Berkenbilt' copyright = '2005-2021, Jay Berkenbilt'
author = 'Jay Berkenbilt' author = 'Jay Berkenbilt'
# make_dist and the CI build lexically find the release version from this file.
release = '10.5.0' release = '10.5.0'
version = release version = release
extensions = [ extensions = [

4
manual/fix-qdf.1.in
View File

@ -14,8 +14,6 @@ the same file with stream lengths, cross-reference table entries, and
object stream offset tables regenerated. object stream offset tables regenerated.
.PP .PP
For details about fix-qdf and about PDF files in QDF mode, please see For details about fix-qdf and about PDF files in QDF mode, please see
the qpdf manual, which can be found in @docdir@/html/index.html or the qpdf manual, which can be found at https://qpdf.readthedocs.io.
@docdir@/qpdf-manual.pdf. The latest version of the documentation can
be found at https://qpdf.readthedocs.io.
.SH "SEE ALSO" .SH "SEE ALSO"
qpdf(1) qpdf(1)

1
manual/index.rst
View File

@ -21,6 +21,7 @@ documentation, please visit `https://qpdf.readthedocs.io
license license
download download
installation installation
packaging
cli cli
qdf qdf
library library

69
manual/installation.rst
View File

@ -60,14 +60,7 @@ suite. Note that in no case are these items required to use qpdf.
If you do not enable this, then you do not need to have tiff and If you do not enable this, then you do not need to have tiff and
ghostscript. ghostscript.
Pre-built documentation is distributed with qpdf, so you should For information on building the documentation, see :ref:`build-doc`.
generally not need to rebuild the documentation. In order to build the
documentation from source, you need to install `Sphinx
<https://sphinx-doc.org>`__ along with the ``sphinx_rtd_doc`` theme
(``pip install sphinx sphinx_rtd_theme``). To build the PDF version of
the documentation, you need ``pdflatex``, ``latexmk``, and a fairly
complete LaTeX installation. Detailed requirements can be found in the
Sphinx documentation.
.. _building: .. _building:
@ -113,6 +106,23 @@ hand-crafted non-recursive Makefile that requires gnu make. If you're
really interested, please read the comments in the top-level really interested, please read the comments in the top-level
:file:`Makefile`. :file:`Makefile`.
.. _build-doc:
Building Documentation
----------------------
The qpdf manual is written in reStructured Text and built with `Sphinx
<https://www.sphinx-doc.org>`__ using the `Read the Docs Sphinx Theme
<https://sphinx-rtd-theme.readthedocs.io>`__. In order to build the
HTML documentation from source, you need to install sphinx and the
theme, which you can typically do with ``pip install sphinx
sphinx_rtd_theme``. To build the PDF version of the documentation, you
need ``pdflatex``, ``latexmk``, and a fairly complete LaTeX
installation. Detailed requirements can be found in the Sphinx
documentation. To see how the documentation is built for the qpdf
distribution, refer to the :file:`build-scripts/build-doc` file in the
qpdf source distribution.
.. _crypto: .. _crypto:
Crypto Providers Crypto Providers
@ -298,46 +308,3 @@ provide their own implementations for basic filters like
Implementing the registration functions and internal storage of Implementing the registration functions and internal storage of
registered providers was also easier using C++-11's functional registered providers was also easier using C++-11's functional
interfaces, which was another reason to require C++-11 at this time. interfaces, which was another reason to require C++-11 at this time.
.. _packaging:
Notes for Packagers
-------------------
If you are packaging qpdf for an operating system distribution, here are
some things you may want to keep in mind:
- Starting in qpdf version 9.1.1, qpdf no longer has a runtime
dependency on perl. This is because fix-qdf was rewritten in C++.
However, qpdf still has a build-time dependency on perl.
- Make sure you are getting the intended behavior with regard to crypto
providers. Read :ref:`crypto.build` for details.
- Passing :samp:`--enable-show-failed-test-output` to
:command:`./configure` will cause any failed test
output to be written to the console. This can be very useful for
seeing test failures generated by autobuilders where you can't access
qtest.log after the fact.
- If qpdf's build environment detects the presence of autoconf and
related tools, it will check to ensure that automatically generated
files are up-to-date with recorded checksums and fail if it detects a
discrepancy. This feature is intended to prevent you from
accidentally forgetting to regenerate automatic files after modifying
their sources. If your packaging environment automatically refreshes
automatic files, it can cause this check to fail. Suppress qpdf's
checks by passing :samp:`--disable-check-autofiles`
to :command:`/.configure`. This is safe since qpdf's
:command:`autogen.sh` just runs autotools in the
normal way.
- QPDF's :command:`make install` does not install
completion files by default, but as a packager, it's good if you
install them wherever your distribution expects such files to go. You
can find completion files to install in the
:file:`completions` directory.
- Packagers are encouraged to install the source files from the
:file:`examples` directory along with qpdf
development packages.

120
manual/packaging.rst Normal file
View File

@ -0,0 +1,120 @@
.. _packaging:
Notes for Packagers
===================
If you are packaging qpdf for an operating system distribution, this
chapter is for you. Otherwise, feel free to skip.
Build Options
-------------
- Perl must be present at build time. Prior to qpdf version 9.1.1,
there was a runtime dependency on perl, but this is no longer the
case.
- Make sure you are getting the intended behavior with regard to crypto
providers. Read :ref:`crypto.build` for details.
- Passing :samp:`--enable-show-failed-test-output` to
:command:`./configure` will cause any failed test
output to be written to the console. This can be very useful for
seeing test failures generated by autobuilders where you can't access
qtest.log after the fact.
- If qpdf's build environment detects the presence of autoconf and
related tools, it will check to ensure that automatically generated
files are up-to-date with recorded checksums and fail if it detects a
discrepancy. This feature is intended to prevent you from
accidentally forgetting to regenerate automatic files after modifying
their sources. If your packaging environment automatically refreshes
automatic files, it can cause this check to fail. Suppress qpdf's
checks by passing :samp:`--disable-check-autofiles`
to :command:`/.configure`. This is safe since qpdf's
:command:`autogen.sh` just runs autotools in the
normal way.
- QPDF's :command:`make install` does not install completion files by
default, but as a packager, it's good if you install them wherever
your distribution expects such files to go. You can find completion
files to install in the :file:`completions` directory.
- Packagers are encouraged to install the source files from the
:file:`examples` directory along with qpdf development packages.
.. _packaging-doc:
Packaging Documentation
-----------------------
Starting in qpdf version 10.5, pre-built documentation is no longer
distributed with the qpdf source distribution. Here are a few options
you may want to consider for your packages:
- **Do nothing**
When you run ``make install``, the file :file:`README-doc.txt` is
installed in ``$(docdir)``. That file tells the reader where to find
the documentation online and where to go to download offline copies
of the documentation. This is the option selected by the debian
packages.
- **Embed pre-built documentation**
You can obtain pre-built documentation and extract its contents into
your distribution. This is what the Windows binary distributions
available from the qpdf release site do. You can find the pre-build
documentation in the release area in the file
:file:`qpdf-{version}-doc.zip`.
- **Build the documentation yourself**
You can build the documentation as part of your build process. Be
sure to pass ``--enable-doc-maintenance`` to ``./configure``, and
install it with ``make doc-dist DOC_DEST=...``. This is what the
AppImage build does. The latest version of Sphinx at the time of the
initial conversion a sphinx-based documentation was 4.3.2. Older
versions are not guaranteed to work.
Documentation Packaging Rationale
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes the reason for things being the way they are.
It's for information only; you don't have to know any of this to
package qpdf.
What is the reason for this change? Prior to qpdf 10.5, the qpdf
manual was a docbook XML file. The generated documents were the
product of running the file through build-time style sheets and
contained no copyrighted material of their own. Starting with version
10.5, the manual is written produced with `Sphinx
<https://www.sphinx-doc.org>`__. This change was made to make it much
easier to automatically generate portions of the documentation and to
make the documentation easier to work with. The HTML output of Sphinx
is also much more readable, usable, and suitable for online
consumption than the output of the docbook style sheets. The downsides
are that the generated HTML documentation now contains Javascript code
and embedded fonts, and the PDF version of the documentation is no
longer as suitable for printing (at least as of the 10.5 distribution)
since external link targets are no longer shown and cross references
no longer contain page number information. The presence of copyrighted
material in the generated documentation, even though things are
licensed with MIT and BSD licenses, complicates the job of the
packager in various ways. For one thing, it means the
:file:`NOTICE.md` file in the source repository would have to keep up
with the copyright information for files that are not controlled in
the repository. Additionally, some distributions (notably
Debian/Ubuntu) discourage inclusion of sphinx-generated documentation
in packages, preferring you instead to build the documentation as part
of the package build process and to depend at runtime on a shared
package that contains the code. At the time of the conversion of the
qpdf manual from docbook to sphinx, newer versions of both sphinx and
the html theme were required than were available in some of most of
the Debian/Ubuntu versions for which qpdf was packaged.
Since always-on Internet connectivity is much more common than it used
to be, many users of qpdf would prefer to consume the documentation
online anyway, and the lack of pre-built documentation in the
distribution won't be as big of a deal. However there are still some
people who can't or choose not to view documentation online. For them,
pre-built documentation is still available.

4
manual/qpdf.1.in
View File

@ -15,6 +15,4 @@ options for inspecting or checking PDF files, some of which are
useful primarily to PDF developers. useful primarily to PDF developers.
.PP .PP
For a summary of qpdf's options, please run \fBqpdf \-\-help\fR. A For a summary of qpdf's options, please run \fBqpdf \-\-help\fR. A
complete manual can be found in @docdir@/html/index.html or complete manual can be found at https://qpdf.readthedocs.io.
@docdir@/qpdf-manual.pdf. The latest version of the documentation can
be found at https://qpdf.readthedocs.io.

24
manual/release-notes.rst
View File

@ -6,29 +6,25 @@ Release Notes
For a detailed list of changes, please see the file For a detailed list of changes, please see the file
:file:`ChangeLog` in the source distribution. :file:`ChangeLog` in the source distribution.
10.5.0: December 20, 2021 10.5.0: December 21, 2021
- Packaging changes - Packaging changes
- The structure of the ``doc`` directory is different. The PDF - Pre-built documentation is no longer distributed with the source
documentation is in the same place, but the files for the distribution. The AppImage and Windows binary distributions
previous HTML documentation are no longer there. Instead, there still contain embedded documentation, and a separate ``doc``
are ``html`` and ``singlehtml`` directories, each of which distribution file is available from the qpdf release site.
contain ``index.html`` and other files and directories. The Documentation is now available at `https://qpdf.readthedocs.io
distribution files and ``make install`` target handle this, but <https://qpdf.readthedocs.io>`__ for every major/minor version
if you are building your own packages and including starting with version 10.5. Please see :ref:`packaging-doc` for
documentation, please double check to make sure that you are details on how packagers should handle documentation.
including the right documentation files.
- The documentation sources have been switched from docbook to - The documentation sources have been switched from docbook to
reStructuredText processed with `Sphinx reStructuredText processed with `Sphinx
<https://sphinx-doc.org>`__. This will break previous <https://www.sphinx-doc.org>`__. This will break previous
documentation links. A redirect is in place on the main website. documentation links. A redirect is in place on the main website.
A top-to-bottom review of the documentation is planned for an A top-to-bottom review of the documentation is planned for an
upcoming release. upcoming release.
- Documentation is now available at `https://qpdf.readthedocs.io
<https://qpdf.readthedocs.io>`__.
- Library Enhancements - Library Enhancements
- Since qpdf version 8, using object accessor methods on an - Since qpdf version 8, using object accessor methods on an

4
manual/zlib-flate.1.in
View File

@ -21,8 +21,6 @@ This program should not be used as a general purpose compression
tool. Use something like gzip(1) instead. tool. Use something like gzip(1) instead.
.PP .PP
For details about qpdf, please see the qpdf manual, which can be found For details about qpdf, please see the qpdf manual, which can be found
in @docdir@/html/index.html or @docdir@/qpdf-manual.pdf. The latest at https://qpdf.readthedocs.io.
version of the documentation can be found at
https://qpdf.readthedocs.io.
.SH "SEE ALSO" .SH "SEE ALSO"
qpdf(1), gzip(1) qpdf(1), gzip(1)