svn commit - mysqldoc@docsrva: r4995 - in trunk: . make.d tools xsl.d

[paul]

Author: paul
Date: 2007-02-20 02:15:50 +0100 (Tue, 20 Feb 2007)
New Revision: 4995

Log:
 r16534@frost:  paul | 2007-02-19 18:24:32 -0600
 Various modifications related to handling of TOC numbering and
 cross references when formatting only part of a larger document.
 Remove no longer needed scripts, XSL transforms, make target rules, variables.


Removed:
   trunk/tools/chapterfmt.pl
   trunk/tools/copy-if-changed
   trunk/xsl.d/cur-sect-num.xsl
   trunk/xsl.d/make-toc-entries.xsl
   trunk/xsl.d/resolve-xref.xsl
Modified:
   trunk/make.d/vars-docbook
   trunk/make.d/xml-pdf
   trunk/make.d/xml-remark
   trunk/make.d/xml-titles
   trunk/make.d/xml-toc

Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:20104
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:16410
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:14593
   + 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:20104
7d8d2c4e-af1d-0410-ab9f-b038ce55645b:/mysqldoc-local/mysqldoc:16534
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:14218
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:14593


Modified: trunk/make.d/vars-docbook
===================================================================
--- trunk/make.d/vars-docbook	2007-02-19 23:08:14 UTC (rev 4994)
+++ trunk/make.d/vars-docbook	2007-02-20 01:15:50 UTC (rev 4995)
Changed blocks: 6, Lines Added: 11, Lines Deleted: 26; 2913 bytes

@@ -6,9 +6,9 @@
 
 DOC_LANG ?= en
 
-# Basename of the main document .xml file.  This must be overridden in
-# the Makefile for any document that needs to generate -toc-entries.xml
-# files.
+# Basename of the main document .xml file.  This must be set in the
+# the Makefile for any document that uses rules for which the primary
+# dependency is the main document.
 
 MAIN_DOC_BASENAME ?= YOU_MUST_DEFINE_MAIN_DOC_BASENAME
 

@@ -27,8 +27,8 @@
 
 MAP_REMARK_TO_PARA ?= 0
 
-# Whether to generate <toc-section-type> element in toc-entries files.
-# Normally, this is 1; we set it to 0 in Makefiles for some older documents.
+#  Whether xrefs resolved by target-resolvers.xsl should include the
+# section type ("Chapter", "Appendix", "Section", etc.).
 
 GENERATE_TOC_SECTION_TYPE ?= 1
 

@@ -62,9 +62,7 @@
 # --novalid: None of the transformation targets require validation (we assume
 # the input has been validated).  
 # XSLTPROC_EXTRA_FLAGS: normally unset, but you can pass a value for it
-# on the make command line to add extra xsltproc flags.  This is used by
-# the chapterfmt.pl script to set the rootid parameter that tells xsltproc
-# to format a single chapter.
+# on the make command line to add extra xsltproc flags.
 
 XSLTPROC = xsltproc --xinclude --novalid $(XSLTPROC_EXTRA_FLAGS)
 

@@ -133,16 +131,10 @@
 
 HTML_TO_TEXT ?= lynx -dump -width=70
 
-# Script that uses entire document but formats output just for a given
-# chapter (or section).
+# Script that gets the root id attribute from an XML file
 
-CHAPTERFMT = $(TOOLS_DIR)/chapterfmt.pl
+GET_ROOTID = $(TOOLS_DIR)/get-rootid.pl
 
-# Script that updates $2 from $1 only if $1 is different from $2
-# (helps prevent unnecessary updates to file-modification time of $2)
-
-COPY_IF_CHANGED = $(TOOLS_DIR)/copy-if-changed
-
 # ----------------------------------------------------------------------
 # Transforms
 

@@ -167,20 +159,12 @@
 	$(DBK_PREP_XSL) \
 	$(XSL_DIR)/map-refentry.xsl
 
-# Transform that generates file containing all the TOC entries (section
-# numbers and titles)
-
-TOC_ENTRIES_XSL = $(XSL_DIR)/make-toc-entries.xsl
-TOC_ENTRIES_XSL_DEPS = \
-	$(TOC_ENTRIES_XSL) \
-	$(XSL_DIR)/target-resolvers.xsl
-
 # Transform that makes table of contents for input document
 
 TOC_XSL = $(XSL_DIR)/make-toc.xsl
 TOC_XSL_DEPS = \
 	$(TOC_XSL) \
