2
1
mirror of https://github.com/qpdf/qpdf.git synced 2024-10-31 19:02:30 +00:00

Stop adding pre-built documentation to the source distribution

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

View File

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

2
.gitignore vendored
View File

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

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>
* C API: clarify documentation around string lengths. Add two new

View File

@ -106,7 +106,6 @@ distclean: clean
maintainer-clean: distclean
$(RM) -r install-mingw* install-msvc* external-libs
$(RM) -rf doc
.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.

View File

@ -4,10 +4,6 @@ ROUTINE DEVELOPMENT
Default:
./configure CXX="g++ --std=c++14" --enable-werror
Doc:
./configure CXX="g++ --std=c++14" --enable-werror --enable-doc-maintenance
Debugging:
@ -363,13 +359,6 @@ rsync -vrlcO ./ jay_berkenbilt,qpdf@frs.sourceforge.net:/home/frs/project/q/qp/q
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
./build-scripts/build-appimage and get the resulting AppImage from
the distribution directory. You can also pass -e SKIP_TESTS=1

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
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
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!

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.
# 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
For UNIX and UNIX-like systems, you can usually get by with just
@ -81,7 +77,9 @@ make
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
@ -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.
# 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
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.
To learn about using the library, please read comments in the header files in `include/qpdf`, especially `QPDF.hh`, `QPDFObjectHandle.hh`, and

View File

@ -100,6 +100,7 @@ mkdir -p $appdir
# Install build result into AppDir:
make install DESTDIR=$appdir; find $appdir
make doc-dist DOC_DEST=appdir/usr/share/doc/qpdf
# Change into build directory:
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/*

View File

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

View File

@ -1,12 +1,4 @@
#!/bin/bash
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 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/build-doc
build-scripts/download-external-libs

View File

@ -8,7 +8,6 @@ installwin: all
mkdir $(DEST)/lib
mkdir $(DEST)/include
mkdir $(DEST)/include/qpdf
mkdir $(DEST)/doc
cp libqpdf/$(OUTPUT_DIR)/$(IMPORT_LIB_NAME) $(DEST)/lib
cp libqpdf/$(OUTPUT_DIR)/qpdf*.dll $(DEST)/bin
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 include/qpdf/*.h $(DEST)/include/qpdf
cp include/qpdf/*.hh $(DEST)/include/qpdf
if [ -f doc/qpdf-manual.pdf ]; then \
cp doc/qpdf-manual.pdf $(DEST)/doc; \
fi
if [ -d doc/html ]; then \
cp -r doc/html $(DEST)/doc; \
fi
if [ -d doc/singlehtml ]; then \
cp -r doc/singlehtml $(DEST)/doc; \
if [ -d doc ]; then \
cp -r doc $(DEST); \
fi

View File

@ -137,13 +137,5 @@ install: all install-libs
$(LIBTOOL) --mode=install ./install-sh \
qpdf/$(OUTPUT_DIR)/fix-qdf \
$(DESTDIR)$(bindir)/fix-qdf
if [ -f doc/qpdf-manual.pdf ]; then \
./install-sh -m 0644 doc/qpdf-manual.pdf $(DESTDIR)$(docdir); \
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
./install-sh -m 0644 README-doc.txt $(DESTDIR)$(docdir); \
./install-sh -m 0644 manual/$(OUTPUT_DIR)/*.1 $(DESTDIR)$(mandir)/man1

View File

@ -1,7 +1,7 @@
#!/usr/bin/env perl
#
# This program creates a source distribution of qpdf. For details,
# see README-maintainer.md.
# see README-maintainer.
#
require 5.008;
@ -16,7 +16,6 @@ use File::Path qw(rmtree make_path);
my $whoami = basename($0);
my $tmp = $ENV{'TMPDIR'} || '/tmp';
my $run_tests = 1;
my $keep_tmp = 0;
my $ci_mode = 0;
my $version = undef;
@ -24,7 +23,7 @@ foreach my $arg (@ARGV)
{
if ($arg eq '--no-tests')
{
$run_tests = 0;
# ignore for compatibility
}
elsif ($arg eq '--keep-tmp')
{
@ -93,19 +92,8 @@ if ($version_error)
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);
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");
rename "$distname.tar.gz-candidate", $distfile or die;

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.

View File

@ -6,7 +6,10 @@ HTML_TARGET := $(HTML_OUT)/index.html
PDF_OUT := $(DOC_OUT)/latex
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)
TARGETS_manual += $(HTML_TARGET) $(S_HTML_TARGET)
endif
@ -22,23 +25,31 @@ MANUAL_DEPS = $(wildcard manual/*.rst) manual/conf.py
# the error "_pickle.UnpicklingError: pickle data was truncated"
$(HTML_TARGET): $(MANUAL_DEPS)
$(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)
$(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)
$(SPHINX) -M latexpdf manual $(DOC_OUT) -W
mkdir -p doc
cp $(PDF_TARGET) doc/qpdf-manual.pdf
doc/%.1: manual/%.1.in
mkdir -p doc
sed -e 's:@PACKAGE_VERSION@:$(PACKAGE_VERSION):g' \
-e 's:@docdir@:$(docdir):g' \
< $< > $@
$(DOC_OUT)/%.1: manual/%.1.in
sed -e 's:@PACKAGE_VERSION@:$(PACKAGE_VERSION):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

View File

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

View File

@ -14,8 +14,6 @@ the same file with stream lengths, cross-reference table entries, and
object stream offset tables regenerated.
.PP
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
@docdir@/qpdf-manual.pdf. The latest version of the documentation can
be found at https://qpdf.readthedocs.io.
the qpdf manual, which can be found at https://qpdf.readthedocs.io.
.SH "SEE ALSO"
qpdf(1)

View File

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

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
ghostscript.
Pre-built documentation is distributed with qpdf, so you should
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.
For information on building the documentation, see :ref:`build-doc`.
.. _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
: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 Providers
@ -298,46 +308,3 @@ provide their own implementations for basic filters like
Implementing the registration functions and internal storage of
registered providers was also easier using C++-11's functional
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.

View File

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

View File

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

View File

@ -21,8 +21,6 @@ This program should not be used as a general purpose compression
tool. Use something like gzip(1) instead.
.PP
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
version of the documentation can be found at
https://qpdf.readthedocs.io.
at https://qpdf.readthedocs.io.
.SH "SEE ALSO"
qpdf(1), gzip(1)