Copying boilerplate files

[Andrew McFarland Campbell]

Hi everyone,

I have inherited a complex Maven project that uses a custom plugin that uses Docbkx to generate documentation.

Currently, in my project, the DocBook source is in ${basedir}/src/docbook. When I run mvn site, the DocBook is transformed into a variety of outputs in ${basedir}/target/site/docs.

What I want to do is run an XSLT transform on some of the source documents, and then process as before, using the transformed source documents in place of the untransformed ones.

I can almost get this to work using the following steps: 

1. Run an XSLT transform on some of the Docbook source files, with the output written to another directory.
   
2. Copy all the untransformed files to that directory.
   
3. Build the documentation from that directory, not from ${basedir}/src/docbook.

In pom.xml I have to do is set a parameter called ${docbook.sourceDirectory} to point to the directory where the transformed files are written, as well as adding some lines to make the above steps happen.

However, it fails because something - and I’m not sure what part of the toolchain - copies boilerplate files (gpc-legal.xml et al) to ${basedir}/src/docbook, not ${docbook.sourceDirectory}. The DocBook build depends on the boilerplate files.

I can’t work out what is copying the boilerplate files. I am hoping that it is the Docbkx plugin, and I’m hoping that this list can help me. So here are my questions: 

• Are the boilerplate files being copied by Docbkx?
• How do I get the boilerplate files copied to ${docbook.sourceDirectory}.

As an alternative, I have thought about integrating my XSLT into our DocBook customisation layer, but I’m not keen to do that because the transform is quite time consuming, and I don’t want to run it on everything, and because it uses XSLT 2.0 and the rest of our customisation is based on XSLT 1.0, and I’d prefer not to upgrade at this time unless it is unavoidable. I’m open to other alternatives if anyone wants to propose them :)

My current hack is to output the transformed files into ${basedir}/src/docbook under different names. This works, but it feels messy because I’m writing generated files to a src directory instead of into target. I am a relative newcomer to Maven.

[Mark Craig]

Hi,

The pgc-legal.xml file isn't from docbkx-tools. It could be getting pulled in from another artifact downloaded through Maven. That would make sense if the content is shared across multiple projects. You can use the Maven dependency plugin to unpack requisite boilerplate files from an artifact (e.g. a .jar file in the Maven repository) before building the docs.

If it's going to be easier to pre-process XML documents in place, you might want to make a copy of the sources before trying to do anything to them.

Know that in Maven, the plugins in the build are run in the order they occur, though the executions triggered of course depend on the Maven lifecycle.

By the way, for running an XSLT transformation on documents, there's an XML Maven Plugin: http://www.mojohaus.org/xml-maven-plugin/

Regards,

Mark

--
You received this message because you are subscribed to the Google Groups "Docbkx Tools Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to docbkx-tools-us...@googlegroups.com.
To post to this group, send email to docbkx-to...@googlegroups.com.
Visit this group at https://groups.google.com/group/docbkx-tools-users.
For more options, visit https://groups.google.com/d/optout.

[Andrew McFarland Campbell]

On Friday, 8 January 2016 14:25:31 UTC, Mark Craig wrote:

It could be getting pulled in from another artifact downloaded through Maven. That would make sense if the content is shared across multiple projects.

After some investigation, that seems to be what is happening. I just have to figure out the inner workings of that plugin now....

Know that in Maven, the plugins in the build are run in the order they occur, though the executions triggered of course depend on the Maven lifecycle.

Thanks - I knew that, but it was something that tripped me up a couple of days ago.

 

By the way, for running an XSLT transformation on documents, there's an XML Maven Plugin: http://www.mojohaus.org/xml-maven-plugin/

Yes, that's the plugin I'm using. It's good :-D 

[Mimil Owns]

Hello,

in the sample project you have 2 samples using an xslt:

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>xml-maven-plugin</artifactId>
  <version>1.0-beta-2</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>transform</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <transformationSets>
      <transformationSet>
        <dir>${basedir}</dir>
        <includes>
          <include>pom.xml</include>
        </includes>
        <outputDir>target</outputDir>
        <stylesheet>src/xslt/pom-to-poms.xsl</stylesheet>
        <parameters>
          <parameter>
            <name>pluginVersion</name>
            <value>${project.version}</value>
          </parameter>
        </parameters>
      </transformationSet>
    </transformationSets>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>xalan</groupId>
      <artifactId>xalan</artifactId>
      <version>2.7.0</version>
    </dependency>
  </dependencies>
</plugin>

and:

<plugin>
    <groupId>com.agilejava.docbkx</groupId>
    <artifactId>docbkx-maven-plugin</artifactId>
    <version>${project.version}</version>
    <executions>
      <execution>
        <id>site</id>
        <goals>
          <goal>generate-html</goal>
        </goals>
        <phase>pre-site</phase>
      </execution>
    </executions>
    <dependencies>
      <dependency>
        <groupId>org.docbook</groupId>
        <artifactId>docbook-xml</artifactId>
        <version>4.4</version>
        <scope>runtime</scope>
      </dependency>
      <dependency>
        <groupId>ant</groupId>
        <artifactId>ant-trax</artifactId>
        <version>1.6.5</version>
      </dependency>
    </dependencies>
    <configuration>
      <entities>
        <entity>
          <name>version</name>
          <value>${project.version}</value>
        </entity>
      </entities>
      <sourceDirectory>target/docbkx</sourceDirectory>
      <targetDirectory>target/site/</targetDirectory>
      <preProcess>
        <mkdir dir="${basedir}/target/docbkx" />
        <xslt style="${basedir}/src/xslt/pom-to-docbkx.xsl" in="pom.xml" out="target/docbkx/manual.xml" />
      </preProcess>
      <htmlStylesheet>http://agilejava.com/downloads/kubrick-docbkx.css</htmlStylesheet>
      <headerRule>0</headerRule>
      <footerRule>0</footerRule>
      <draftMode>0</draftMode>
      <bodyFontFamily>Helvetica</bodyFontFamily>
    </configuration>
  </plugin>
</plugins>

Regards,

Cedric

--

[Mimil Owns]

Yes we do not copy stuff to src/docbook so I guess this is part of your complex project and not the plugin. Maybe you could provide some debug of the plugin failure.

Regards,

Cedric,