diff options
Diffstat (limited to 'manual/installation.rst')
-rw-r--r-- | manual/installation.rst | 69 |
1 files changed, 18 insertions, 51 deletions
diff --git a/manual/installation.rst b/manual/installation.rst index 197977e7..0bd13e31 100644 --- a/manual/installation.rst +++ b/manual/installation.rst @@ -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. |