How to add a DocBuild Timestamp

[gullinx]

I generate new versions of my docs all the time, and I'd like to be able to distinguish between versions, according to when I built them. How can I add this "time of build" information to my output docs?

[sorin_ristache]

Hello,

Does your document type define an element which allows inserting a revision date/build date in the XML documents of that type? If not maybe you should customize/extend the schema of your XML documents for allowing the declaration of a date.

For example the Docbook schema allows inserting the date in a Docbook XML document, either in a precise form like 04-16-2013 or as a template like @@DATE_OF_BUILD@@ which can be replaced automatically with the current date at build time in an ANT pre-processing (for example), just before the build of the output format of the documentation:

Code: Select all

<article xmlns="http://docbook.org/ns/docbook" version="5.0">

    <info>

        <title>Title of Docbook document here</title>

        <revhistory>

            <revision>

                <date>@@TIME_OF_BUILD@@</date>

            </revision>

        </revhistory>

    </info>

    . . .

In a DITA map a close relative would be the revised element which allows isnerting a date:

Code: Select all

    <topicmeta>

        <critdates>

            <revised modified="@@DATE_OF_BUILD@@"/>

        </critdates>

    </topicmeta>

Regards,
Sorin

[gullinx]

I'm using "DITA Map WebHelp". Can I use the <topicmeta> element inside the <map> root element (because I want to apply the DocBuild Timestamp the entire documentation set)?

<map>
<title>User's Guide</title>
<topicmeta>
<copyright>
<copyryear year="2013"></copyryear>
<copyrholder>Example Corporation</copyrholder>
</copyright>
<critdates>
<created date="2013-06-13"></created>
<revised modified="@@DATE_OF_BUILD@@"/>
</critdates>
</topicmeta>
...


I don't understand where you got @@DATE_OF_BUILD@@?
Is the schema aware of this variable, or do I have to declare it somewhere?
Do I declare it as a variable in the Ant build file?
Where is the Ant build file (build.xml)?
Can I extend the Ant build file with this additional information?

Finally, how do I reference this information in the footer of every topic?
Do I use ${DATE_OF_BUILD}?

Thanks,

Chris.

[gullinx]

I'm using "DITA Map WebHelp". Can I use the <topicmeta> element inside the <map> root element (because I want to apply the DocBuild Timestamp the entire documentation set)?

Code: Select all

<map>

  <title>User's Guide</title>

  <topicmeta>

    <copyright>

      <copyryear year="2013"></copyryear>

      <copyrholder>Example Corporation</copyrholder>

    </copyright>

    <critdates>

      <created date="2013-06-13"></created>

      <revised modified="@@DATE_OF_BUILD@@"/>

    </critdates>

  </topicmeta>

...

I don't understand where you got @@DATE_OF_BUILD@@?
Is the schema aware of this variable, or do I have to declare it somewhere?
Do I declare it as a variable in the Ant build file?
Where is the Ant build file (build.xml)?
Can I extend the Ant build file with this additional information?

Finally, how do I reference this information in the footer of every topic?
Do I use ${DATE_OF_BUILD}?

Thanks,

Chris.

[sorin_ristache]

Hi,

@@DATE_OF_BUILD@@ is a token which can be replaced at build time with the current date. You can use any token you want in the map file, that was just an example. It is not an ANT variable and you don't have to declare it in the build.xml of DITA-OT. It is only a marker that you can replace with any value you want when the map is processed by the build.xml script of DITA-OT which is located in directory [Oxygen-install-dir]\frameworks\dita\DITA-OT.

I suggest customizing the XSLT stylesheet that is called in the DITA-OT build process and handles the map/topicmeta/critdates/revised element. I think it is the stylesheet [Oxygen-install-dir]\frameworks\dita\DITA-OT\xsl\xslhtml\get-meta.xsl. You can override the template that processes the revised element or the critdates element and insert the current date in the main page of the output of the Webhelp transformation. For example you can add your custom XSLT template in the Oxygen Webhelp stylesheet [Oxygen-15.0-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\dita\map2webhelptoc.xsl where you can see other examples of customized processing.

If you want to insert the date of build also in every output topic page you have to customize the processing applied to every topic. You can add your custom processing in the stylesheet [Oxygen-15.0-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\xsl\dita\desktop\fixup.xsl which receives as input the output topic file (an XHTML file) as you can see it in the output of the DITA Map XHTML transformation and applies some processing specific for Webhelp output. You can look at the templates from this stylesheet as examples for your custom XSLt template.


Regards,
Sorin

[lopresti]

I'm reviving this thread to ask how to insert a timestamp into WebHelp output (com.oxygenxml.webhelp).

Using the fixup.xsl file, I've added a new template:

Code: Select all

<xsl:template name="myFooter">

	<xsl:value-of select="ex:date-time()"/> //Date this topic is generated

</xsl:template>

Next I updated the xsl:stylesheet definition:

Code: Select all

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

  xmlns:xs="http://www.w3.org/2001/XMLSchema"

  xmlns:xhtml="http://www.w3.org/1999/xhtml"

  xmlns:File="java:java.io.File" 

  exclude-result-prefixes="xs xhtml File"

  version="2.0"

  xmlns:ex="http://exslt.org/dates-and-times"

  extension-element-prefixes="ex">

Now I'm stuck. From where should the "myFooter" template get called? It seems that wherever I add it the transform fails with the message "This document contains top-level text node."

Thanks,
Kate

[radu_pisoi]

Hi,

You get this error because the XSLT stylesheet is not welformed.

You can find a similar discussion here:
http://stackoverflow.com/questions/7817 ... sformation

From where should the "myFooter" template get called?

If you want to modify the footer to add the current date and time you can add the following template in the 'fixup.xsl' stylesheet:

Code: Select all

<xsl:template match="*:div[@class='footer']" mode="fixup_desktop">

    <xsl:copy>

      <xsl:apply-templates select="node() | @*" mode="#current"/>

      

      Date: <xsl:value-of select="ex:date-time()"/>

    </xsl:copy>

  </xsl:template>

[lopresti]

Wonderful. Thanks for the quick response. I have it working now.

I also discovered that XSLT 2.0 has date and time format XPath functions so I didn't need to use the third-party library EXSLT.

Code: Select all

  <xsl:template match="*:div[@class = 'footer']" mode="fixup_desktop">

    <xsl:copy>

      <xsl:apply-templates select="node() | @*" mode="#current"/> 

      Date generated: <xsl:value-of select="format-date(current-date(), '[Y0001]-[M01]-[D01]')"/> 

    </xsl:copy>

  </xsl:template>

[cjboorman]

Hi,

I added the following code to fixup.xsl,

Code: Select all

  <xsl:template match="*:div[@class = 'footer']" mode="fixup_desktop">

    <xsl:copy>

      <xsl:apply-templates select="node() | @*" mode="#current"/> 

      Date generated: <xsl:value-of select="format-date(current-date(), '[Y0001]-[M01]-[D01]')"/> 

    </xsl:copy>

  </xsl:template>

and it didn't do anything. Is there something else that I need to do?

[alin]

Hi,

I added the following code to fixup.xsl,

Code: Select all

  <xsl:template match="*:div[@class = 'footer']" mode="fixup_desktop">

    <xsl:copy>

      <xsl:apply-templates select="node() | @*" mode="#current"/> 

      Date generated: <xsl:value-of select="format-date(current-date(), '[Y0001]-[M01]-[D01]')"/> 

    </xsl:copy>

  </xsl:template>

and it didn't do anything. Is there something else that I need to do?

For WebHelp Responsive, you will find another solution here: topic13403.html

[cjboorman]

No, this is for DITA Map WebHelp Classic. Should the code in my previous post work in this case, or am I still missing something (I'm thinking I must be missing something because I still don't have a time-stamp in my output)?

[alin]

Hello,

The XSL code snippet should have worked. I have tested it on my side and I got the expected output.
I have added the template in: ${current-dita-ot folder}/plugins/com.oxygenxml.webhelp/xsl/dita/desktop/fixup.xsl.
This is the content of the footer section:

Code: Select all

WebHelp output generated by <oXygen/> XML Author Date generated: 2016-09-30

${current-dita-ot folder} is the base directory of your current DITA Open Toolkit ditribution. The application comes bundled with two distributions of DITA Open Toolkit: DITA-OT 1.8 and DITA-OT 2.x.

• The DITA OT 1.8 base directory is: {installation-directory}/frameworks/dita/DITA-OT
• The DITA OT 2.x base directory is: {installation-directory}/frameworks/dita/DITA-OT2.x

Note: You can find out which is your current DITA Open Toolkit distribution in the DITA preferences page: Main Menu > Options > Preferences (https://www.oxygenxml.com/doc/versions/ ... OT-section).

Please make sure that you add the custom template in the fixup.xsl file in the WebHelp plugin from your current DITA-OT distribution.
If this is not the case please let me know.

Regards,
Alin

[cjboorman]

That solved my problem. Thank you.

The path to my fixup.xsl file was:

Code: Select all

C:\Program Files\Oxygen XML Editor 18\frameworks\dita\DITA-OT2.x\plugins\com.oxygenxml.webhelp\xsl\dita\desktop\fixup.xsl

I added the following code to the bottom of the file:

Code: Select all

  <!-- Add a "Date Published" timestamp to the footer of each topic. -->

  <xsl:template match="*:div[@class = 'footer']" mode="fixup_desktop">

    <xsl:copy>

      <xsl:apply-templates select="node() | @*" mode="#current"/> 

      Date generated: <xsl:value-of select="format-dateTime(current-dateTime(), '[h1]:[m01] [P] on [M01]/[D01]/[Y0001].')"/>

    </xsl:copy>

  </xsl:template>

[lopresti]

Thanks for this. I successfully added a timestamp to our footer file using these instructions.

Can I similarly use the fixup.xsl file to add <vrmlist> element attribute values like @version, @release and @modification?

[radu_pisoi]

Hi,

You can find a similar customization in the com.oxygenxml.webhelp.responsive.custom.footer WebHelp customizatiom plugin commited on GitHub.

In this sample, the footer of the WebHelp Responsive output is modified by adding copyright information extracted from the DITA bookmap or by adding the output generation time.

This copyright information is specified in the bookmap:

Code: Select all

<bookrights>

  <copyrfirst>

    <year>2002</year>

  </copyrfirst>

  <copyrlast>

    <year>2017</year>

  </copyrlast>

  <bookowner>

    <organization>SyncRO Soft SRL</organization>

  </bookowner>

</bookrights>

You can modify the XSLT stylesheets in a similar manner to extract version or release information.

[lopresti]

Thanks, Radu. At the moment we're using WebHelp classic.

[radu_pisoi]

Hi,

I don't think this customization is possible using the WebHelp Classic plugin.

The main problems is that the meta information presented in DITA map is not transferred to the 'toc.xml' file from the output folder, so it is not accessible from the XSLT processing.

I will register an issue on our side for this use case.