From d3467a2fcf207daec472c27015184daa5f4594dd Mon Sep 17 00:00:00 2001
From: Guillem Jover <guillem@debian.org>
Date: Sun, 26 Mar 2017 22:52:20 +0200
Subject: [PATCH 8/8] Make the upgrading-checklist a proper appendix of the
 policy manual

This integrates the upgrading checklist properly into the policy
manual, so that there are now navigation references and it appears
in the TOC.

As a side effect we get rid of the split HTML output because it would
contain just a single index.html file anyway, but keep compatibility
files for the one-page HTML and text outputs.
---
 .gitignore              |  1 -
 Makefile                | 16 ++--------------
 debian/rules            | 19 +++++++++++--------
 policy.xml              |  2 ++
 upgrading-checklist.xml | 37 ++++++-------------------------------
 5 files changed, 21 insertions(+), 54 deletions(-)

diff --git a/.gitignore b/.gitignore
index 66c32a5..a200169 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,7 +16,6 @@
 /policy.html/
 /stamp-build
 /stamp-binary
-/upgrading-checklist.html/
 /version.xml
 *-1.html
 *.html.tar.gz
diff --git a/Makefile b/Makefile
index 2df0ac0..cd4b124 100644
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,6 @@ include debian/rules
 policy.xml: version.xml
 menu-policy.xml: version.xml
 perl-policy.xml: version.xml
-upgrading-checklist.xml: version.xml
 
 XSLTPROC = xsltproc --nonet --xinclude
 XMLLINT  = xmllint --nonet --noout --postvalid --xinclude
@@ -16,8 +15,7 @@ $(MDWN_FILES:=.txt): %.txt: %.md
 $(MDWN_FILES:=.html): %.html: %.md
 	$(MDWN) $< > $@
 
-upgrading-checklist-1.html \
-upgrading-checklist.html/index.html: XSLPARAMS = --stringparam generate.toc ''
+upgrading-checklist-1.html: XSLPARAMS = --stringparam generate.toc ''
 
 %.validate: %
 	$(XMLLINT) $<
@@ -34,7 +32,7 @@ upgrading-checklist.html/index.html: XSLPARAMS = --stringparam generate.toc ''
 %.html.tar.gz: %.html/index.html
 	GZIP=-n9 tar -czf $(<:/index.html=.tar.gz) $(<:/index.html=)
 
-$(XML_FILES:=.txt): %.txt: %.xml
+$(XML_FILES:=.txt) $(XML_SPLIT_FILES:=.txt): %.txt: %.xml
 	$(XSLTPROC) $(XSLPARAMS) xsl/text.xsl $< > $@.html
 	links -dump $@.html | perl -pe 's/[\r\0]//g' > $@
 	rm -f $@.html
@@ -54,16 +52,6 @@ $(XML_FILES:=.txt): %.txt: %.xml
 %.pdf.gz: %.pdf
 	gzip -ncf9 $< > $@
 
-# This is a temporary hack to fold the upgrading-checklist into the Policy
-# HTML directory so that it can be deployed alongside Policy on
-# www.debian.org in a way that lets the cross-document links work properly.
-# The correct solution is to make upgrading-checklist an appendix of Policy,
-# which will probably be done as part of a general conversion to DocBook.
-policy.html.tar.gz:: policy.html/upgrading-checklist.html
-policy.html/upgrading-checklist.html: upgrading-checklist-1.html \
-				      policy.html/index.html
-	cp -p $< $@
-
 # convenience aliases :)
 html: policy.html/index.html
 html-1: policy-1.html
diff --git a/debian/rules b/debian/rules
index 33c06ab..a47ab60 100755
--- a/debian/rules
+++ b/debian/rules
@@ -18,7 +18,11 @@ LIBDIR	:= $(TMPTOP)/usr/share/doc-base
 
 # DocBook source files in the top-level directory.  We do some common actions
 # with each of these: build text, HTML, and one-page HTML output.
-XML_FILES   := policy menu-policy perl-policy upgrading-checklist
+XML_FILES   := policy menu-policy perl-policy
+
+# The upgrading-checklist used to be a document of its own, which was merged
+# with the conversion to DocBook. Keep backwards compatibility files.
+XML_SPLIT_FILES := upgrading-checklist
 
 XML_VERSION := copyright-format/version.xml debconf_spec/include/version.xml \
 	       version.xml
@@ -41,6 +45,8 @@ FHS_FILES   := fhs-2.3.html fhs-2.3.ps.gz fhs-2.3.txt.gz fhs-2.3.pdf.gz
 # handled separately.
 POLICY_FILES := $(XML_FILES:=.txt.gz)					\
 		$(XML_FILES:=-1.html)					\
