From kutulu@kutulu.org  Fri Nov  7 14:32:21 2003
Return-Path: <kutulu@kutulu.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id B577016A4CE
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  7 Nov 2003 14:32:21 -0800 (PST)
Received: from basement.kutulu.org (pcp03610121pcs.longhl01.md.comcast.net [68.49.239.235])
	by mx1.FreeBSD.org (Postfix) with ESMTP id E915943FBD
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  7 Nov 2003 14:32:20 -0800 (PST)
	(envelope-from kutulu@kutulu.org)
Received: from wombat.localnet (wombat.localnet [192.168.69.3])
	by basement.kutulu.org (Postfix) with ESMTP id D01F3AA38
	for <FreeBSD-gnats-submit@freebsd.org>; Fri,  7 Nov 2003 17:32:17 -0500 (EST)
Received: by wombat.localnet (Postfix, from userid 1001)
	id BAD5DB855; Fri,  7 Nov 2003 17:31:37 -0500 (EST)
Message-Id: <20031107223137.BAD5DB855@wombat.localnet>
Date: Fri,  7 Nov 2003 17:31:37 -0500 (EST)
From: Michael Edenfield <kutulu@kutulu.org>
Reply-To: Michael Edenfield <kutulu@kutulu.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: doc.docbook.mk does not properly handle a source document already in XML format.
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         59044
>Category:       docs
>Synopsis:       [patch] doc.docbook.mk does not properly handle a source document already in XML format.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    gabor
>State:          closed
>Quarter:        
>Keywords:       all
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Fri Nov 07 14:40:09 PST 2003
>Closed-Date:    Fri Sep 14 14:57:55 UTC 2012
>Last-Modified:  Fri Sep 14 14:57:55 UTC 2012
>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@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:
State-Changed-From-To: open->closed 
State-Changed-By: gabor 
State-Changed-When: Fri Sep 14 14:56:37 UTC 2012 
State-Changed-Why:  
With time the SGML format became obsolete and now we only 
support XML.  Thanks for taking your time to send a patch, though! 


Responsible-Changed-From-To: freebsd-doc->gabor 
Responsible-Changed-By: gabor 
Responsible-Changed-When: Fri Sep 14 14:56:37 UTC 2012 
Responsible-Changed-Why:  
Track. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=59044 
>Unformatted:
