Build process with Gradle?

[Joachim Durchholz]

Sorry if this is off-topic (I'm almost sure it is to some degree); if you know a better place to ask this, please direct me there.

I'm looking for a way to publish documentation for an open source project I'm planning. Requirements:
- Easy to edit for new contributors.
- Able to generate HTML, single-page HTML, PDF.
- Generation is easy to set up from Gradle.
- Eclipse plugins for easier editing are an optional plus.

A DITA-based toolchain could fit that bill, except my searches didn't turn up any useful advice on setting up such a toolchain, so I'm turning here for advice.
Heh. What I got was advocacy, introductory articles, and lots of conflicting tool recommendations. No instructions on how to build such a toolchain. Ideally, I'd like to see a small project that sets up a minimum toolchain using Gradle, if such a thing exists.
Yeah I know this sounds lazy... but I need to do a quick smoke test to see whether DITA fits the bill, before embarking on a weeks-long quest to assemble a tool chain, make some stupid mistake, and conclude it won't work for me.

Any advice on how to best proceed are appreciated.

Thanks!
Jo

[que...@gmail.com]

I don't have an example. But, you could wrap the entire invocation of DITA-OT using gradle by integrating build.xml and invoking the default target. If the rest of what you want to do makes use of gradle, that could be worthwhile, otherwise I don't think it would simplify anything. I was going to look into invoking individual targets separately as part of unit testing but didn't get to it.

If easy to edit for new contributors means that you need them to be able to change something within the DITA-OT process, as opposed to configuring the build, you could do something like invoking a single gradle script from the pre/post targets. If the simplicity comes from it being groovy and you don't need the build logic in gradle you could just invoke groovy. So, you would have one groovy file that is called in various places within the DITA-OT "build" and could be the single place where new contributors make modiications. Ant is "inherently evil" (a joke. read the rationale for ant) so it could be easier for contributors to change.

Kendall

[Joachim Durchholz]

Thanks Kendall.

My focus is on easy doc writing, much less on easy build process fiddling - in an ideal world, both would be easy, but since we can't have everything, I'll opt for the more common case: doc writing :-)

What I was hoping for was a Gradle plugin, so people don't have to download and install DITA-OT and any postprocessors before they can build. Since it's all Java, it would even be doable... but then if it's not available, I'll live with what's there.

Is there an easy recipe for a toolchain?
It should start with a set of topic files and generate multi-page HTML, single-page HTML, and a PDF. Nothing fancy, I just want to see some wheels turning and what needs to be installed.

(On a tangent, I assume you didn't mean Gradle's doLast{...} feature with "post task" - that's not the best way to organize a build script.)
(On a further tangent, I'm currently less unhappy with Gradle than I am with ant, so I'm going to stick with and and refuse to discuss switching toolsets in mid-flight unless I hit a problem that Gradle can't solve - of which I currently do not have any. There's a time for advocacy, and there's a time for getting things done.)

[que...@gmail.com]

The pre/post targets are an extension mechanism in DITA-OT.

Using ant to invoke DITA-OT is straight forward if you don't need to change anything.

You can include an ant build script using ant.importBuild("some/path/build.xml") which would expose the ant targets as gradle tasks.

From what you are describing it doesn't sound like there is a reason to do that and you should just use ant. You could include an invocation of dita-ot by invoking ant as an executable or a java class from gradle.

Kendall

On Tuesday, August 26, 2014 11:36:08 PM UTC-7, Joachim Durchholz wrote:

[Joachim Durchholz]

Please let the build tool choice out of this discussion. My current goal is to integrate DITA-OT into an existing toolchain, and Gradle happens to be part of that toolchain for reasons entirely unrelated to DITA-OT's requirements. (In fact from what I wrote, you can't even infer a need to use ant, a shell script would do.)

Now how about the right incantations to generate the two HTMLs and PDF?
Googling for
  dita-ot html pdf example
and variants is giving me descriptions for a plugin that's doing extra stuff, not the basic process. Oh, and something that led me to dita-ot.github.io, taking me back to square one.

[Mark Giffin]

Joachim, maybe you want the ant command line to run PDF and HTML? Try these:

ant -Dtranstype=pdf2 -Dargs.input=C:\path\to\mymap.ditamap
ant -Dtranstype=xhtml -Dargs.input=C:\path\to\mymap.ditamap

Mark Giffin
http://markgiffin.com/

[que...@gmail.com]

Here is a description of how to invoke dita-ot using ant:

http://dita-ot.github.io/1.8/readme/DITA-antuse.html

There is a description of the transformation types for pdf and html elsewhere in the user guide.

The "ant" command is a shell script.

Kendall

[Joachim Durchholz]

Thanks.
Yes I finally found the right tutorial sections, and I'm now seeing that the output format is essentially just a question of using the right parameter.
I guess having read about Docbook set my expectations for a heavy, complicated toolchain. Not needed for dita-ot, so I thought I was missing something.

BTW now that I have seen how massively ant is being used to set up a dita-ot-run, I get an idea why ant is getting so much love here.
I'd still want to use Gradle (or Maven) though, they will automatically download toolchain and library dependencies (even indirect ones). That reduces download instructions for wannabee contributors to
  install $SCM, checkout the source tree, run ./gradlew
which is pretty easy on them and allows them to concentrate on whatever aspect they're interested in, instead of having to deal with toolchain installation (which gets old quickly).

Oh, also
  <condition property="args.input" value="${dita.input.dirname}${file.separator}${dita.input}">
    <not>
      <isset property="args.input"/>
    </not>
  </condition>
is just too much vs. Gradle's
  if (args.input == null) {
    args.input = "${dita.input.dirname}${file.separator}${dita.input}"
  }
or the even more compact
  args.input = args.input ?: "${dita.input.dirname}${file.separator}${dita.input}"
Not that I'm suggesting that all ant stuff should be thrown overboard. After all, it's working - not so well for the Maven/Gradle ecosystem, but fully adequate for command-line usage.

[Eero Helenius]

Hey there,

On Friday, August 29, 2014 1:08:24 AM UTC+3, Joachim Durchholz wrote:

I'd still want to use Gradle (or Maven) though, they will automatically download toolchain and library dependencies (even indirect ones). That reduces download instructions for wannabee contributors to
  install $SCM, checkout the source tree, run ./gradlew
which is pretty easy on them and allows them to concentrate on whatever aspect they're interested in, instead of having to deal with toolchain installation (which gets old quickly).

The DITA-OT full-easy-install package includes all of its dependencies, so you only really need to have Java installed to run it.

I actually investigated the Gradle & DITA-OT combination some time ago. However, if I recall correctly, I threw away what I had because I didn't really feel I was gaining anything by using Gradle and I couldn't really live with Gradle's mutable properties (as opposed to Ant's immutable ones).

