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

["Rowland, Larry" <larry.rowland@hp.com>]

We have a fairly complex Ant based system that uses an individual build file for each document that includes a set of build files that have the actual targets for building; this allows us to customize things like file names and destination paths easily.  Each document can be processed into a number of different outputs by selecting appropriate targets (things like build.pdf, build.html, build.html.single -- there are actually over a dozen targets, including a couple that do things like counting words and checking how much content is reused for estimates the localizers need).  We routinely process documents that are 100 to 400 or so pages -- policy says to break them up into volumes if they get much larger.

One thing we found really helpful is that Ant is XML, so we can use transforms to generate new Ant build files on the fly (to pass in dynamic parameters) and then transfer control to the new build file.  Moving from Make files to Ant was a bit challenging at first for a bunch of UNIX hackers, but we found a lot of advantages to it due to it being XML (so the same tools that edit our documents can edit the build files) and having native XSLT transform capability built into it.  It is extensible and easy to modularize things, which helps a lot.  It also allowed us to make things cross-platform which became important as we rolled things out to a wider community of users.

Regards,
Larry Rowland

-----Original Message-----
From: Peter Desjardins [mailto:peter.desjardins.us@gmail.com] 
Sent: Wednesday, August 25, 2010 8: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