+		$(XML_SPLIT_FILES:=.txt.gz)				\
+		$(XML_SPLIT_FILES:=-1.html)				\
 		virtual-package-names-list.txt	                        \
 		copyright-format/copyright-format-1.0.html		\
 		copyright-format/copyright-format-1.0.txt.gz		\
@@ -60,6 +66,8 @@ STAMPS_TO_CLEAN := stamp-binary stamp-build
 DIRS_TO_CLEAN   := $(XML_FILES:=.html) debian/tmp fhs
 FILES_TO_CLEAN  := $(XML_FILES:=.txt) $(XML_FILES:=.txt.gz)		\
 		   $(XML_FILES:=.html.tar.gz) $(XML_FILES:=-1.html)	\
+		   $(XML_SPLIT_FILES:=.txt) $(XML_SPLIT_FILES:=.txt.gz)	\
+		   $(XML_SPLIT_FILES:=-1.html)				\
 		   $(MDWN_FILES:=.html) $(MDWN_FILES:=.txt)		\
 		   policy.pdf.gz policy.ps.gz				\
 		   policy.pdf policy.ps policy.tpt policy.txt		\
@@ -89,6 +97,8 @@ stamp-build: $(MDWN_FILES:=.md)				\
 		$(XML_FILES:=.html.tar.gz) \
 		$(XML_FILES:=-1.html) \
 		$(XML_FILES:=.txt.gz) \
+		$(XML_SPLIT_FILES:=-1.html) \
+		$(XML_SPLIT_FILES:=.txt.gz) \
 		policy.ps.gz policy.pdf.gz
 	$(MAKE) $(MDWN_FILES:=.html) \
 		$(MDWN_FILES:=.txt)
@@ -149,13 +159,6 @@ stamp-binary: stamp-build
 		tar -C $(DOCDIR) -zxf $$file.html.tar.gz;	\
 	done
 #
-# Make upgrading-checklist-1.html a symlink to the copy in the policy.html
-# directory.  This is temporary until it becomes a proper appendix.
-#
-	rm -f $(DOCDIR)/upgrading-checklist-1.html
-	ln -s policy.html/upgrading-checklist.html \
-		$(DOCDIR)/upgrading-checklist-1.html
-#
 # Install doc-base files.
 #
 	@set -ex; for file in $(DESC_FILES); do			\
diff --git a/policy.xml b/policy.xml
index f901692..5848af1 100644
--- a/policy.xml
+++ b/policy.xml
@@ -10767,6 +10767,8 @@ it well.
 </para>
 </appendix>
 
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+            href="upgrading-checklist.xml" />
 
 </book>
 
diff --git a/upgrading-checklist.xml b/upgrading-checklist.xml
index f0dbd17..0241315 100644
--- a/upgrading-checklist.xml
+++ b/upgrading-checklist.xml
@@ -1,33 +1,13 @@
 <?xml version='1.0' encoding='utf-8'?>
 <!-- -*- DocBook -*- -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
     "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % versiondata SYSTEM "version.xml"> %versiondata;
 ]>
 
-<book lang="en">
+<appendix id="upgrading-checklist"><title>Upgrading checklist</title>
 
-<title>Policy checklist for upgrading your packages</title>
-
-<bookinfo>
-
-<authorgroup>
-<author><personname><firstname>Bill</firstname><surname>Allombert</surname></personname><email>ballombe@debian.org</email></author>
-<author><personname><firstname>Josip</firstname><surname>Rodin</surname></personname></author>
-<author><personname><firstname>Julian</firstname><surname>Gilbey</surname></personname></author>
-<author><personname><firstname>Russ</firstname><surname>Allbery</surname></personname><email>rra@debian.org</email></author>
-<author><personname><firstname>Manoj</firstname><surname>Srivastava</surname></personname><email>srivasta@debian.org</email></author>
-
-</authorgroup>
-<releaseinfo></releaseinfo>
-
-<pubdate>&date;</pubdate>
-
-
-</bookinfo>
-
-
-<chapter id="ch1"><title>About the checklist</title>
+<abstract>
+<title>About the checklist</title>
 <para>
 The checklist below has been created to simplify the upgrading process of old
 packages.  Note that this list is not "official"; it simply gives an indication
@@ -49,9 +29,8 @@ and then check out the Policy Manual for details.  If you are upgrading from
 Policy version &lt; 2.5.0, it may be easier to check through the whole of
 policy instead of picking your way through this list.
 </para>
-</chapter>
+</abstract>
 
-<chapter id="ch2"><title>The checklist</title>
 <section id="s-3.9.9.0"><title>Version 3.9.9.0</title>
 <para>
 Not Released Yet
@@ -3471,8 +3450,4 @@ Upstream changelog must be installed too
 </itemizedlist>
 </section>
 
-</chapter>
-
-
-</book>
-
+</appendix>
-- 
2.12.2.564.g063fe858b8