In any case, here's a simple Gist that might help you get started with Gradle:

https://gist.github.com/eerohele/0cb870824b51eb501cc5

It's by no means a complete solution (and I believe you might be able to come up with a neat trick that lets you pass properties to DITA-OT on the command line when running Gradle without having to specify them separately in the Gradle buildfile), but it might work as a starting point. With it, it shouldn't be necessary to set a CLASSPATH at all — in fact, it's better if it's empty. You just need to either have your DITA_HOME and ANT_HOME environment variables set or you can define them in the buildfile itself. You should then be able to run DITA-OT by just doing gradle -PinputFile=$PWD/my-ditamap.ditamap. You can pass additional parameters to DITA-OT by adding more ant.sysproperty calls.

Alternatively, you could repurpose the Ant buildfile I made for my dita-ot-issues GitHub repository to work for you. You can check out the README in that repo for information on how to use the buildfile. I haven't had the chance to test it on a wide variety of systems, though, so if you decide to try it out and it doesn't work for you, please let me know. It should work pretty much on any DITA-OT version.

Yet another option is using the dita command-line tool introduced in DITA-OT 2.0. DITA-OT 2.0 is still in milestone status, though.

 

Oh, also
  <condition property="args.input" value="${dita.input.dirname}${file.separator}${dita.input}">
    <not>
      <isset property="args.input"/>
    </not>
  </condition>
is just too much vs. Gradle's
  if (args.input == null) {
    args.input = "${dita.input.dirname}${file.separator}${dita.input}"
  }
or the even more compact
  args.input = args.input ?: "${dita.input.dirname}${file.separator}${dita.input}"
Not that I'm suggesting that all ant stuff should be thrown overboard. After all, it's working - not so well for the Maven/Gradle ecosystem, but fully adequate for command-line usage.

Yeah, that Ant markup is quite redundant. Since Ant's properties are immutable, you could simply do <property name="args.input" value="${dita.input.dirname}${file.separator}${dita.input}"/> and not worry about whether a property is already set or not. There's a whole bunch of legacy Ant markup like that lying around in DITA-OT, unfortunately.

Best regards,

Eero

[que...@gmail.com]

Off topic for the list but maybe it's worth saying that immutable properties are great, except that ant is a procedural language which makes them pretty odd. Essentially, you have to invoke ant again to do the equivalent of a function invocation, which gets to be very slow. Using antbuilder from groovy is useful to get around immutable properties in ant in the cases where they are a limitation. XML as a declarative syntax (though groovy can be nicer for that too) makes sense. As a syntax for a procedural language it's needlessly verbose.

Also, ant was created to get around the supposed "inherent evil" of make but didn't include perhaps the main thing that make is used for, which is inferring which dependencies need to be built and only building those. Ant uses the term depends and target like make, but does not do what you would think, coming from make. Ultimately it is a procedural language that looks like it's supposed to be a build script but you then have to learn that it acts differently than you would expect from either of those.

DITA-OT doesn't use ant as a build tool so it's perhaps needlessly complicated to use one. I suppose it was common of the available almost kind of declarative xml executable language at the time.

Kendall

[Joachim Durchholz]

Thanks for the pointers, I'll be investigating more over the weekend.

I actually investigated the Gradle & DITA-OT combination some time ago. However, if I recall correctly, I threw away what I had because I didn't really feel I was gaining anything by using Gradle

Gradle isn't giving you much if all you want is generating documentation.
It will shine if you have multiple deliverables, have a build process that's so slow that you don't want to rebuild what doesn't need to, or have a complicated dependency setup.
dita-ot doesn't seem to need any of that. Well, maybe some day FOP will start needing dependencies.

One thing that dita-ot could gain from Gradle to change FOP version at the drop of a hat. That would allow experimenting with different versions of FOP with very little effort - just change the version number in the build.gradle and let Gradle download whatever different dependencies the other FOP version may need.

For including dita-ot into another builds, Gradle can simply call the ant buildfile.
More hoops to jump than strictly necessary I'd expect, but at least it should work :-)

and I couldn't really live with Gradle's mutable properties (as opposed to Ant's immutable ones).

Gradle properties are mutable only during phase 1, collecting information.
During the actual builds, properties can't be mutated anymore.

Though I'm wondering what's so bad about mutable properties. Okay they're somewhat cleaner, but unless you do real programming (and ant isn't suitable or designed for that), I'm not seeing any problems from that area - am I missing something?

[Eero Helenius]

Heya,

On Saturday, August 30, 2014 1:16:39 AM UTC+3, Joachim Durchholz wrote:

Thanks for the pointers, I'll be investigating more over the weekend.

I actually investigated the Gradle & DITA-OT combination some time ago. However, if I recall correctly, I threw away what I had because I didn't really feel I was gaining anything by using Gradle

Gradle isn't giving you much if all you want is generating documentation.
It will shine if you have multiple deliverables, have a build process that's so slow that you don't want to rebuild what doesn't need to, or have a complicated dependency setup.
dita-ot doesn't seem to need any of that. Well, maybe some day FOP will start needing dependencies.

One thing that dita-ot could gain from Gradle to change FOP version at the drop of a hat. That would allow experimenting with different versions of FOP with very little effort - just change the version number in the build.gradle and let Gradle download whatever different dependencies the other FOP version may need.

For including dita-ot into another builds, Gradle can simply call the ant buildfile.
More hoops to jump than strictly necessary I'd expect, but at least it should work :-)

I agree completely with regard to Gradle's benefits, and I didn't mean to discount Gradle at all — I simply meant to say that for that particular job (DITA-OT-related but not building or packaging DITA-OT itself) I was considering it for, it didn't offer any benefit over Ant. (Just to clarify: I'm not the DITA-OT maintainer, so I wasn't referring to migrating DITA-OT itself from Ant to Gradle. I can see the benefits that might have, though.)

 

and I couldn't really live with Gradle's mutable properties (as opposed to Ant's immutable ones).

Gradle properties are mutable only during phase 1, collecting information.
During the actual builds, properties can't be mutated anymore.

Though I'm wondering what's so bad about mutable properties. Okay they're somewhat cleaner, but unless you do real programming (and ant isn't suitable or designed for that), I'm not seeing any problems from that area - am I missing something?

I'm afraid it was so long ago that I toyed with Gradle that I don't remember the particular problem I had back then, but it may have had something to do with passing properties on the command line or something similar. It's entirely possible I just didn't figure out the right way to do it back then (or things may've changed in the Gradle world), but I just vaguely remember being frustrated about not being able to count on properties retaining the value I had given them. :)

Anywho, it's certainly a fine tool, especially for managing dependencies as you said.

Best regards,

Eero

[Joachim Durchholz]

Am Samstag, 30. August 2014 00:56:14 UTC+2 schrieb Eero Helenius:

I agree completely with regard to Gradle's benefits, and I didn't mean to discount Gradle at all — I simply meant to say that for that particular job (DITA-OT-related but not building or packaging DITA-OT itself) I was considering it for, it didn't offer any benefit over Ant.

For a pure DITA-OT product, that's fully sufficient.
My use case is a mixed build - a lot of jars and packaging and stuff; docs generation is just a small part of it all, so the overall process is going to be done in Gradle anyway.
 

I'm afraid it was so long ago that I toyed with Gradle that I don't remember the particular problem I had back then, but it may have had something to do with passing properties on the command line or something similar. It's entirely possible I just didn't figure out the right way to do it back then (or things may've changed in the Gradle world), but I just vaguely remember being frustrated about not being able to count on properties retaining the value I had given them. :)

Gradle has moved quite a lot in the past few years, so whatever roadblock you hit then, it's probably not there anymore :-)