RE: [docbook-apps] Controlling the publishing process - shellscripts, Ant, other tools

["Cramer, David W (David)" <dcramer@motive.com>]

Hi Peter, 
I also use Ant for our build process and would add a couple of points to those others have made:

The <xslt> task [1] allows you to pass in parameters if they have been specified. This is very convenient since you want to use the default values from the xslts unless you pass in a value. I.e. you don't want to pass in an empty string and override the default in the xslts. So in the following example, if="webhelp.include.search.tab" tells the xslt task only to pass in this param if the property webhelp.include.search.tab has been set. 

	<xslt
	  in="${input-xml}"
	  out="${output-dir}/dummy.html"
	  style="${stylesheet-path}"
	  scanincludeddirectories="false"
	  classpath="${xslt-processor-classpath}">
	  <param name="webhelp.include.search.tab" expression="${webhelp.include.search.tab}"
		if="webhelp.include.search.tab"/>
	  <param name="webhelp.base.dir" expression="${output-dir}" if="output-dir"/>
	  <param name="webhelp.indexer.language" expression="${webhelp.indexer.language}" if="webhelp.indexer.language"/>
	</xslt>	

I only use the xslt task with Saxon 6 and 9 and can use the classpath attribute to pick the one I need, BUT it won't work if Saxon 6 is in the CLASSPATH when you run Ant. If you get a mysterious error, try invoking ant with a clean classpath. 

Ant has a baby version of XML catalogs but can also use a real catalog resolver. Sometimes the baby version is convenient if your needs are limited. 

A limitation of Ant compared to shell scripts or make is that it lacks common scripting constructs like if/then and try/catch. If you need things like this, then you can use the ant-contrib extensions ([2] and [3]). I was reluctant to use extensions, but ultimately found I needed the functionality. 

To collect images for the output directory after assembling transclusions, filtering, and so on, I run an xslt over the processed document and generate an ant script, then run that ant script from the main ant script. I have it check to see if any images are missing so it can fail if they are. To catch common images (callouts, admon graphics) you need either to run the xslt on the output or code the xslt so it knows what DcoBook constructs require what graphics. 

As Pavel mentions, Ant is good at making war files etc. In fact, globbing is a particular strength. By default, when making a zip of some kind, it excludes obvious cruft like svn or cvs directories. 

I've looked a little at xproc, which seems designed for this situation, but haven't gotten far yet. I can tell that it would make certain parts very easy, but one point I'm confused on is how chunked output is treated. Is each chunk a separate pipeline that I can process further? How would I handle the image case? Or perhaps I should invoke xproc from ant and each for certain tasks?

Btw., the webhelp gsoc project [5] has a sample ant build file that could give some ideas (though very simple-minded wrt how it handles images). The idea is that the user makes a small build.xml that declares a couple of properties (input doc file name, desired output dir, and any xslt params to pass in), then imports the main build.xml included with webhelp which contains the logic.

Hope that helps,
David

[1] http://ant.apache.org/manual/Tasks/style.html
[2] http://ant-contrib.sourceforge.net/
[3] http://ant-contrib.sourceforge.net/tasks/tasks/
[4] http://en.wikipedia.org/wiki/XProc
[5] http://www.thingbag.net/docbook/gsoc2010/doc/content/ch02s01.html

-----Original Message-----
From: Peter Desjardins [mailto:peter.desjardins.us@gmail.com] 
Sent: Wednesday, August 25, 2010 9:56 PM
To: DocBook Apps
Subject: [docbook-apps] Controlling the publishing process - shell scripts, Ant, other tools

Hi. I've been publishing DocBook for a few years and I've always used
shell scripts to control the process. This has worked well for me but
I'm starting a new publishing system from scratch and I'd like to
improve the maintainability and scalability of the process if I can.

Although I could do anything I needed to do with my publishing system
when it was based on shell scripts, it really wasn't something that
could be easily maintained by someone else. I tried to comment and
otherwise document my scripts but realistically, it would have been
frustrating for someone else to pick through the logic.

For my new publishing system, I'm considering using Apache Ant. I see
that other people seem happy publishing XML with Ant and the software
developers I work with use it for their build process. So I've started
experimenting with Ant, starting with the examples at
http://www.dpawson.co.uk/docbook/ant.html. It's not coming easily in
the first few hours I've spent with it.

Here are some of the questions I have. Any input will be very helpful.

* What are some advantages an Ant-based publishing system has over a
shell script system? Clearly Ant is cross-platform, what else?

* Is there a typical Ant architecture for large, single-sourced
documentation sets? I've got over 30 large documents being published
to multiple formats. Would I set up a build.xml file for each document
and format permutation and then have a master build.xml file to run
them all at once?

* The example on Dave Pawson's site (thanks, Dave!) shows web site
publishing. Does anyone know of example Ant setups for publishing
large manual sets to PDF and online help?

* Can Ant handle complicated file manipulation like packaging Eclipse
help plugins into an Infocenter WAR file? Will I end up having to
write shell-script code for an Ant task to execute?

* What other build control systems should I consider in this
situation? I don't think my colleagues would be very excited about GNU
make files. I'm not too excited about the idea of a CMS to handle
publishing. Anything else?

Thanks for your help.

Peter Desjardins

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org