Wireshark · Ethereal-dev: Re: [Ethereal-dev] Beginnings of automake in docbook directory

[Joerg Mayer <jmayer@xxxxxxxxx>]

Ulf,

On Sun, Feb 20, 2005 at 01:18:21PM +0100, Ulf Lamping wrote:
> But you seem to be on the way ...

Yes, and spent most of today fighting with the existing makefile, learning
a few basic things about xsltproc and catalogc. The result is a much simplified
dependency situation.
I've attached a patch which I ask you to test whether it works for you.
You need to apply the patch and remove the catalog.xml file.
I'll also include a commented version of the patch into the main body of
this mail.

> >Ulf: Is there any specific reason why  you do this:
> >edg_images:
> >       cp $(DOCBOOKXSL)/images/note.png ./edg_graphics
> >       cp $(DOCBOOKXSL)/images/tip.png ./edg_graphics
> >       cp $(DOCBOOKXSL)/images/warning.png ./edg_graphics
> >
> >In the makefile instead of just copying them over and chekcing them in?

a) After looking at the license of the package I'm no longer sure that we
   could distribute it under this license (I'm not sure about the contrary
   either)
b) It looks like you already checked them in (probably accidentally):
----
jmayer@egg:~/work/ethereal/trunk/docbook> svn log graphics/note.png
------------------------------------------------------------------------
r11433 | ulfl | 2004-07-19 18:59:49 +0200 (Mon, 19 Jul 2004) | 4 lines

The first draft of an updated "Ethereal User's Guide" redesigned and updated to the currentreleased Ethereal version 0.10.5.
As generation of output files is a bit tricky, please have a look at the Readme.txt file for instructions.

Please send comments and improvements.
------------------------------------------------------------------------


And now for the patch:
---------------------------------------
> -# if you need to change this, don't forget to change it in catalog.xml too
> -
> -DOCBOOKXSL="/usr/share/docbook-xsl"
> -# On SUSE 9.1 uncomment the following line:
> -#DOCBOOKXSL="/usr/share/xml/docbook/stylesheet/nwalsh/1.64.1"
> -# On SUSE 9.2 uncomment the following line:
> -#DOCBOOKXSL="/usr/share/xml/docbook/stylesheet/nwalsh/1.65.1"

Removing the DOCBOOKXSL variable becomes possible by also removing catalog.xml:
Background: Instead of hardcoding distribution specific paths to the places where
the different files are installed, distributions can provide a catalog file
that contains redirects from the official URLs to the locally installed copies.
Have a look at your Suse system at /etc/xml/catalog and the file it refers to.

This is, what "man xsltproc" has to say on the topic:
--------
--catalogs
  Use  the  SGML catalog specified in SGML_CATALOG_FILES to resolve the location
  of external entities. By default, xsltproc looks for the catalog specified in
  XML_CATALOG_FILES. If that is not specified, it uses /etc/xml/catalog.
--------

> -all: svn_version.xml eug edg 
> +all: eug edg 

Just undo my patch that was unnecessary as svn_version.xml is a dependency for each
doc build.
 
> -eug: eug_validate eug_pdf_a4 eug_html eug_html_chunked eug_chm 
> +eug: eug_validate eug_pdf_a4 eug_pdf_us eug_html eug_html_chunked eug_chm 

Build the letter documents as well, to allow testing.

> -eug_images:
> -	cp $(DOCBOOKXSL)/images/note.png ./graphics
> -	cp $(DOCBOOKXSL)/images/tip.png ./graphics
> -	cp $(DOCBOOKXSL)/images/warning.png ./graphics

In case we can't put the icons into the package, I have no real idea how to
handle this, as this image is never actually included directly.

> -eug_html: eug_images svn_version.xml
> +eug_html: svn_version.xml

Remove the eug_images dependencies from all documents

> eug_html: svn_version.xml
>         ...
> -	$(XSLTPROC) --nonet $(DOCBOOKXSL)/html/docbook.xsl user-guide.xml > eug_html/user-guide.html
> +	$(XSLTPROC) --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl user-guide.xml > eug_html/user-guide.html

This is the final step of getting rid of the DOCBOOKXSL hardcoded path: Use the official
URL and let the tools do the replacement.

