docs/59044: doc.docbook.mk does not properly handle a source document already in XML format.

[Michael Edenfield]

>Number:         59044
>Category:       docs
>Synopsis:       doc.docbook.mk does not properly handle a source document already in XML format.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri Nov 07 14:40:09 PST 2003
>Closed-Date:
>Last-Modified:
>Originator:     Michael Edenfield
>Release:        FreeBSD 5.1-CURRENT i386
>Organization:
>Environment:
System: FreeBSD wombat.localnet 5.1-CURRENT FreeBSD 5.1-CURRENT #7: Sun Aug 24 21:35:57 EDT 2003 root at wombat.localnet:/usr/obj/usr/src/sys/ATHLON i386

>Description:

The documentation project makefiles are set up to allow the author
to apply XSL stylesheets instead of DSSSL stylesheet, and to use
DocBook 4.2 in XML format.  However, the makefiles assume that the
source document is in SGML format and needs to be converted to XML
format first.

This step itself is actually broken, as it assumes the document
has a root node of <book>, which is not always the case.  As it
stands, there's no way around this problem because using a pre-
make XML file fails for the reason below.

If the source document is already in XML format, this step is not
needed, and in fact causes a cyclic dependancy of the master
document on itself.

With this patch applied, one can use either the XML or SGML forms
of the DocBook DTD.

The patch also fixes a bug in the XSLT processing which fails to 
generate the HTML.manifest document, even though it assumes the 
file is present during `make clean` and while running tidy.


>How-To-Repeat:
--- Makefile:
DOC= article
DOCBOOKSUFFIX= xml
STYLESHEET_TYPE= xsl
SRCS= article.xml
.include "/usr/doc/share/mk/doc.project.mk"

~: $ make
Graph cycles through article.xml.

>Fix:


--- docbook.patch begins here ---
--- doc.docbook.mk.orig	Thu Oct  2 15:46:49 2003
+++ doc.docbook.mk	Fri Nov  7 17:19:50 2003
@@ -349,7 +349,11 @@
 .endif
 
 .if (${STYLESHEET_TYPE} == "xsl")
+.if ${DOCBOOKSUFFIX} != "xml"
 CLEANFILES+= ${DOC}.xml .sxerr
+.else
+CLEANFILE+= .sxerr
+.endif
 .endif
 
 .if (${LOCAL_CSS_SHEET} != ${CSS_SHEET}) && \
@@ -421,10 +425,14 @@
 #
 # Better approaches to handling this would be most welcome
 
+# If our master doc is already ${DOC}.xml then we don't need this next 
+# part.  In fact, it causes a circular graph reference.
+.if ${DOCBOOKSUFFIX} != "xml"
 ${DOC}.xml: ${SRCS}
 	echo '<!DOCTYPE book SYSTEM "/usr/local/share/xml/docbook/4.2/docbookx.dtd">' > ${DOC}.xml
 	${SX} -xlower -xndata ${MASTERDOC} 2> .sxerr | tail -n +2 >> ${DOC}.xml 
 	@-grep -v 'reference to internal SDATA entity' .sxerr
+.endif
 
 # HTML-SPLIT -------------------------------------------------------------
 
@@ -436,8 +444,8 @@
 .elif ${STYLESHEET_TYPE} == "xsl"
 index.html: ${DOC}.xml ${LOCAL_IMAGES_LIB} ${LOCAL_IMAGES_PNG} \
 	${INDEX_SGML} ${HTML_SPLIT_INDEX} ${LOCAL_CSS_SHEET}
-	${XSLTPROC} --param freebsd.output.html.images "'1'" ${XSLHTMLCHUNK} \
-		${DOC}.xml
+	${XSLTPROC} --param generate.manifest "'1'" --param freebsd.output.html.images "'1'" \
+		${XSLHTMLCHUNK} ${DOC}.xml
 .endif
 .if !defined(NO_TIDY)
 	-${TIDY} ${TIDYOPTS} $$(${XARGS} < HTML.manifest)
--- docbook.patch ends here ---

>Release-Note:
>Audit-Trail:
>Unformatted: