mirror of
https://github.com/qpdf/qpdf.git
synced 2024-12-22 02:49:00 +00:00
Update documentation build/installation
This commit is contained in:
Jay Berkenbilt
parent
eb20b4d0cb
commit
426b4ce856
37
.github/workflows/main.yml
vendored
37
.github/workflows/main.yml
vendored
@ -19,21 +19,20 @@ on:
|
||||
# have reliable testing.
|
||||
- cron: '12 4 * * 5'
|
||||
jobs:
|
||||
Distfiles:
|
||||
# Generate distfiles.zip, which is a prerequisite for the mac and
|
||||
# Windows builds. Only the mac and Windows builds actually "need"
|
||||
# it, but declaring all the jobs to need it forces it to run
|
||||
# first.
|
||||
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.
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: 'Create distfiles.zip'
|
||||
run: build-scripts/make-distfiles
|
||||
- name: 'Run pre-build steps'
|
||||
run: build-scripts/prebuild
|
||||
- name: 'Upload extra distribution files'
|
||||
uses: actions/upload-artifact@v1
|
||||
with:
|
||||
name: distfiles
|
||||
path: distfiles.zip
|
||||
name: doc
|
||||
path: doc.zip
|
||||
- name: 'Upload external libs'
|
||||
uses: actions/upload-artifact@v1
|
||||
with:
|
||||
@ -52,7 +51,7 @@ jobs:
|
||||
path: distribution
|
||||
Windows:
|
||||
runs-on: windows-latest
|
||||
needs: Distfiles
|
||||
needs: Prebuild
|
||||
strategy:
|
||||
fail-fast: false
|
||||
max-parallel: 4
|
||||
@ -64,10 +63,10 @@ jobs:
|
||||
shell: bash
|
||||
run: git config --global core.autocrlf input
|
||||
- uses: actions/checkout@v2
|
||||
- name: 'Download distribution files'
|
||||
- name: 'Download documentation'
|
||||
uses: actions/download-artifact@v2
|
||||
with:
|
||||
name: distfiles
|
||||
name: doc
|
||||
path: .
|
||||
- name: 'Download external libs'
|
||||
uses: actions/download-artifact@v2
|
||||
@ -84,13 +83,9 @@ jobs:
|
||||
path: distribution
|
||||
macOS:
|
||||
runs-on: macos-latest
|
||||
needs: Distfiles
|
||||
needs: Prebuild
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: 'Download distribution files'
|
||||
uses: actions/download-artifact@v2
|
||||
with:
|
||||
name: distfiles
|
||||
- name: 'Download external libs'
|
||||
uses: actions/download-artifact@v2
|
||||
with:
|
||||
@ -100,7 +95,7 @@ jobs:
|
||||
run: build-scripts/build-mac
|
||||
AppImage:
|
||||
runs-on: ubuntu-latest
|
||||
needs: Distfiles
|
||||
needs: Prebuild
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: 'Build AppImage'
|
||||
@ -112,21 +107,21 @@ jobs:
|
||||
path: distribution
|
||||
Linux32:
|
||||
runs-on: ubuntu-latest
|
||||
needs: Distfiles
|
||||
needs: Prebuild
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: 'Linux 32-bit'
|
||||
run: build-scripts/build-linux32
|
||||
Fuzzers:
|
||||
runs-on: ubuntu-latest
|
||||
needs: Distfiles
|
||||
needs: Prebuild
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: 'Build Fuzzer'
|
||||
run: build-scripts/build-fuzzer
|
||||
Sanitizers:
|
||||
runs-on: ubuntu-latest
|
||||
needs: Distfiles
|
||||
needs: Prebuild
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: 'Sanitizer Tests'
|
||||
|
||||
2
.gitignore
vendored
2
.gitignore
vendored
@ -5,8 +5,8 @@ autoconf.mk
|
||||
autom4te.cache/
|
||||
config.log
|
||||
config.status
|
||||
distfiles.zip
|
||||
doc
|
||||
doc.zip
|
||||
examples/build/
|
||||
external-libs
|
||||
fuzz/build/
|
||||
|
||||
9
Makefile
9
Makefile
@ -97,23 +97,16 @@ $(foreach B,$(BUILD_ITEMS),$(eval \
|
||||
clean_$(B): ; \
|
||||
$(RM) -r $(B)/$(OUTPUT_DIR)))
|
||||
|
||||
DISTFILES = doc/qpdf-manual.html doc/qpdf-manual.pdf
|
||||
distfiles.zip: $(DISTFILES)
|
||||
$(RM) distfiles.zip
|
||||
zip -r distfiles.zip $(DISTFILES) doc/_static
|
||||
|
||||
distclean: clean
|
||||
$(RM) -r autoconf.mk autom4te.cache config.log config.status libtool
|
||||
$(RM) libqpdf/qpdf/qpdf-config.h
|
||||
$(RM) manual/html.xsl
|
||||
$(RM) manual/print.xsl
|
||||
$(RM) doc/*.1
|
||||
$(RM) libqpdf.pc libqpdf.map
|
||||
|
||||
maintainer-clean: distclean
|
||||
$(RM) doc/qpdf-manual.*
|
||||
$(RM) -r install-mingw* install-msvc* external-libs
|
||||
$(RM) distfiles.zip
|
||||
$(RM) -rf doc
|
||||
|
||||
.PHONY: $(TEST_TARGETS)
|
||||
|
||||
|
||||
@ -119,7 +119,7 @@ RELEASE PREPARATION
|
||||
git --no-pager grep -i -n -P "copyright.*$(expr $(date +%Y) - 1).*berkenbilt"
|
||||
|
||||
Also update the copyright in these places:
|
||||
* manual
|
||||
* manual/conf.py
|
||||
* debian package -- search for copyright.*berkenbilt in debian/copyright
|
||||
* qtest-driver, TestDriver.pm in qtest source
|
||||
|
||||
@ -210,14 +210,12 @@ RELEASE PREPARATION
|
||||
* Make sure version numbers are consistent in the following locations:
|
||||
* configure.ac
|
||||
* libqpdf/QPDF.cc
|
||||
* manual/qpdf-manual.xml
|
||||
* manual/conf.py
|
||||
* qpdf/qpdf.cc
|
||||
`make_dist` verifies this consistency.
|
||||
|
||||
* Update release notes in manual. Look at diffs and ChangeLog.
|
||||
Update release date in `manual/qpdf-manual.xml`. Remember to
|
||||
ensure that the entities at the top of the document are consistent
|
||||
with the release notes for both version and release date.
|
||||
Update release date in `manual/release-notes.rst`.
|
||||
|
||||
* Add a release entry to ChangeLog: "x.y.z: release"
|
||||
|
||||
@ -327,7 +325,7 @@ Template for release notes:
|
||||
```
|
||||
This is qpdf version x.y.z. (Brief description)
|
||||
|
||||
For a full list of changes from previous releases, please see the [release notes](http://qpdf.sourceforge.net/files/qpdf-manual.html#release-notes). See also [README-what-to-download](./README-what-to-download.md) for details about the available source and binary distributions.
|
||||
For a full list of changes from previous releases, please see the [release notes](https://qpdf.sourceforge.io/doc/html/release-notes.html). See also [README-what-to-download](./README-what-to-download.md) for details about the available source and binary distributions.
|
||||
```
|
||||
|
||||
# Publish release
|
||||
@ -348,7 +346,7 @@ rsync -vrlcO ./ jay_berkenbilt,qpdf@frs.sourceforge.net:/home/frs/project/q/qp/q
|
||||
|
||||
(cd /tmp; mkdir -p z; cd z; \
|
||||
tar xf ~/Q/storage/releases/qpdf/qpdf/$version/qpdf-$version.tar.gz qpdf-$version/doc; \
|
||||
scp -p qpdf-$version/doc/qpdf-* jay_berkenbilt,qpdf@frs.sourceforge.net:htdocs/files/)
|
||||
rsync -avx --delete --force --exclude '*.1' qpdf-$version/doc/ jay_berkenbilt,qpdf@frs.sourceforge.net:htdocs/doc/)
|
||||
|
||||
* Upload the debian package and Ubuntu ppa backports.
|
||||
|
||||
|
||||
@ -68,7 +68,7 @@ The PDF file format used to rely on RC4 for encryption. Using 256-bit keys alway
|
||||
|
||||
# Building from a pristine checkout
|
||||
|
||||
When building qpdf from a pristine checkout from version control, generated documentation files are not present. You may either generate them (by passing `--enable-doc-maintenance` to `./configure` and satisfying the extra build-time dependencies) or obtain them from a released source package, which includes them. If you want to grab just the files that are in the source distribution but not in the repository, extract a source distribution in a temporary directory, and run `make CLEAN=1 distfiles.zip`. This will create a file called `distfiles.zip`, which can you can extract in a checkout of the source repository. This step is optional unless you are running make install and want the html and PDF versions of the documentation to be installed.
|
||||
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
|
||||
|
||||
|
||||
22
TODO
22
TODO
@ -1,8 +1,6 @@
|
||||
Next
|
||||
====
|
||||
|
||||
* Add spell check to CI
|
||||
|
||||
* High-level API/doc overhaul: #593
|
||||
|
||||
* Refactor test_driver.cc so that runtest is not one huge function.
|
||||
@ -19,24 +17,6 @@ Next
|
||||
thrown when an uninitialized trailer is accessed provides useful
|
||||
information. Test from the C API as well as the C++ API.
|
||||
|
||||
Doc conversion
|
||||
==============
|
||||
|
||||
Before release:
|
||||
|
||||
* Figure out what to do about the fact that the release notes are now
|
||||
at #release-notes instead of #ref.release-notes. This invalidates
|
||||
the link in all previous release announcements, but there's not much
|
||||
I can do about, and it doesn't seem worth fixing. Maybe mention it
|
||||
somewhere?
|
||||
* README-maintainer: Fix installation of documentation to website
|
||||
|
||||
Soon:
|
||||
|
||||
* :ref: -- would be nice if it were suitable for printed documentation
|
||||
* Decide about readthedocs; if using, with multiple versions/latest
|
||||
* Generate stuff (options, code samples, etc.) as needed
|
||||
|
||||
Documentation
|
||||
=============
|
||||
|
||||
@ -52,6 +32,8 @@ Documentation
|
||||
* See #530 -- add an appendix explaining PDF encryption in general
|
||||
plus how it's handled by qpdf. Or maybe this should go on the wiki.
|
||||
|
||||
* Decide about readthedocs including supporting multiple released
|
||||
versions of the docs and docs from main.
|
||||
|
||||
Document-level work
|
||||
===================
|
||||
|
||||
@ -8,9 +8,6 @@ cd jpeg-*
|
||||
make -k
|
||||
sudo make install
|
||||
cd ..
|
||||
if [ -f distfiles/distfiles.zip ]; then
|
||||
unzip distfiles/distfiles.zip
|
||||
fi
|
||||
./configure --enable-werror --enable-show-failed-test-output
|
||||
make -j$(nproc) -k
|
||||
make -k check
|
||||
|
||||
@ -20,7 +20,7 @@ if [[ $tool == mingw ]]; then
|
||||
elif [[ $tool == msvc ]]; then
|
||||
cl
|
||||
fi
|
||||
unzip distfiles.zip
|
||||
unzip doc.zip
|
||||
unzip qpdf-external-libs-bin.zip
|
||||
cwd=`pwd`
|
||||
PATH=$cwd/libqpdf/build:$PATH
|
||||
|
||||
@ -7,5 +7,6 @@ sudo apt-get -y install \
|
||||
python3-pip texlive-latex-extra latexmk inkscape imagemagick
|
||||
pip3 install sphinx
|
||||
./configure --enable-doc-maintenance
|
||||
make -j$(nproc) distfiles.zip
|
||||
make -j$(nproc) build_manual
|
||||
zip -r doc.zip doc/*html doc/*.pdf
|
||||
build-scripts/download-external-libs
|
||||
@ -11,6 +11,7 @@
|
||||
"afdh",
|
||||
"afdhph",
|
||||
"ageneration",
|
||||
"agogo",
|
||||
"aitems",
|
||||
"annots",
|
||||
"aobjid",
|
||||
@ -73,6 +74,7 @@
|
||||
"dctdecode",
|
||||
"decrypter",
|
||||
"deduplicating",
|
||||
"deps",
|
||||
"destdir",
|
||||
"dests",
|
||||
"devel",
|
||||
@ -80,7 +82,6 @@
|
||||
"diffutils",
|
||||
"directpagerefcount",
|
||||
"distclean",
|
||||
"distfiles",
|
||||
"ditems",
|
||||
"docbook",
|
||||
"docdir",
|
||||
@ -299,6 +300,7 @@
|
||||
"pluggable",
|
||||
"pngify",
|
||||
"poppler",
|
||||
"prebuild",
|
||||
"precheck",
|
||||
"prepended",
|
||||
"prepending",
|
||||
|
||||
@ -17,11 +17,12 @@ 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.html ]; then \
|
||||
mkdir $(DEST)/doc/_static; \
|
||||
cp doc/qpdf-manual.html $(DEST)/doc; \
|
||||
cp doc/_static/* $(DEST)/doc/_static; \
|
||||
fi
|
||||
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; \
|
||||
fi
|
||||
|
||||
@ -121,8 +121,6 @@ install-libs: build_libqpdf
|
||||
# NOTE: If installing any new executables, remember to update the
|
||||
# lambda layer code in build-scripts/build-appimage.
|
||||
|
||||
# NOTE: See comments in manual/build.mk about html documentation.
|
||||
|
||||
# Ensure that installwin in make/installwin.mk is consistent with
|
||||
# this.
|
||||
|
||||
@ -139,12 +137,13 @@ install: all install-libs
|
||||
$(LIBTOOL) --mode=install ./install-sh \
|
||||
qpdf/$(OUTPUT_DIR)/fix-qdf \
|
||||
$(DESTDIR)$(bindir)/fix-qdf
|
||||
if [ -f doc/qpdf-manual.html ]; then \
|
||||
./mkinstalldirs -m 0755 $(DESTDIR)$(docdir)/_static; \
|
||||
./install-sh -m 0644 doc/qpdf-manual.html $(DESTDIR)$(docdir); \
|
||||
./install-sh -m 0644 doc/_static/* $(DESTDIR)$(docdir)/_static; \
|
||||
fi
|
||||
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
|
||||
|
||||
@ -8,10 +8,10 @@ PDF_TARGET := $(PDF_OUT)/qpdf.pdf
|
||||
|
||||
TARGETS_manual := doc/qpdf.1 doc/fix-qdf.1 doc/zlib-flate.1
|
||||
ifeq ($(BUILD_HTML),1)
|
||||
TARGETS_manual += doc/qpdf-manual.html $(HTML_TARGET)
|
||||
TARGETS_manual += $(HTML_TARGET) $(S_HTML_TARGET)
|
||||
endif
|
||||
ifeq ($(BUILD_PDF),1)
|
||||
TARGETS_manual += doc/qpdf-manual.pdf
|
||||
TARGETS_manual += $(PDF_TARGET)
|
||||
endif
|
||||
|
||||
MANUAL_DEPS = $(wildcard manual/*.rst) manual/conf.py
|
||||
@ -22,33 +22,20 @@ 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
|
||||
|
||||
# This depends on sphinx-build's singlehtml target creating index.html
|
||||
# and a _static directory. If that changes, this code has to be
|
||||
# adjusted. It will also be necessary to adjust the install target in
|
||||
# make/libtool.mk.
|
||||
doc/qpdf-manual.html: $(S_HTML_TARGET)
|
||||
mkdir -p doc
|
||||
@if [ "$(shell find $(S_HTML_OUT)/ -mindepth 1 -type d -print)" != \
|
||||
"$(S_HTML_OUT)/_static" ]; then \
|
||||
echo "***"; \
|
||||
echo Expected only directory in $(S_HTML_OUT) to be _static; \
|
||||
echo "***"; \
|
||||
false; \
|
||||
fi
|
||||
cp $< $@
|
||||
mkdir -p doc/_static
|
||||
cp -p $(S_HTML_OUT)/_static/* doc/_static
|
||||
|
||||
doc/qpdf-manual.pdf: $(PDF_TARGET)
|
||||
mkdir -p doc
|
||||
cp $< $@
|
||||
cp $(PDF_TARGET) doc/qpdf-manual.pdf
|
||||
|
||||
doc/%.1: manual/%.1.in
|
||||
mkdir -p doc
|
||||
|
||||
@ -14,5 +14,5 @@ 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@/qpdf-manual.html or
|
||||
the qpdf manual, which can be found in @docdir@/html/index.html or
|
||||
@docdir@/qpdf-manual.pdf.
|
||||
|
||||
@ -64,7 +64,7 @@ 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>`__. To build the PDF version of the
|
||||
documentation, you need `pdflatex`, `latexmk`, and a fairly complete
|
||||
documentation, you need ``pdflatex``, ``latexmk``, and a fairly complete
|
||||
LaTeX installation. Detailed requirements can be found in the Sphinx
|
||||
documentation.
|
||||
|
||||
|
||||
@ -16,4 +16,4 @@ 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@/qpdf-manual.html or @docdir@/qpdf-manual.pdf.
|
||||
@docdir@/html/index.html or @docdir@/qpdf-manual.pdf.
|
||||
|
||||
@ -7,6 +7,25 @@ For a detailed list of changes, please see the file
|
||||
:file:`ChangeLog` in the source distribution.
|
||||
|
||||
10.5.0: XXX Month dd, YYYY
|
||||
- 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.
|
||||
|
||||
- The documentation sources have been switched from docbook to
|
||||
reStructuredText processed with `Sphinx
|
||||
<https://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.
|
||||
|
||||
- Library Enhancements
|
||||
|
||||
- Since qpdf version 8, using object accessor methods on an
|
||||
@ -58,16 +77,6 @@ For a detailed list of changes, please see the file
|
||||
|
||||
- Add ``qpdf_oh_get_type_code`` and ``qpdf_oh_get_type_name``.
|
||||
|
||||
- Documentation change
|
||||
|
||||
- The documentation sources have been switched from docbook to
|
||||
reStructuredText processed with `Sphinx
|
||||
<https://sphinx-doc.org>`__. This is mostly transparent (other
|
||||
than format change) with the exception that all section links
|
||||
have changed. What used to be `#ref.something` is now
|
||||
`#something`. A top-to-bottom review of the documentation is
|
||||
planned for an upcoming release.
|
||||
|
||||
10.4.0: November 16, 2021
|
||||
- Handling of Weak Cryptography Algorithms
|
||||
|
||||
|
||||
@ -21,6 +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@/qpdf-manual.html or @docdir@/qpdf-manual.pdf.
|
||||
in @docdir@/html/index.html or @docdir@/qpdf-manual.pdf.
|
||||
.SH "SEE ALSO"
|
||||
qpdf(1), gzip(1)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user