maven-jdocbook-plugin
  1. maven-jdocbook-plugin
  2. MPJDOCBOOK-30

Allow injection of information into docbook sources

    Details

    • Type: Feature Request Feature Request
    • Status: Closed Closed (View Workflow)
    • Priority: Major Major
    • Resolution: Done
    • Affects Version/s: 2.1.2
    • Fix Version/s: 2.2.0
    • Labels:
      None
    • Similar Issues:
      Show 10 results 

      Description

      Wanted to let you know that I am experimenting with adding support for this in trunk (-> 2.2.0).

      There are 2 options in play here:
      1) <options><applyStandardInjectionEntities>true</applyStandardInjectionEntities></options> (true is the default). Makes some "standard" information available to your docbook source in the form of DTD entities. Currently there are just 2: (1) "version" which is the defined version from pom; (2) "today" which is a new Date() formatted as "MMMM d yyyy"
      2) <entities><entity><name>version</name><value$

      {pom.version}

      </value></entity></entities> would again make available a DTD entity named "version" available to your docbook as a DTD entity with the value of your pom-defined version.

      I think this should allow coverage of most cases.

        Issue Links

          Activity

          Hide
          Steve Ebersole
          added a comment -

          jdocbook:resources is a goal (mojo) in the jdocbook plugin. It is bound to the process-resources phase. So the process-resources phase is being executed...

          Show
          Steve Ebersole
          added a comment - jdocbook:resources is a goal (mojo) in the jdocbook plugin. It is bound to the process-resources phase. So the process-resources phase is being executed...
          Hide
          Thomas Diesler
          added a comment -

          Could you please verify that the resources are indeed filtered and copied - this does not seem to be the case

          http://maven.apache.org/guides/getting-started/index.html#How_do_I_filter_resource_files

          merci

          Show
          Thomas Diesler
          added a comment - Could you please verify that the resources are indeed filtered and copied - this does not seem to be the case http://maven.apache.org/guides/getting-started/index.html#How_do_I_filter_resource_files merci
          Hide
          Steve Ebersole
          added a comment -

          Or you could verify that it does not and attach a project showing that it in fact does not if that is the case... That the normal way a bug report works

          Show
          Steve Ebersole
          added a comment - Or you could verify that it does not and attach a project showing that it in fact does not if that is the case... That the normal way a bug report works
          Hide
          Steve Ebersole
          added a comment -

          I think you need to understand the different between phases and goals. Maven binds a certain goal (http://maven.apache.org/plugins/maven-resources-plugin/resources-mojo.html) to a phase called process-resources by default. However, the jdocbook packaging overrides that and binds a different goal to that phase.

          You can either:
          1) Bind the resources:resources goal to the process-resources phase in your pom
          2) (as outlined on MPJDOCBOOK-31) not use the jdocbook packaging and bind the jdocbook goals to approproate phases in your pom

          Show
          Steve Ebersole
          added a comment - I think you need to understand the different between phases and goals. Maven binds a certain goal ( http://maven.apache.org/plugins/maven-resources-plugin/resources-mojo.html ) to a phase called process-resources by default. However, the jdocbook packaging overrides that and binds a different goal to that phase. You can either: 1) Bind the resources:resources goal to the process-resources phase in your pom 2) (as outlined on MPJDOCBOOK-31 ) not use the jdocbook packaging and bind the jdocbook goals to approproate phases in your pom
          Hide
          Thomas Diesler
          added a comment -

          For folks who are interested in a solution, here is how JBossOSGi does it:

          In you pom add

          <resources>
          <resource>
          <directory>src/main/resources</directory>
          <filtering>true</filtering>
          </resource>
          </resources>
          <plugins>
          <plugin>
          <groupId>org.codehaus.mojo</groupId>
          <artifactId>buildnumber-maven-plugin</artifactId>
          <executions>
          <execution>
          <phase>process-resources</phase>
          <goals>
          <goal>create</goal>
          </goals>
          <configuration>
          <format>

          {0,date,dd-MMM-yyyy}

          </format>
          <items>
          <item>timestamp</item>
          </items>
          </configuration>
          </execution>
          </executions>
          </plugin>
          <plugin>
          <artifactId>maven-resources-plugin</artifactId>
          <executions>
          <execution>
          <phase>process-resources</phase>
          <goals>
          <goal>resources</goal>
          </goals>
          <configuration>
          <outputDirectory>$

          {project.build.directory}

          /docbook/resources</outputDirectory>
          </configuration>
          </execution>
          </executions>
          </plugin>

          in src/main/resources/bookinfo.xml I have

          <bookinfo>
          <title>JBossOSGi - User Guide</title>
          <releaseinfo>Version: $

          {version}

          </releaseinfo>
          <pubdate>Date: $

          {buildNumber}

          </pubdate>
          </bookinfo>

          in my master.xml I have

          <book lang="en" xmlns:xi="http://www.w3.org/2001/XInclude">

          <xi:include href="../target/docbook/resources/bookinfo.xml"/>

          <toc/>

          <xi:include href="modules/introduction.xml"/>
          <xi:include href="modules/gettingstarted.xml"/>
          <xi:include href="modules/frameworkintegration.xml"/>
          <xi:include href="modules/devguide.xml"/>
          <xi:include href="modules/providedservices.xml"/>
          <xi:include href="modules/references.xml"/>
          <xi:include href="modules/gettingsupport.xml"/>

          </book>

          This includes the filtered bookinfo from target/docbook/resources

          May this be useful

          Show
          Thomas Diesler
          added a comment - For folks who are interested in a solution, here is how JBossOSGi does it: In you pom add <resources> <resource> <directory>src/main/resources</directory> <filtering>true</filtering> </resource> </resources> <plugins> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>buildnumber-maven-plugin</artifactId> <executions> <execution> <phase>process-resources</phase> <goals> <goal>create</goal> </goals> <configuration> <format> {0,date,dd-MMM-yyyy} </format> <items> <item>timestamp</item> </items> </configuration> </execution> </executions> </plugin> <plugin> <artifactId>maven-resources-plugin</artifactId> <executions> <execution> <phase>process-resources</phase> <goals> <goal>resources</goal> </goals> <configuration> <outputDirectory>$ {project.build.directory} /docbook/resources</outputDirectory> </configuration> </execution> </executions> </plugin> in src/main/resources/bookinfo.xml I have <bookinfo> <title>JBossOSGi - User Guide</title> <releaseinfo>Version: $ {version} </releaseinfo> <pubdate>Date: $ {buildNumber} </pubdate> </bookinfo> in my master.xml I have <book lang="en" xmlns:xi="http://www.w3.org/2001/XInclude"> <xi:include href="../target/docbook/resources/bookinfo.xml"/> <toc/> <xi:include href="modules/introduction.xml"/> <xi:include href="modules/gettingstarted.xml"/> <xi:include href="modules/frameworkintegration.xml"/> <xi:include href="modules/devguide.xml"/> <xi:include href="modules/providedservices.xml"/> <xi:include href="modules/references.xml"/> <xi:include href="modules/gettingsupport.xml"/> </book> This includes the filtered bookinfo from target/docbook/resources May this be useful
          Hide
          Steve Ebersole
          added a comment -

          Wanted to let you know that I am experimenting with adding support for this in trunk (-> 2.2.0).

          There are 2 options in play here:
          1) <options><applyStandardInjectionEntities>true</applyStandardInjectionEntities></options> (true is the default). Makes some "standard" information available to your docbook source in the form of DTD entities. Currently there are just 2: (1) "version" which is the defined version from pom; (2) "today" which is a new Date() formatted as "MMMM d yyyy"
          2) <entities><entity><name>version</name><value$

          {pom.version}

          </value></entity></entities> would again make available a DTD entity named "version" available to your docbook as a DTD entity with the value of your pom-defined version.

          I think this should allow coverage of most cases.

          Show
          Steve Ebersole
          added a comment - Wanted to let you know that I am experimenting with adding support for this in trunk (-> 2.2.0). There are 2 options in play here: 1) <options><applyStandardInjectionEntities>true</applyStandardInjectionEntities></options> (true is the default). Makes some "standard" information available to your docbook source in the form of DTD entities. Currently there are just 2: (1) "version" which is the defined version from pom; (2) "today" which is a new Date() formatted as "MMMM d yyyy" 2) <entities><entity><name>version</name><value$ {pom.version} </value></entity></entities> would again make available a DTD entity named "version" available to your docbook as a DTD entity with the value of your pom-defined version. I think this should allow coverage of most cases.
          Hide
          Steve Ebersole
          added a comment -

          Having some difficulty getting this to work.

          Another option would be a push model where you can specify which element(s) should have their value replaced with a given value. Maybe via XPath. Something like:
          <injections>
          <injection>
          <path>/book/bookinfo/releaseinfo</path>
          <value>$

          {pom.version}

          </value>
          </injection>
          </injections>

          I'd prefer to get the doctype+ENTITY approach working... Just listing alternatives in case I cannot

          Show
          Steve Ebersole
          added a comment - Having some difficulty getting this to work. Another option would be a push model where you can specify which element(s) should have their value replaced with a given value. Maybe via XPath. Something like: <injections> <injection> <path>/book/bookinfo/releaseinfo</path> <value>$ {pom.version} </value> </injection> </injections> I'd prefer to get the doctype+ENTITY approach working... Just listing alternatives in case I cannot
          Hide
          Steve Ebersole
          added a comment -

          OK, I got this done the "preferred" way. This is implemented by injecting a series DOCTYPE internal entity definitions into you docbook document. An internal entity def looks like:

          <!DOCTYPE ... [<!ENTITY version "1.1.0">]>

          Then in your docuemnt you can use this value using an "entity reference", here "&version;" e.g:
          <releaseinfo>&version;</releaseinfo>

          You can even define the entity physically in the doctype declaration in your source. These injected values will take precedence!

          So there are two non-exclusive ways to inject values:

          1) "standard" injections.
          <options>
          <applyStandardInjectionEntities>true</applyStandardInjectionEntities>
          </options>
          True is the default! This will inject "version" and "today" as values. "today" is a formatted "new java.util.Date()". The format is controlled by
          <options>
          <injectionDateFormat>yyyy-MM-dd</injectionDateFormat>
          </options>
          The default format is MMMM d, yyyy

          2) "additional" injections.
          e.g.
          <injections>
          <injection>
          <name>projectname</name>
          <value>$

          {pom.name}

          </value>
          </injection>
          <injection>
          <name>projecturl</name>
          <value>$

          {pom.url}

          </value>
          </injection>
          </injections>
          Would make entities named "projectname" and "projecturl" available to your docbook sources as outlined above.

          Show
          Steve Ebersole
          added a comment - OK, I got this done the "preferred" way. This is implemented by injecting a series DOCTYPE internal entity definitions into you docbook document. An internal entity def looks like: <!DOCTYPE ... [<!ENTITY version "1.1.0">] > Then in your docuemnt you can use this value using an "entity reference", here "&version;" e.g: <releaseinfo>&version;</releaseinfo> You can even define the entity physically in the doctype declaration in your source. These injected values will take precedence! So there are two non-exclusive ways to inject values: 1) "standard" injections. <options> <applyStandardInjectionEntities>true</applyStandardInjectionEntities> </options> True is the default! This will inject "version" and "today" as values. "today" is a formatted "new java.util.Date()". The format is controlled by <options> <injectionDateFormat>yyyy-MM-dd</injectionDateFormat> </options> The default format is MMMM d, yyyy 2) "additional" injections. e.g. <injections> <injection> <name>projectname</name> <value>$ {pom.name} </value> </injection> <injection> <name>projecturl</name> <value>$ {pom.url} </value> </injection> </injections> Would make entities named "projectname" and "projecturl" available to your docbook sources as outlined above.
          Hide
          Geoffrey De Smet
          added a comment -

          There's a regression and this doesn't work, but MPJDOCBOOK-78 fixes it for 2.3.6.

          Show
          Geoffrey De Smet
          added a comment - There's a regression and this doesn't work, but MPJDOCBOOK-78 fixes it for 2.3.6.

            People

            • Assignee:
              Steve Ebersole
              Reporter:
              Thomas Diesler
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: