Uploaded image for project: 'maven-jdocbook-plugin'
  1. maven-jdocbook-plugin
  2. MPJDOCBOOK-30

Allow injection of information into docbook sources

    Details

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

      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.

        Gliffy Diagrams

          Issue Links

            Activity

            Hide
            sebersole 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
            sebersole 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 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 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
            sebersole 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
            sebersole 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
            sebersole 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
            sebersole 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 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 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
            sebersole 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
            sebersole 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
            sebersole 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
            sebersole 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
            sebersole 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
            sebersole 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
            ge0ffrey 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
            ge0ffrey 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:
                sebersole Steve Ebersole
                Reporter:
                thomas.diesler Thomas Diesler
              • Votes:
                0 Vote for this issue
                Watchers:
                0 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Development