-	$(XSL_DIR)/cur-sect-num.xsl
+	$(XSL_DIR)/target-resolvers.xsl
 
 # Transform that replaces <xref> elements with the literal
 # cross-reference text.

@@ -283,7 +267,8 @@
 
 MYSQL_FO_XSL = $(XSL_DIR)/mysql-fo.xsl
 MYSQL_FO_XSL_DEPS = $(MYSQL_FO_XSL) \
-	$(XSL_DIR)/mysql.formalpara.templates.fo.xsl
+	$(XSL_DIR)/mysql.formalpara.templates.fo.xsl \
+	$(XSL_DIR)/mysql.titlepage.templates.fo.xsl
 
 # Transform that extracts <remark> elements
 


Modified: trunk/make.d/xml-pdf
===================================================================
--- trunk/make.d/xml-pdf	2007-02-19 23:08:14 UTC (rev 4994)
+++ trunk/make.d/xml-pdf	2007-02-20 01:15:50 UTC (rev 4995)
Changed blocks: 3, Lines Added: 110, Lines Deleted: 2; 5185 bytes

@@ -1,6 +1,11 @@
 # Convert DocBook -> PDF (letter/A4)
 # (Language sensitive)
 
+# The main transform is preceded by one that strips remarks to avoid
+# certain linebreak problems. If it's desired to retain remarks in
+# the output, convert them to special paras by setting MAP_REMARK_TO_PARA
+# to 1 in the main Makefile.
+
 # Do not delete these files when they are generated as intermediates
 # for a final target.  They are deleted by "make clean".
 

@@ -10,6 +15,20 @@
 # for page margins, note that you can't set left and right as they
 # will be overwritten. The default value is 1in for both.
 
+# These rules can be used for either the full document or for subsidiary
+# files that are part of the full document.  However, for subsidiary files,
+# the TOC numbering will begin at chapter one and cross-references may be
+# inaccurate.
+
+%.a4.fo: %-prepped.xml $(MYSQL_FO_XSL_DEPS) $(STRIP_REMARKS_XSL_DEPS)
+	$(XSLTPROC) \
+		--output - $(STRIP_REMARKS_XSL) $< \
+	| $(XSLTPROC) \
+		--stringparam l10n.gentext.default.language $(DOC_LANG) \
+		--stringparam paper.type A4 \
+		--output $@-tmp $(MYSQL_FO_XSL) -
+	mv $@-tmp $@
+
 %.fo: %-prepped.xml $(MYSQL_FO_XSL_DEPS) $(STRIP_REMARKS_XSL_DEPS)
 	$(XSLTPROC) \
 		--output - $(STRIP_REMARKS_XSL) $< \

@@ -18,15 +37,104 @@
 		--output $@-tmp $(MYSQL_FO_XSL) -
 	mv $@-tmp $@
 
-%.a4.fo: %-prepped.xml $(MYSQL_FO_XSL_DEPS) $(STRIP_REMARKS_XSL_DEPS)
+# These rules are intended for formatting subsidiary files that are part
+# of a larger document:
+# - The dependency is the full document, not just the file itself.
+# - The root id of the file is passed to the FO transform so that only its
+#   content is formatted (not that of the entire document), but the TOC
+#   numbering will be correct with respect to the entire document.
+# The effect is that the transform will take longer than for the preceding
+# rules but the TOC and cross-reference numbering will be that of the full
+# document.
+
+# Generally, the file will represent an individual chapter, so the rules
+# are invoked as "make chapter-filename.pdf" or "make chapter-filename.a4.pdf"
+# but the part- and section- prefixes are recognized as well, in case you
+# want to format a file that represents a part or section. (The action taken
+# is the same, but the output file will have a name that better reflects
+# how much of the main document the input file contains.)
+
+# Because these rules are dependent on MAIN_DOC_BASE_NAME, they are NOT
+# SUITABLE for cases where a directory contains multiple "main documents."
+# An instance of this is refman-common, where the various connector
+# documents each are formatted as though they are standalone documents.
+
+# The transform tself is slightly different as well: It forces a TOC
+# to be generated for chapter units.
+
+.PRECIOUS: chapter-%.fo
+.PRECIOUS: chapter-%.a4.fo
+.PRECIOUS: part-%.fo
+.PRECIOUS: part-%.a4.fo
+.PRECIOUS: section-%.fo
+.PRECIOUS: section-%.a4.fo
+
+chapter-%.a4.fo part-%.a4.fo section-%.a4.fo: \
+		$(MAIN_DOC_BASENAME)-prepped.xml \
+		$(MYSQL_FO_CHAPTER_XSL_DEPS) \
+		$(STRIP_REMARKS_XSL_DEPS)
 	$(XSLTPROC) \
 		--output - $(STRIP_REMARKS_XSL) $< \
 	| $(XSLTPROC) \
