From c3fae92bb43e3ece6c723a85b6b65fe7b67633ed Mon Sep 17 00:00:00 2001
From: Daira Hopwood <daira@jacaranda.org>
Date: Sat, 24 Mar 2018 09:10:32 +0000
Subject: [PATCH] Support for building size-optimized PDFs, and other Makefile
 and README improvements.

Signed-off-by: Daira Hopwood <daira@jacaranda.org>
---
 protocol/Makefile   | 29 +++++++++++++++++++++++++++++
 protocol/README.rst | 41 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/protocol/Makefile b/protocol/Makefile
index df96607b..0d56e4e1 100644
--- a/protocol/Makefile
+++ b/protocol/Makefile
@@ -70,3 +70,32 @@ clean:
               protocol.aux protocol.out protocol.log protocol.bcf protocol.run.xml protocol.fls protocol.fdb_latexmk \
               sapling.dvi  sapling.pdf  sapling.bbl  sapling.blg  sapling.brf      sapling.toc \
               sapling.aux  sapling.out  sapling.log  sapling.bcf  sapling.run.xml  sapling.fls  sapling.fdb_latexmk
+
+optimizer-installed.flag:
+	# Nail down git commits to make backdooring somewhat harder.
+	git clone https://github.com/pts/sam2p.git
+	cd sam2p && git reset --hard a2d7819107324faf7b0904fc7074f7dd4a0e16c7 && $(MAKE)
+	git clone https://github.com/pts/tif22pnm.git
+	cd tif22pnm && git reset --hard 22217c1a3ea355a899e9c7c79903488ca13d1dfe && $(MAKE)
+	git clone https://github.com/pts/pdfsizeopt.git
+	cd pdfsizeopt && git reset --hard 47a03403d70f6975888cee966858bebc51b76463
+	touch optimizer-installed.flag
+
+.PHONY: clean-optimizer
+clean-optimizer:
+	rm -rf sam2p tif22pnm pdfsizeopt optimizer-installed.flag
+
+.PHONY: optimize-pdf
+optimize-pdf: optimizer-installed.flag
+	PATH="${PATH}:$(CURDIR)/sam2p:$(CURDIR)/tif22pnm" pdfsizeopt/pdfsizeopt --do-require-image-optimizers=no \
+              protocol.pdf protocol-opt.pdf
+	mv -f protocol-opt.pdf protocol.pdf
+
+.PHONY: optimize-sapling
+optimize-sapling: optimizer-installed.flag
+	PATH="${PATH}:$(CURDIR)/sam2p:$(CURDIR)/tif22pnm" pdfsizeopt/pdfsizeopt --do-require-image-optimizers=no \
+              sapling.pdf sapling-opt.pdf
+	mv -f sapling-opt.pdf sapling.pdf
+
+.PHONY: optimized
+optimized: pdf sapling optimize-pdf optimize-sapling
diff --git a/protocol/README.rst b/protocol/README.rst
index 81fb29e9..c5c087c9 100644
--- a/protocol/README.rst
+++ b/protocol/README.rst
@@ -6,4 +6,43 @@ Build dependencies on Debian-based systems include, at least:
 
 .. code::
 
-   apt-get install texlive texlive-science texlive-fonts-extra texlive-generic-recommended texlive-bibtex-extra biber latexmk
+   apt-get install texlive texlive-science texlive-fonts-extra \
+     texlive-generic-recommended texlive-bibtex-extra biber latexmk
+
+
+Building
+--------
+
+Use:
+
+* ``make pdf`` to make the current protocol specification (``protocol.pdf``);
+* ``make sapling`` to make the draft specification for the Overwinter and
+  Sapling upgrades (``sapling.pdf``).
+
+By default these use ``latexmk``, which does not work on all systems.
+Use ``make nolatexmk-pdf`` or ``make nolatexmk-sapling`` if you run into
+problems with ``latexmk``, but that is not the preferred way of building
+because it may not run ``pdflatex`` enough times.
+
+There is also support for using the incremental (``-pvc``) mode of
+``latexmk`` to automatically rebuild when changes in the source files
+are detected: ``make pvcpdf`` or ``make pvcsapling``.
+Manual intervention is still needed when there are LaTeX errors.
+
+
+Optimizing PDF size
+-------------------
+
+Optionally, you can use `Péter Szabó <https://github.com/pts>`_'s
+``pdfsizeopt`` program to optimize the size of the resulting PDF files.
+
+Run ``make optimized`` to rebuild both PDFs and then optimize them.
+This will probably only work on Linux. The first time this is run it
+will automatically clone and build the necessary dependencies (pinned
+by ``git`` hash) from GitHub.
+
+Alternatively, you can run ``make optimize-pdf`` or ``make optimize-sapling``
+to optimize just ``protocol.pdf`` or ``sapling.pdf`` respectively.
+
+This gives a size saving of about 50% for ``protocol.pdf``, and
+40% for ``sapling.pdf``.