docbook-apps

  • 1.  Controlling the publishing process - shell scripts, Ant, other tools

    Posted 08-26-2010 02:56
    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



  • 2.  Re: [docbook-apps] Controlling the publishing process - shell scripts, Ant, other tools

    Posted 08-26-2010 06:50
    On Wed, 25 Aug 2010 22:55:36 -0400
    Peter Desjardins <peter.desjardins.us@gmail.com> wrote:

    > 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?

    Fairly well known Peter. More chance of others maintaining your script?



    >
    > * 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?

    I have multiple media in one ant build file. Suggest you review it and
    group our output as appropriate. There is an 'include' facility in ant
    which I use for definitions, you could look at that. I guess time spent
    on design will pay off later, usual ideas.


    >
    > * 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?

    I do a 120 page document (embarrassed to say what) using 'book' root
    element. No problem.



    >
    > * 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?


    I call xslt using the java and task, I guess you could do the same
    for building a war file? Otherwise perhaps run them in bash as a
    precursor to running ant?

    >
    > * 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?

    ditto... although Norm seems pretty impressed with his employers kit.


    Not that I've used Peter.

    HTH






    --

    regards

    --
    Dave Pawson
    XSLT XSL-FO FAQ.
    http://www.dpawson.co.uk



  • 3.  RE: [docbook-apps] Controlling the publishing process - shell scripts, Ant, other tools

    Posted 08-26-2010 07:06
    Hi,

    I have been using ant for publishing for some time. Typical usage scenarios in my company are these:
    - publish documentation to webhelp and pdf as part of the application build
    - publish documentation as an eclipse infocenter plugin (this involves updating working copy from svn, stopping infocenter, publishing docs, starting infocenter)

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

    I do not have that much experience with shell scripts, but ant is quite extensible - you can use extension libraries or write you own.

    * 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?

    You could do with one file only. You could write a macro for each output format (http://ant.apache.org/manual/Tasks/macrodef.html) and then call it directly with parameters for each doc. Something like this:

    <macrodef name="publish-to-pdf">
    <atribute name="input-file"/>
    ...
    </macrodef>

    <target name="build-all-doc">
    <publish-to-pdf input-file="path-to-doc1"/>
    <publish-to-pdf input-file="path-to-doc2"/>
    </target>

    * 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?

    I cannot share our build scripts, but our largest document has circa 700 pages (PDF).

    * 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?

    Yes, you can create war files directly usány the war task (http://ant.apache.org/manual/Tasks/war.html).

    Pavel Škopík




    Original Message


  • 4.  RE: [docbook-apps] Controlling the publishing process - shell scripts, Ant, other tools

    Posted 08-26-2010 13:08
    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}">
    if="webhelp.include.search.tab"/>


    </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


  • 5.  RE: [docbook-apps] Controlling the publishing process - shell scripts, Ant, other tools

    Posted 08-26-2010 15:38
    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


  • 6.  Re: [docbook-apps] Controlling the publishing process - shell scripts, Ant, other tools

    Posted 08-27-2010 13:50
    Thanks to all. Your input is extremely helpful!

    Peter



Related Content