+		--stringparam rootid "`$(GET_ROOTID) $*.xml`" \
 		--stringparam l10n.gentext.default.language $(DOC_LANG) \
 		--stringparam paper.type A4 \
-		--output $@-tmp $(MYSQL_FO_XSL) -
+		--output $@-tmp $(MYSQL_FO_CHAPTER_XSL) -
 	mv $@-tmp $@
 
+chapter-%.fo part-%.fo section-%.fo: \
+		$(MAIN_DOC_BASENAME)-prepped.xml \
+		$(MYSQL_FO_CHAPTER_XSL_DEPS) \
+		$(STRIP_REMARKS_XSL_DEPS)
+	$(XSLTPROC) \
+		--output - $(STRIP_REMARKS_XSL) $< \
+	| $(XSLTPROC) \
+		--stringparam rootid "`$(GET_ROOTID) $*.xml`" \
+		--stringparam l10n.gentext.default.language $(DOC_LANG) \
+		--output $@-tmp $(MYSQL_FO_CHAPTER_XSL) -
+	mv $@-tmp $@
+
+# Format given arbitrary node from entire document.
+
+.PRECIOUS: node-%.fo
+.PRECIOUS: node-%.a4.fo
+
+node-%.html: \
+		$(MAIN_DOC_BASENAME)-prepped.xml \
+		$(MYSQL_HTML_XSL_DEPS)
+	$(XSLTPROC) \
+		--stringparam rootid "$*" \
+		--stringparam l10n.gentext.default.language $(DOC_LANG) \
+		--output $@-tmp \
+		$(MYSQL_HTML_XSL) \
+		$<
+	mv $@-tmp $@
+
+node-%.a4.fo: \
+		$(MAIN_DOC_BASENAME)-prepped.xml \
+		$(MYSQL_FO_CHAPTER_XSL_DEPS) \
+		$(STRIP_REMARKS_XSL_DEPS)
+	$(XSLTPROC) \
+		--output - $(STRIP_REMARKS_XSL) $< \
+	| $(XSLTPROC) \
+		--stringparam rootid "$*" \
+		--stringparam l10n.gentext.default.language $(DOC_LANG) \
+		--stringparam paper.type A4 \
+		--output $@-tmp $(MYSQL_FO_CHAPTER_XSL) -
+	mv $@-tmp $@
+
+node-%.fo: \
+		$(MAIN_DOC_BASENAME)-prepped.xml \
+		$(MYSQL_FO_CHAPTER_XSL_DEPS) \
+		$(STRIP_REMARKS_XSL_DEPS)
+	$(XSLTPROC) \
+		--output - $(STRIP_REMARKS_XSL) $< \
+	| $(XSLTPROC) \
+		--stringparam rootid "$*" \
+		--stringparam l10n.gentext.default.language $(DOC_LANG) \
+		--output $@-tmp $(MYSQL_FO_CHAPTER_XSL) -
+	mv $@-tmp $@
+
 # Ignore error messages about hyphenation. FOP produces zillions of these
 # if it doesn't have hyphenation tables for a given language.
 # (Don't use grep to filter messages, because it returns non-zero if no


Modified: trunk/make.d/xml-remark
===================================================================
--- trunk/make.d/xml-remark	2007-02-19 23:08:14 UTC (rev 4994)
+++ trunk/make.d/xml-remark	2007-02-20 01:15:50 UTC (rev 4995)
Changed blocks: 1, Lines Added: 6, Lines Deleted: 4; 890 bytes

@@ -5,16 +5,18 @@
 # Extract <remark> elements
 
 %.remarks: %-remprepped.xml $(EXTRACT_REMARK_XSL_DEPS)
-	$(XSLTPROC) --output - $(EXTRACT_REMARK_XSL) $< | $(WRAP_REMARK) > $@
+	$(XSLTPROC) --output - $(EXTRACT_REMARK_XSL) $< | $(WRAP_REMARK) > $@-tmp
+	mv $@-tmp $@
 
 # Count <remark> elements
 
 %.remark-count: %-remprepped.xml $(COUNT_REMARK_XSL_DEPS)
