RE: [docbook-apps] Handling individual document attributes whenpublishing with Ant

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

Yes, you can have a master build.xml file that contains a series of <ant/> tasks invoking each document's build.xml. Each can build the doc in one or more formats and you can pass in properties at this point to override those set in the document's build.xml:

<project>
 <ant antfile="path/to/build.xml">
  <target name="pdf"/>
  <target name="webhelp"/>
  <property name="profile.security" value="reviewer"/>
 </ant>
 ...
</project>

When building several documents, you may not want the whole build to fail if one doc fails. We use the trycatch[1] task from antcontrib[2]. So it will try to build a doc, if that one fails then the catch uses the <mail/> task to send an email to the writer that owns that doc.  

However, having individual writers think about ant and concepts like try/catch is inconvenient, so I have a module.xml file that lists the docs to be built and whether the build should break if the doc fails. So the build runs an xslt that generates a build.xml from that module.xml file and then runs the generated build file. The generated build file in turn calls each doc's build.xml file. This way the writer can just manage a simple format like:

<module>
<document buildfile="path/to/build.xml">
 <notification>
   <email>someone@motive.com</email>
   <email>someoneesle@motive.com</email>
 </notification>
 <format name="pdf">
  <reviewer failonerror="false"/>
  <internal failonerror="true"/>
 </format>
 <format name="eclipse>
  <reviewer publish="true" infocenter="hsd"/>
 </format>
 ...

Then the xslt sees failonerror="false" and so wraps that one in a try/catch block and puts all the try/catches before the others so it will do those first then try the ones that could kill the build. In our system, for eclipse formats, if publish="true" then I invoke the target that pushes the result out to an infocenter. 

David

[1] http://ant-contrib.sourceforge.net/tasks/tasks/trycatch.html
[2] http://sourceforge.net/projects/ant-contrib/files/


> -----Original Message-----
> From: Peter Desjardins [mailto:peter.desjardins.us@gmail.com]
> Sent: Tuesday, November 09, 2010 11:06 PM
> To: Cramer, David W (David)
> Cc: DocBook Apps
> Subject: Re: [docbook-apps] Handling individual document attributes
> when publishing with Ant
> 
> Those sound like excellent solutions.
> 
> Is there a way to have Ant build the 40 individual build.xml files
> from a central build file? I'd like to invoke Ant once, have it build
> 40 documents based on their individual build XML files, and then move
> on to other targets such as packaging in Eclipse WAR files.
> 
> Thanks for your help.
> 
> Peter
> 
> On Tue, Nov 9, 2010 at 3:00 PM, Cramer, David W (David)
> <dcramer@motive.com> wrote:
> > Hi Peter,
> > You could have a build.xml for each top-level/buildable source file
> that:
> >
> > 1. Declares properties like current.docid etc.
> > 2. Imports your main build.xml that contains your build logic <import
> file="path/to/main-build.xml"/>
> >
> > Optionally, you could store the key/value pairs in a properties file
> and pull them into the doc's build.xml via <propertyfile
> file="build.properties"/>. That can be convenient if you have a group
> of properties that are common to a set of docs. Just put them in a
> properties file and have the build files for all those docs pull it in.
> >
> > When you pass the properties in to the xslts using the <xslt/> task,
> you can use the "if" attribute on nested params so that the params are
> only set if the property is declared. That way, your xslts will still
> use their defaults if the property happened not to have been set in the
> build.xml.
> >
> > David
> >
> >> -----Original Message-----
> >> From: Peter Desjardins [mailto:peter.desjardins.us@gmail.com]
> >> Sent: Tuesday, November 09, 2010 1:41 PM
> >> To: DocBook Apps
> >> Subject: [docbook-apps] Handling individual document attributes when
> >> publishing with Ant
> >>
> >> Hi, I'm getting started with Apache Ant and DocBook publishing. I
> have
> >> figured out how to use Ant to transform DocBook files with the
> >> stylesheets. Now I'm trying to find an efficient, maintainable, and
> >> scalable way to handle the sets of attributes that are unique to
> >> documents.
> >>
> >> I am dealing with about 40 documents and each one has a set of
> values
> >> that I need to pass in when they are published. For example, each
> >> document has a docid for olinking, a document title that appears in
> >> Eclipse output, an output filename, and similar details that I need
> to
> >> control while publishing.
> >>
> >> In the past, I've stored all these details in a crude database that
> I
> >> read with my publishing shell scripts. I'm moving to Ant in an
> effort
> >> to make the publishing process more easily understandable and
> >> maintainable. Can you point me to a good way to handle these
> document
> >> attributes when DocBook publishing with Ant? I didn't see the way
> this
> >> is handled in the DocBook/Ant examples I've found on the web.
> >>
> >> Thanks for your help.
> >>
> >> Peter
> >>
> >> --------------------------------------------------------------------
> -
> >> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-
> open.org
> >> For additional commands, e-mail: docbook-apps-help@lists.oasis-
> open.org
> >
> >