> -eug_pdf_us: eug_images svn_version.xml
> +eug_pdf_us: svn_version.xml
>       ...
> -	$(XSLTPROC) --nonet custom_layer_pdf.xsl $(DOCBOOKXSL)/fo/docbook.xsl user-guide.xml > user-guide.fo
> -	$(FOP) user-guide.fo user-guide.pdf
> +	# $(XSLTPROC) --nonet custom_layer_pdf.xsl http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl user-guide.xml > user-guide-us.fo
> +	$(XSLTPROC) --nonet custom_layer_pdf.xsl user-guide.xml > user-guide-us.fo
> +	$(FOP) user-guide-us.fo user-guide-us.pdf

The letter format build failed until I removed the docbook.xsl, which is included
via custom_layer_pdf.xsl anyway.
 
-	mv htmlhelp.chm user-guide.chm
-	rm -r htmlhelp.hhp
-	rm -r toc.hhc
+	-mv htmlhelp.chm user-guide.chm
+	-rm -r htmlhelp.hhp
+	-rm -r toc.hhc

Enable test builds to continue with HHC set to true.

---------------------------------------
 

I hope that this patch will work on your Windows platform too or at least
can be made to work.

 ciao
      Joerg
-- 
Joerg Mayer                                           <jmayer@xxxxxxxxx>
We are stuck with technology when what we really want is just stuff that
works. Some say that should read Microsoft instead of technology.

Index: Makefile
===================================================================
--- Makefile	(revision 13446)
+++ Makefile	(working copy)
@@ -5,14 +5,6 @@
 # $Id$
 #
 
-# if you need to change this, don't forget to change it in catalog.xml too
-
-DOCBOOKXSL="/usr/share/docbook-xsl"
-# On SUSE 9.1 uncomment the following line:
-#DOCBOOKXSL="/usr/share/xml/docbook/stylesheet/nwalsh/1.64.1"
-# On SUSE 9.2 uncomment the following line:
-#DOCBOOKXSL="/usr/share/xml/docbook/stylesheet/nwalsh/1.65.1"
-
 # formatting objects processor
 # (comment this out, if you don't want pdf or don't have fop installed)
 # for win32 (cygwin) environments
@@ -20,11 +12,12 @@
 # for unix like environments (if you have problems with fop, try to use an absolute path here)
 #FOP="/usr/share/fop-0.20.5/fop.sh"
 # One SUSE 9.1 and 9.2 uncomment the following line (make sure you have at least fop-0.20.5-71.2)
-#FOP="/usr/bin/fop"
+#FOP="fop"
 
 # html help compiler (Win32 only)
 # (comment this out, if you don't want chm or don't have hhc installed)
 #HHC="/cygdrive/c/Program Files/HTML Help Workshop/hhc.exe"
+#HHC="true"
 
 ############### YOU SHOULDN'T HAVE TO EDIT ANYTHING BELOW THIS LINE! ################
 
@@ -35,7 +28,7 @@
 XMLLINT="xmllint"
 
 # as eug_chm will stop with an error, make sure it's the last in this dependency list
-all: svn_version.xml eug edg 
+all: eug edg 
 
 clean:
 	rm -f *.html
@@ -53,7 +46,7 @@
 	rm -rf edg_chm
 
 
-eug: eug_validate eug_pdf_a4 eug_html eug_html_chunked eug_chm 
+eug: eug_validate eug_pdf_a4 eug_pdf_us eug_html eug_html_chunked eug_chm 
 
 #
 # on every build, record the working copy revision string
@@ -66,56 +59,52 @@
 	svnversion -n .                   >> svn_version.xml
 	echo '">'   >> svn_version.xml
     
-eug_images:
-	cp $(DOCBOOKXSL)/images/note.png ./graphics
-	cp $(DOCBOOKXSL)/images/tip.png ./graphics
-	cp $(DOCBOOKXSL)/images/warning.png ./graphics
-
 # validate the content
 eug_validate:
 	@ echo --- VALIDATING XML ---
 	$(XMLLINT) --valid --noout user-guide.xml
 
 # create html single page file
-eug_html: eug_images svn_version.xml
+eug_html: svn_version.xml
 	@ echo --- HTML SINGLE PAGE ---
 	mkdir -p eug_html
 	mkdir -p eug_html/graphics
 	mkdir -p eug_html/graphics/toolbar
 	cp ./graphics/*.* eug_html/graphics
 	cp ./graphics/toolbar/*.* eug_html/graphics/toolbar
-	$(XSLTPROC) --nonet $(DOCBOOKXSL)/html/docbook.xsl user-guide.xml > eug_html/user-guide.html
+	$(XSLTPROC) --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl user-guide.xml > eug_html/user-guide.html
 	
 # create html chunked page files
-eug_html_chunked: eug_images svn_version.xml
+eug_html_chunked: svn_version.xml
 	@ echo --- HTML CHUNKED ---
 	mkdir -p eug_html_chunked
 	mkdir -p eug_html_chunked/graphics
 	mkdir -p eug_html_chunked/graphics/toolbar
 	cp ./graphics/*.* eug_html_chunked/graphics
 	cp ./graphics/toolbar/*.* eug_html_chunked/graphics/toolbar
-	$(XSLTPROC) --stringparam base.dir eug_html_chunked/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/html/chunk.xsl user-guide.xml
+	$(XSLTPROC) --stringparam base.dir eug_html_chunked/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl user-guide.xml
 
 # create pdf file (through XSL-FO), portrait pages on US letter paper (the default)
 # you will get lot's of errors, but that's ok
-eug_pdf_us: eug_images svn_version.xml
+eug_pdf_us: svn_version.xml
 ifdef FOP
 	@ echo --- PDF US PAPER ---
-	$(XSLTPROC) --nonet custom_layer_pdf.xsl $(DOCBOOKXSL)/fo/docbook.xsl user-guide.xml > user-guide.fo
-	$(FOP) user-guide.fo user-guide.pdf
+	# $(XSLTPROC) --nonet custom_layer_pdf.xsl http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl user-guide.xml > user-guide-us.fo
+	$(XSLTPROC) --nonet custom_layer_pdf.xsl user-guide.xml > user-guide-us.fo
+	$(FOP) user-guide-us.fo user-guide-us.pdf
 endif
 
 # create pdf file (through XSL-FO), portrait pages on A4 paper
 # you will get lot's of errors, but that's ok
-eug_pdf_a4: eug_images svn_version.xml
+eug_pdf_a4: svn_version.xml
 ifdef FOP
 	@ echo --- PDF A4 PAPER ---
-	$(XSLTPROC) --stringparam paper.type A4 --nonet custom_layer_pdf.xsl user-guide.xml > user-guide.fo
-	$(FOP) user-guide.fo user-guide.pdf
+	$(XSLTPROC) --stringparam paper.type A4 --nonet custom_layer_pdf.xsl user-guide.xml > user-guide-a4.fo
+	$(FOP) user-guide-a4.fo user-guide-a4.pdf
 endif
 
 # create MS html help file (through html chunked pages)
-eug_chm: eug_images svn_version.xml
+eug_chm: svn_version.xml
 ifdef HHC
 	@ echo --- MICROSOFT HTML HELP ---
 	mkdir -p eug_chm
@@ -123,72 +112,67 @@
 	mkdir -p eug_chm/graphics/toolbar
 	cp ./graphics/*.* eug_chm/graphics
 	cp ./graphics/toolbar/*.* eug_chm/graphics/toolbar
-	$(XSLTPROC) --stringparam base.dir eug_chm/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/htmlhelp/htmlhelp.xsl user-guide.xml
+	$(XSLTPROC) --stringparam base.dir eug_chm/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl user-guide.xml
 	-$(HHC) htmlhelp.hhp
-	mv htmlhelp.chm user-guide.chm
-	rm -r htmlhelp.hhp
-	rm -r toc.hhc
+	-mv htmlhelp.chm user-guide.chm
+	-rm -r htmlhelp.hhp
+	-rm -r toc.hhc
 endif
 
 
-edg: edg_validate edg_html_chunked edg_pdf_a4 edg_html edg_chm 
+edg: edg_validate edg_html_chunked edg_pdf_a4 edg_pdf_us edg_html edg_chm 
 
-edg_images:
-	cp $(DOCBOOKXSL)/images/note.png ./edg_graphics
-	cp $(DOCBOOKXSL)/images/tip.png ./edg_graphics
-	cp $(DOCBOOKXSL)/images/warning.png ./edg_graphics
-
-
 # validate the content
 edg_validate:
 	@ echo --- VALIDATING XML ---
 	$(XMLLINT) --valid --noout developer-guide.xml
 
 # create html single page file
-edg_html: edg_images svn_version.xml
+edg_html: svn_version.xml
 	@ echo --- HTML SINGLE PAGE ---
 	mkdir -p edg_html
 	mkdir -p edg_html/edg_graphics
 	cp ./edg_graphics/*.* edg_html/edg_graphics
-	$(XSLTPROC) --nonet $(DOCBOOKXSL)/html/docbook.xsl developer-guide.xml > edg_html/developer-guide.html
+	$(XSLTPROC) --nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl developer-guide.xml > edg_html/developer-guide.html
 	
 # create html chunked page files
-edg_html_chunked: edg_images svn_version.xml
+edg_html_chunked: svn_version.xml
 	@ echo --- HTML CHUNKED ---
 	mkdir -p edg_html_chunked
 	mkdir -p edg_html_chunked/edg_graphics
 	cp ./edg_graphics/*.* edg_html_chunked/edg_graphics
-	$(XSLTPROC) --stringparam base.dir edg_html_chunked/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/html/chunk.xsl developer-guide.xml
+	$(XSLTPROC) --stringparam base.dir edg_html_chunked/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl developer-guide.xml
 
 # create pdf file (through XSL-FO), portrait pages on US letter paper (the default)
 # you will get lot's of errors, but that's ok
-edg_pdf_us: edg_images svn_version.xml
+edg_pdf_us: svn_version.xml
 ifdef FOP
 	@ echo --- PDF US PAPER ---
-	$(XSLTPROC) --nonet custom_layer_pdf.xsl $(DOCBOOKXSL)/fo/docbook.xsl developer-guide.xml > developer-guide.fo
-	$(FOP) developer-guide.fo developer-guide.pdf
+	# $(XSLTPROC) --nonet custom_layer_pdf.xsl http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl developer-guide.xml > developer-guide-us.fo
+	$(XSLTPROC) --nonet custom_layer_pdf.xsl developer-guide.xml > developer-guide-us.fo
+	$(FOP) developer-guide-us.fo developer-guide-us.pdf
 endif
 
 # create pdf file (through XSL-FO), portrait pages on A4 paper
 # you will get lot's of errors, but that's ok
-edg_pdf_a4: edg_images svn_version.xml
+edg_pdf_a4: svn_version.xml
 ifdef FOP
 	@ echo --- PDF A4 PAPER ---
-	$(XSLTPROC) --stringparam paper.type A4 --nonet custom_layer_pdf.xsl developer-guide.xml > developer-guide.fo
-	$(FOP) developer-guide.fo developer-guide.pdf
+	$(XSLTPROC) --stringparam paper.type A4 --nonet custom_layer_pdf.xsl developer-guide.xml > developer-guide-a4.fo
+	$(FOP) developer-guide-a4.fo developer-guide-a4.pdf
 endif
 
 # create MS html help file (through html chunked pages)
-edg_chm: edg_images svn_version.xml
+edg_chm: svn_version.xml
 ifdef HHC
 	@ echo --- MICROSOFT HTML HELP ---
 	mkdir -p edg_chm
 	mkdir -p edg_chm/edg_graphics
 	cp ./edg_graphics/*.* edg_chm/edg_graphics
-	$(XSLTPROC) --stringparam base.dir edg_chm/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet $(DOCBOOKXSL)/htmlhelp/htmlhelp.xsl developer-guide.xml
+	$(XSLTPROC) --stringparam base.dir edg_chm/ --stringparam  use.id.as.filename 1 --stringparam admon.graphics 1 --stringparam admon.graphics.path edg_graphics/ --stringparam section.autolabel 1 --stringparam  section.label.includes.component.label 1 --nonet http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl developer-guide.xml
 	-$(HHC) htmlhelp.hhp
-	mv htmlhelp.chm developer-guide.chm
-	rm -r htmlhelp.hhp
-	rm -r toc.hhc
+	-mv htmlhelp.chm developer-guide.chm
+	-rm -r htmlhelp.hhp
+	-rm -r toc.hhc
 endif