As I was watching the "Chuck Versus the Broken Heart" episode of Chuck, I was excited to see Michael Kay's XSLT book in the background! It appears that Agent Carmichael also uses XSLT...
I also noticed Programming Perl, and a few Java books, but was most excited to see the familiar red book laying in the background!
The latest version of the DocBook XSL stylesheets, v1.73.0, has been released!
The .0 designator means this is the beta version, and should be tested. If no bugs are found with the new distribution, a .1 release will be issued shortly!.
Hopefully a new version of the namespace-aware stylesheets for processing DocBook v5.0 documents will be following soon. UPDATE: The 1.73.0 namespace-aware version is also available now!
The stylesheets can be downloaded from here.
Features in this release include:
This release includes important bug fixes and adds the following significant
feature changes:
New localizations and localization updates
We added two new localizations: Latvian and Esperanto, and made updates to
the Czech, Chinese Simplified, Mongolian, Serbian, Italian, and Ukrainian
localizations.
ISO690 citation style for bibliography output.
Set the bibliography.style parameter to iso690 to use ISO690 style.
New documentation for processing instructions (PI)
The reference documentation that ships with the release now includes
documentation on all PIs that you can use to control output from the
stylesheets.
New profiling parameters for audience and wordsize
You can now do profiling based on the values of the audience and wordsize
attributes.
Changes to man-page output
The manpages stylesheet now supports single-pass profiling and single-pass
DocBook 5 namespace stripping (just as the HTML and FO stylesheets also
do). Also, added handling for mediaobject & inlinemediaobject. (Each
imagedata, audiodata, or videodata element within a mediaobject or inline
mediaobject is now treated as a "notesource" and so handled in much the
same way as links and annotation/alt/footnote are in manpages output.) And
added the man.authors.section.enabled and man.copyright.section.enabled
parameters to enable control over whether output includes auto-generated
AUTHORS and COPYRIGHT sections.
Highlighting support for C
The highlighting mechanism for generating syntax-highlighted code snippets
in output now supports C code listings (along with Java, PHP, XSLT, and
others).
Experimental docbook-xsl-update script
We added an experimental docbook-xsl-update script, the purpose of which
is to facilitate easy sync-up to the latest docbook-xsl snapshot (by means
of rsync).
I've been working on a little identity transform issue, where I needed to resolve some transclusions in an XML document. Some of the ref attributes in the doc also contained multiple space-separated values that needed to be processed separately.
After a few Googles and a great deal of hacking, I was able to process refs with a single attribute value. I Googled a bit more and found some help (including a great article from Bob DuCharme) to process the multiple values using the tokenize function in XSLT 2.0.
I kept running into an odd error though: "Cannot select a node here: the context item is an atomic value". I thought it was some kind of XPath issue, so tried a number of different hacks to get around the issue to no avail. Finally, I Googled on the error message and found the solution. Here's the code snippet that I used:
<xsl:template match="widgetRef">
<xsl:variable name="root" select="/"/>
<xsl:variable name="widgetID" select="tokenize(@stuff, ' ')"/>
<xsl:for-each select="$widgetID">
<xsl:variable name="widgetNum" select="."/>
<xsl:copy-of select="$root//widget[@id=$widgetNum]"/>
</xsl:for-each>
</xsl:template>
Hope this helps someone. It took me a while to discover that I needed to reset the context when using tokenize within a for-each.
Jeni Tennison has entered the blogosphere! Welcome, Jeni! Jeni and Michael Kay are my primary sources of XSLT wisdom, so I look forward to reading her posts!
Elliotte Rusty Harold pointed me to the Apache Velocity DocBook Framework at: http://velocity.apache.org/docbook/.
This looks pretty interesting and would be an easy way for folks to set up a multi-platform processing framework for DocBook. It uses the community stylesheet releases from sourceforge, but makes it easier to set up the rest of the toolchain.
Definitely worth giving it a test drive!
Michael Kay has released a new version of Saxon: 8.9
New features in this release include: compiling a query to Java source code, XInclude, and a Saxon specific Ant task.
Saxon is THE engine to use for XSLT in my opinion. Check it out!
The latest versions of the DocBook stylesheets have been released on sourceforge here. Included in this 1.72.0 release are the base docbook stylesheets, as well as docbook5 stylesheets.
The release notes can be found here, but essentially the highlights include:
- Automatic sorting of glossary entries
WordML renamed to Roundtrip, OpenOffice support added
Stylesheets for roundtrip conversion between documents in OpenOffice format (ODF) and DocBook XML have been added to the set of stylesheets that formerly had the collective title WordML, and that set of stylesheets has been renamed to Roundtrip to better reflect the actual scope and purpose of its contents.
So the DocBook XSL Stylesheets now support roundtrip conversion (with certain limitations) of WordML, OpenOffice, and Apple Pages documents to and from DocBook XML.
- Including QandASet questions in TOCs
- Language identifier in man-page filenames and pathnames
- index.page.number.properties property set
- Crop marks in output from Antenna House XSL Formatter
- More string-substitution hooks in manpages output
- Moved verbatim properties to attribute-set
- enhanced simple.xlink template
DocBook 5 compatibility
Stylesheets now consistently support DocBook 5 attributes (such as xml:id). Also, DocBook 5 info elements are now checked along with other *info elements, and the use of name() function was replaced by local-name() so it also matches on DocBook 5 elements. These changes enable reusing the stylesheets with DocBook 5 documents with minimal fixup.
- HTML class attributes now handled in class.attribute mode
- arabic-indic numbering enabled in autolabels
As always, the .0 release is the test release. A follow-on .1 release should follow shortly if no errors are reported.
Michael Smith has released the latest DocBook XSL.
Version 1.71.1 of the DocBook XSL stylesheets is now available for
download from the DocBook project site:
http://docbook.sf.net/files/xsl/latest
http://docbook.sf.net/files/xsl-doc/latest
http://sourceforge.net/projects/docbook
HTML and PDF versions of the release notes are also available:
http://docbook.sf.net/release/xsl/current/RELEASE-NOTES.html
http://docbook.sf.net/release/xsl/current/RELEASE-NOTES.pdf
This is the production release of the XSL, so if you've been waiting to upgrade, now is the time! Enjoy!
Categories: DocBook
Michael Smith has released the latest DocBook XSL stylesheets (version 1.71.0). This is the experimental release, to be followed shortly with v.1.71.1 if no problems are found.
This release incorporates a number of bug fixes, and also 2 new features:
You can download the latest stylesheets here.
Categories: DocBook
OK, now it's official. The latest version of the DocBook XSL (1.70.1) has been released.
You can download the latest stylesheets at: http://sourceforge.net/projects/docbook, and you can view the release notes at: http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html
Now go forth and DocBook with style! :-)
Categories: General
It's been a while since the last release of the DocBook stylesheets, but there have been quite a number of improvements and fixes! Michael Smith has announced the availability of Version 1.70.0 of the DocBook XSL stylesheets.
You can download the latest stylesheets at: http://sourceforge.net/projects/docbook, and you can view the release notes at: http://docbook.sourceforge.net/release/xsl/current/RELEASE-NOTES.html
Key improvements include:
This is the initial experimental release, so please test and send feedback to the docbook-apps list! The final version 1.70.1 will be released following the short review and test period.
Categories: DocBook
I've been creating PDFs via a DocBook customization layer and Arbortext Publishing Engine. For some reason, using this method, I couldn't get bookmarks in the PDF.
I tried various combinations of:
<xsl:param name="arbortext.extensions">1</xsl:param> <xsl:param name="fop1.extensions">1</xsl:param> <xsl:param name="fop.extensions">1</xsl:param>
Thanks to Paul Grosso for giving me the solution: If you are using Arbortext, you should use
<xsl:import href="doctypes/axdocbook/axdocbook-fo.xsl"/>not
<xsl:import href="docbook-xsl-1.69.1/fo/docbook.xsl"/>
I need to take a look in axdocbook-fo.xsl to see what's going on, and figure out how to make the arbortext extension to the DocBook stylesheets generate the bookmarks properly.
I also found some interesting info on linking to PDFs:
If you want to display bookmarks when the PDF opens, create your link like:
<a href="mydoc.pdf#pagemode=bookmarks
Other linking parameters are described at: http://ic.ucsc.edu/docs/tutorials/linkingtopdfs/.
Dominik Brettnacher has released Annotate 0.1.6, a free annotation tool for DocBook documents. Based on an extension of the DocBook XSL and a DBMS to store the annotations, it looks to be very useful! There is also an online demo you can try. For more info, check out: http://www.brettnacher.org/annotate/.
Annotation has been added to DocBook v5.0, and is described here: http://docbook.org/tdg5/en/html/annotation.html
Categories: DocBook
I ran into a very interesting challenge lately, and since RoboHelp has been EOL'd, I thought I'd try to benefit the rest of the community that might need to migrate content out of RoboHelp. There is an export handler in RoboHTML that will convert content to DocBook, but unfortunately, it doesn't provide very good or accurate markup, IMO.
Since the default RoboHTML export handler for DocBook wouldn't work for us, we created a new export handler, based on the original. What I wanted, was a book file that contained entity declarations for each topic. The trick was trying to generate the Doctype declaration, with the entity declarations. XSLT provides a way to generate a PUBLIC and SYSTEM identifier in the DOCTYPE declaration for an output document, but does not provide a way to write out the entity declarations as an internal DTD subset in that doctype decl.
Part of the solution is to not use the XML output method, but to use the TEXT method. This was working splendidly, until it came time to write the file entity reference in the content. From what I could tell, the problem is with the msxml parser that RoboHelp uses when exporting content. No matter how I tried to escape the "&", I would get & in the entity reference, which of course would not resolve.
Instead of building it into the export handler, I came up with a stylesheet to process the *_toc.xml file that resulted from the DocBook export.
Here are some snippets from the resulting code. The critical components are generating the DOCTYPE decl, generating the ENTITY decl, and then creating the entity reference.
<xsl:output method="text" indent="yes"/>
<xsl:template match="/">
<xsl:text disable-output-escaping="yes"><!DOCTYPE book PUBLIC "-//COMPANY//DTD DocBook-Based Extension v1.0//EN" "extended-docbook.dtd" [
<!ENTITY glossary SYSTEM "glossary.xml">
</xsl:text>
<xsl:for-each select="//tocentry/ulink[normalize-space(@url)!= '']">
<xsl:call-template name="generate_entity_decl">
<xsl:with-param name="url" select="@url" />
<xsl:with-param name="title" select="@title" />
</xsl:call-template>
</xsl:for-each>
<xsl:text disable-output-escaping="yes">]></xsl:text>
<book>
<title><xsl:value-of select="title"/></title>
<bookinfo>
<xsl:call-template name="generate_publisher_info">
<xsl:with-param name="rootnode" select="." />
</xsl:call-template>
</bookinfo>
<xsl:apply-templates/>
<xsl:text disable-output-escaping="yes">&</xsl:text>glossary;
</book>
</xsl:template>
The above creates the DocType declaration, but relies on generating a valid entity name for the entity declarations:
<!-- =========== generate_file_url template ============= -->
<xsl:template name="entityName">
<xsl:param name="url" />
<xsl:choose>
<xsl:when test="contains($url,'/')">
<xsl:value-of select="substring-before($url,'/')"/>
<xsl:call-template name="entityName">
<xsl:with-param name="url" select="substring-after($url, '/')"/>
</xsl:call-template>
</xsl:when>
<xsl:when test="contains($url,'\')">
<xsl:value-of select="substring-before($url,'\')"/>
<xsl:call-template name="entityName">
<xsl:with-param name="url" select="substring-after($url, '\')"/>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$url"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- ======== outputs entity references ======== -->
<xsl:template name="generate_file_url">
<xsl:param name="url" select="''" />
<xsl:param name="title" select="''" />
<xsl:variable name="transformedURL">
<xsl:value-of select="translate(string($url), ' ()','_' )" />
</xsl:variable>
<xsl:variable name="entity.file.name">
<xsl:call-template name="entityName">
<xsl:with-param name="url" select="$transformedURL" />
</xsl:call-template>
</xsl:variable>
<xsl:variable name="entity.name">
<xsl:choose>
<xsl:when test="contains($entity.file.name, 'htm')">
<xsl:value-of select="substring-before($entity.file.name, '.htm')" />
</xsl:when>
<xsl:when test="contains($entity.file.name, 'xml')">
<xsl:value-of select="substring-before($entity.file.name, '.xml')" />
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$entity.file.name" />
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<!-- outputs entity reference -->
<xsl:text disable-output-escaping="yes">&</xsl:text>
<xsl:value-of select="$entity.name" />
<xsl:text disable-output-escaping="yes">;
</xsl:text>
</xsl:template>
The above templates create a valid entity name, based on the path to the file. I tried to adjust for both XML, HTML and unknown file names. Following is the template that creates the ENTITY declaration that needs to be a part of the internal subset in the DOCTYPE declaration.
<!-- This generates an entity declaration: <!ENTITY foo SYSTEM "foo.xml"> -->
<xsl:template name="generate_entity_decl">
<xsl:param name="url" select="''" />
<xsl:param name="title" select="''" />
<xsl:variable name="transformedURL">
<xsl:value-of select="translate(string($url), ' ()','_' )" />
</xsl:variable>
<xsl:variable name="entity.file.name">
<xsl:call-template name="entityName">
<xsl:with-param name="url" select="$transformedURL" />
</xsl:call-template>
</xsl:variable>
<xsl:variable name="entity.name">
<xsl:choose>
<xsl:when test="contains($entity.file.name, 'htm')">
<xsl:value-of select="substring-before($entity.file.name, '.htm')" />
</xsl:when>
<xsl:when test="contains($entity.file.name, 'xml')">
<xsl:value-of select="substring-before($entity.file.name, '.xml')" />
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$entity.file.name" />
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<!-- outputs entity declaration -->
<xsl:text disable-output-escaping='yes'><!ENTITY </xsl:text><xsl:value-of select='$entity.name'/><xsl:text> SYSTEM
"</xsl:text><xsl:value-of select='$transformedURL'/><xsl:text>"</xsl:text><xsl:text disable-output-escaping='yes'>>
</xsl:text>
</xsl:template>
As you can see, there are several variables that have been reused, and could probably be declared globally or more efficiently. The remaining task is to create the entity reference in the content. Since the RoboHelp export handler dumped everything as a tocentry/ulink, it's pretty easy to extract and re-write the entity reference we really want:
<xsl:template match="tocpart">
<chapter>
<title>
<xsl:value-of select="tocentry"/>
</title>
<xsl:apply-templates />
</chapter>
</xsl:template>
<xsl:template match="tocchap">
<xsl:choose>
<xsl:when test="tocentry/ulink">
<xsl:call-template name="generate_file_url">
<xsl:with-param name="url">
<xsl:value-of select="tocentry/ulink/@url"/>
</xsl:with-param>
</xsl:call-template>
</xsl:when>
<xsl:otherwise>
<section>
<title>
<xsl:value-of select="tocentry" />
</title>
<xsl:apply-templates select="toclevel1"/>
</section>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
The finer details will be left as an exercise to the reader, but this was a particularly interesting problem and solution. Hope this helps!
Sasha Philippov has announced the release of a free command-line tool for DocBook to SCORM 2004 conversion. It is the command-line Ant-based java application intended to generate SCORM 2004 compliant packages from DocBook 4.4 sources. It's free to use but not open source. It uses XSL stylesheets from DocBook project on SourceForge to generate HTML resources.
You can find more information on the tool at: http://pyxx.org/DocBook2SCORM/overview.html
Michael Smith reported an "Unsupported major.minor version 49.0" error with Java 1.4.2, so you may want to use the latest version of Java.
I am also doing some work with clients on authoring eLearning content in DocBook and exporting to SCORM, so I will definitely be giving this a try! Will post my results later...
Update: Sasha has recompiled the converter to support JRE 1.3 and higher.
Big day for XML experts and their new blogs! It looks like Dr. Kay (author of the XSLT Programmer's Reference and creator of THE best XSL parser in the world) is now blogging: Saxon diaries.
If you don't use it already, you need to switch to Saxon (http://www.saxonica.com/). It is simply the most compliant, high performance parser available for processing XML with XSLT. He has also added support for XSLT 2.0 and XQuery.
Welcome to the blogosphere, Dr. Kay!
Categories: XSLT
I've used oXygen for quite a while now, and I completely agree with Kurt Cagel (On XMLish Things: Oxygen).
The app is quite robust, and even better, multi-platform! It is definitely the tool of choice for XML hacks. I first chose oXygen because of its support for RelaxNG and easy transformation features.
The only problem, is that it's not the easiest tool for basic authors who just need to write documents in XML. It's not quite WYSIWYG, so I still often recommend Arbortext Epic or BlastRadius XMetal for those folks.
I think the split tabs could work a little bit better (jEdit is fantastic in this regard), but otherwise very useful. I didn't know about dragging an element from the XML and having the template and XPath already created in the XSL. I think this will be a huge timesaver!
Steve Ball has announced the release of a set of XSL stylesheets to transform DocBook to WordML and back with minimal structure loss. This is indeed a welcome development, as I've faced many painful migrations from Word or Frame to DocBook. Some solutions work better than others, but they ALL require cleanup. I'm very curious to try this method, and see if it is truly painless yet...
More details are available at: http://www.explain.com.au/oss/docbook/. These stylesheets will also be added to the DocBook XSL project in SourceForge in the wordml subdir.
There have been some concerns raised by Jens Stavnstrup, such as a lack of support for Chapter/Appendix, and some issues with Saxon.
Categories: DocBook
Well, another great XML conference has come to a close. It's always a pleasure to interact with the industry experts, and meet all the first-timers! My favorite sessions were David Megginson's closing keynote, Bob DuCharme's schema and XSLT sessions, Ken Holman's XSL case study, and Norm Walsh's XSL unit testing, and Bob Stayton's "Linking outside the box". Thursday had a heavy emphasis on XSLT, but all of the sessions were quite informative.
I learned a fair amount of new things this year. Here are just a few of my take-aways:
Cool things to follow up on:
Did you know?
DocBook XSL stylesheets consist of:
Subversion will allow you to set up pre-commit tests, to make sure all tests pass before checking the code in.
End to end XML processing performance estimates:
Security and Identity Standards in the land of XML are complementary, not overlapping!
MS Linq is over my head...
Limitations of DITA: current stylesheets for FO are very limited, and not production quality. DITA is more complicated to produce output than DocBook.
Targeted search using XQuery in MarkLogic is lightning fast, and enables the creation of a variety of new outputs!
Not enough XML authoring tools provide validation against RelaxNG schemas! Good job, oXygen. Now, how 'bout the rest of you editors? Arbortext?! DocBook v5.0 is here!
I hope to see you all at XML 2006 in Seattle!
Categories: XML, xmlconf2005