-	$(XSLTPROC) --output $@ $(COUNT_REMARK_XSL) $<
+	$(XSLTPROC) --output $@-tmp $(COUNT_REMARK_XSL) $<
+	mv $@-tmp $@
 
 clean::
-	$(RM) *.remarks
-	$(RM) *.remark-count
+	$(RM) *.remarks *.remarks-tmp
+	$(RM) *.remark-count *.remark-count-tmp
 
 help::
 	@echo "make file.remarks         - extract <remark> elements from file.xml"


Modified: trunk/make.d/xml-titles
===================================================================
--- trunk/make.d/xml-titles	2007-02-19 23:08:14 UTC (rev 4994)
+++ trunk/make.d/xml-titles	2007-02-20 01:15:50 UTC (rev 4995)
Changed blocks: 1, Lines Added: 3, Lines Deleted: 2; 590 bytes

@@ -2,10 +2,11 @@
 # element that has a title and the text of the title
 
 %.titles: %.xml $(EXTRACT_TITLES_XSL_DEPS)
-	$(XSLTPROC) --output $@ $(EXTRACT_TITLES_XSL) $<
+	$(XSLTPROC) --output $@-tmp $(EXTRACT_TITLES_XSL) $<
+	mv $@-tmp $@
 
 clean::
-	$(RM) *.titles
+	$(RM) *.titles *.titles-tmp
 
 help::
 	@echo "make file.titles          - convert file.xml to id/titles file"


Modified: trunk/make.d/xml-toc
===================================================================
--- trunk/make.d/xml-toc	2007-02-19 23:08:14 UTC (rev 4994)
+++ trunk/make.d/xml-toc	2007-02-20 01:15:50 UTC (rev 4995)
Changed blocks: 1, Lines Added: 4, Lines Deleted: 42; 2214 bytes

@@ -1,51 +1,13 @@
-# TOC and TOC-related target rules
+# TOC target rules
 
-# Generate table of contents entries (for resolving cross-references)
-
-# Do not delete these files when they are generated as intermediates
-# for a final target.  They are deleted by "make clean".
- 
-.PRECIOUS: toc-entries.tmp
-.PRECIOUS: toc-entries.xml
-
-# Generate the result as an intermediate file, and update the real
-# file only if there's a change.  This way, changes to chapter files
-# that don't result in TOC changes don't cause the toc-entries.xml
-# file to be updated.  (That saves all the rebuilds that otherwise
-# would result from just a last-modified date change even when the
-# content doesn't change.)
-
-# Note: MAIN_DOC_BASENAME *must* be set to the basename of the main
-# document file.  For example, if the main file is manual.xml or
-# book.xml, set MAIN_DOC_BASENAME to manual or book.
-
-# Note: For rules that use the toc-entries.xml file, refer to it using
-# $PWD so that XSL transforms that need to find toc-entries.xml
-# have an absolute pathname to work with. (Otherwise, they look in the
-# same directory in which they are located, and may not find the file.)
-
-# Full-document TOC entries file.  Use this for operations that need
-# to know about the TOC entries for any part of the the document.
-
-toc-entries.tmp: $(MAIN_DOC_BASENAME)-prepped.xml $(TOC_ENTRIES_XSL_DEPS)
-	$(XSLTPROC) \
-		--param generate.toc.section.type $(GENERATE_TOC_SECTION_TYPE) \
-		--output $@ $(TOC_ENTRIES_XSL) $<
-toc-entries.xml: toc-entries.tmp
-	$(COPY_IF_CHANGED) $< $@
-
 # Generate table of contents for a document
 
 %-toc.txt: %-prepped.xml $(TOC_XSL_DEPS)
-	$(XSLTPROC) --output $@ $(TOC_XSL) $<
+	$(XSLTPROC) --output $@-tmp $(TOC_XSL) $<
+	mv $@-tmp $@
 
 clean::
-	$(RM) toc-entries.xml
-	$(RM) *-toc.txt
+	$(RM) *-toc.txt *-toc.txt-tmp
 
-realclean::
-	$(RM) toc-entries.tmp
-
 help::
-	@echo "make toc-entries.xml      - produce table of contents entries"
 	@echo "make file-toc.txt         - produce table of contents from file.xml"