Lars Trieloff's Collaboration Weblog

I have moved the archives of the Software Documentation Weblog to a new location.

For a presentation at the Hasso-Plattner-Institute for Software Systems Engineering I created a custom version of XSL-Stylesheets for the DocBook-Slides-DTD. This version uses DHTML for navigation and CSS for layout of the slides.
If you would like to review the example, you should use an modern Browser like Internet Explorer or even better Mozilla with a screen resolution of at least 1024X768 pixels and fullscreen display turned on. By pressing the space-key you can navigate to the next foil. Other navigation options include:

SPACE

Go to next slide

n

Go to next slide

p

Go to previuos slide

LEFT-ARROW

Go to next slide

RIGHT-ARROW

Go to previous slide

12+RETURN

Go to slide #12 (you can also type any other number)

3+n

Go 3 slides forward

3+p

Go 3 slides backward

t

Show table of contents

Download

A Zipfile with an XSL-Stylesheet, JavaScript for switching the slides and CSS for making the stuff look good can be found here:

dhtml-slides-xsl-0.99.zip

11-06-2003: Fixes Mozilla printing bug #133490 (Alexander Klimetschek)

dhtml-slides-xsl-0.98.zip

10-06-2003: Initial release, but not announced

Customization

You can customize the slides by

• replacing the files resources/biglogo.png and resources/smalllogo.png with your organization's logos.
• Modifying the CSS
• Setting the parameters event (which will control the footer line in the slides) and altlogo (which will set an alternate text for the logos)

Enhancements

The Stylesheets can make use of my Saxon extension for syntax-highlighting code in programlistings. You juat need to install the extension and have the conf dir under the directory from where you start saxon.
If you are using Mozilla, you can create good-looking printouts from the slides by printing on landscape oriented paper with a margin of 0 on all borders.

Take a look at Andreas Bovens page. He shows, how to create very good looking CSS3-based sidenotes in XHTML documents.
Best of all, he shows how to enable these sidenotes in Gecko-based Browsers (Netscape 6/7, Mozilla, Camino, Galeon...) and Apple's Safari, that has just gone 1.0. This feature works completely without any JavaScript, it is plain CSS3.[via dfc]

The problem of creating better two-column output from DocBook documents using the DocBook-XSl-Stylesheets for XML:FO, especially when it come to inserting figures that span two or more columns has been discudded at the DocBook-Apps-mailinglist more than one. The problem is that to create column-wide-spanning blocks, the DocBook-Stylesheets create a <fo-block span="all"> at the appropiate place, but the XSL-FO-specifcation allows this attribute only for direct children of <fo:flow>. This means, that some XSL-FO-processors like Apache FOP or RenderX XEP follow this specifiaction strictly and will ignore this attribute when it is at the wron position. Other processors like Antenna House XSL Formatter or Arbortext Epic ignore the specification and create - in my opinion, more user-friendly - a column-span anyway.
To overcome this problem, and to have the possibility of using FOP for the elaborations of an University lecture, Alexander Klimetschek and me created a small java program, that will read a XSL:FO-file with incorrect placement of span="all" and create one with correct placement. At the beginning of this article you can see a screenshot the result.

How does it work?

The program works very generic. You can search for elements by entering an XPath define, in a configuration-file, namespaces and special attributes and then perform following transitions to the document for the first element that matches the XPath: A document fragment that looks like this will be converted into this: this means, the parent of our matched element will be split up and the matched element will move one level up in the document tree without affecting the order of content in the document.
With this behaviour we can find elements that contain the attribute span="all" and are not direct children of <fo:flow>. The program will continue to split and move, until no single mis-placed element remains.

How do I use it?

You will need a Java Runtime Environment installed on your machinhe in oder to run this program, because it was written in Java. Next you need to download the program package and install it anywhere.
It is called as following:
java -jar xmlflatener.jar [-c CONFIG.FILE] [-o OUTPUT] XPATH INPUT The distribution conains a configuration file config.properties which fits well for XSL:FO. The XPath expression that adresses the problem described above is //fo:flow/*/fo:block[attribute::span='all'], so that the resulting command to convert file wrong.fo into file correct.fo would be:
java -jar xmlflatener.jar -c config.properties -o correct.fo "//fo:flow/*/fo:block[attribute::span='all']" wrong.fo

When I use it with Apache FOP, FOP complains about duplicate ids

This is a bug in Apache FOP, because there are actually no duplicate ids, because the configuration prevents ids from being copied into the upper and into the lower virtual parent element, they are only copied to the upper element.
If you experience this problem, you should download the patched FOP, that Alexander Klimetschek has created. It will simply ignore the error messages and continue rendering.

If you would like to surpress the Doctype-declaration in HTML/XHTML output of the DocBook-XSL-Stylesheets, as trainedmonkey does, you are perhaps served with this customization layer:

   1:<?xml version='1.0'?>
   2:<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   3:                version='1.0'
   4:                xmlns="http://www.w3.org/TR/xhtml1/transitional"
   5:                xmlns:saxon="http://icl.com/saxon"
   6:                xmlns:lxslt="http://xml.apache.org/xslt"
   7:                xmlns:xalanredirect="org.apache.xalan.xslt.extensions.Redirect"
   8:                xmlns:exsl="http://exslt.org/common"
   9:                exclude-result-prefixes="#default">
  10:
  11:<xsl:import href="/usr/share/sgml/docbook/xsl-stylesheets-1.60.1/xhtml/chunk.xsl"/>
  12:
  13:<xsl:param name="chunker.output.omit-xml-declaration" select="'yes'"/>
  14:<xsl:param name="chunker.output.standalone" select="'no'"/>
  15:<xsl:param name="chunker.output.doctype-public" select="''"/>
  16:<xsl:param name="chunker.output.doctype-system" select="''"/>
  17:<xsl:param name="chunker.output.media-type" select="''"/>
  18:
  19:</xsl:stylesheet>

You will have to, of course, edit the import-statement on line 11 to your local copy of the DocBook-XSL-Stylesheets or to http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl

Bob Stayton has released the second edition of his complete Guide to the DocBook XSL-Stylesheets. His book is available as eBook for 30 US$ and as printed Book for 40 US$ and online for free.
This book is a must-read for everyone working with DocBook and the DocBook-Stylesheets.

Mark Derricutt reports about a quite sucessful attempt to roll out DocBook as documentation format at this workplace. He has created a CVS module with all required libraries to create PDF or HTML from a DocBook source, along with a build.xml for ant to automate the generation. The XML Editor of choice is XXE, as most writers are used to write documentation in a WYSIWYG-manner.

This day brought us the releases of two WYSIWYG-XML editors. Both editors are very usable, and follow a similar approach, so I will try to review and compare them here.

Syntext Serna 1.0

Serna is developed by Syntext, an American company and is unique, because it is the world's first WYSIWYG-editor that uses XSLT and XSL:FO to render the document. While editing, a XSLT engine will transform the edited XML buffer into XSL:FO which will be rendered on the fly to the editing window. The effect is that your XML document appears more or less in the same way as it may look if you print it. More or less, because the XSL:FO engine does not implement every detail of the specification (but a reasonable amount, even tables with row- and columnspans) and it displays metainformation that would not be visible in the printed document. Usability: The XML editor is written in C++, using the QT library, so the application is quite fast and integrates well into the desktop environment (It does not pick up qt or kde-styles, though). It will work under Windows, Linux and Mac OS X. You can edit the document using keyboard shortcuts and menu entries, so you can be very quick after a short learning span. Additional features: Serna includes a spell-checker (based on aspell, which is good), modularization of documents with the means of external entities and publishing to HTML and PDF using RenderX XEP or Apache FOP is XSL:FO-engine. Supported XML vocabularies: Serna includes stylesheets for DocBook, the Darwin Information Typing Architecture and, in the near future, TEI. It is also possible to add own XSL-stylesheets to support custom vocabularies. Extensibility and customizability: You can customize Serna's user interface by adding or removing menu items and toolbar item through a XML-based user interface description. Additionally there is support for Python scripting. Pricing and availability: Currently there is no pricing information available, but you can register for a free 30-day fully functional evaluation version.

XMLmind XML Editor 2.5

XMLmind XML Editor (XXE) is a structured document editor, developed by Pixware, a small french software developing company. It uses CSS to style the document and it's CSS engine adds some very powerful extensions to CSS to make it possible to edit both XML document formats (like DocBook), but also XML application formats (e.g. time tables). Unlike Serna it is strictly structure-oriented, so it will convert all internal entities to their corresponding value and offers no code view. Usability: the program is written in Java, which makes it available for every platform that has a Java VM (like Windows, Linux, Mac OS X), but results in limitations concerning the desktop integration (different look and feel, no drag and drop for Linux) and the speed of the application. All editing commands can be reached via menu items or keyboard shortcuts and modeless dialogs, which makes working with it really easy, especially if you have learned the important editing and navigation shortcuts. The set of editing commands is more fine-grained than Serna's which is good, if you know what you want to do and bad if you are fightened by more than ten items in a menu. Additional features: XXE has an integrated spell checker, which is as usable as Serna's (it also has features like "skip checking this element", which is very useful for skipping programlistings), but the dictionary seems to be smaller. The editor has very good support for modularized documents using external entities and XInclude. The professional version makes it even possible to edit document parts that are in different files. Supported XML vocabularies: XXE has support for DocBook, XHTML, DocBook Slides and simplified DocBook. It is also possible to add support for custom vocabularies by proving a matching CSS stylesheet. XXE allows it to convert the current document to HTML and to PDF (using a plugin which is available only for the professional version) Extensibility and customizability: XMLmind XML editor is very customizable. You can write extensions in Java and modify the configuration for each vocabulary to add custom action when adding or changing elements. There is a extensive guide for developers who want to customize XXE, and if you buy the professional version you will also get the source code. Pricing and availabilityThe standard edition is available for free, but it has some limitations, the professional version is available starting at 220 USD/EUR and offers source code and free updates. The professional edition does also offer sophisticated distribution and deployment solutions for larger organizations.

For all users of the Mac OS X presentation program Keynote, the XML specialists at zveno.com have come up with an interesting solution that will allow you to create presentations in DocBook (the Slides DTD to be precise) and transform it to a Keynote presentation with full support for slide transitions and slide masters.
The underlying file format of Keynote is XML and thus it is possible to create, given the content in DocBook XML and the styling in form of an empty Keynote presentation, complete presentations for Keynote,
The DTD and Stylesheets for DocBook Slides can be downloaded from sourceforge.net.

Microsoft's new operating system, codename Longhorn will include a completely new online help system. Previous versions of the Windows operating system used the CHM format, which was essentially HTML compiled together with a searchable index and a table of contents.
For Longhorn the help system will rely on a new XML-based markup-language called MAML (Microsoft Assistance Markup Language) which will offer semantic markup instead of presentational markup which is common for HTML. The authors will not mark up how the text potion should be displayed, but what it represents,
Other features of the new markup language are very similar to what is known from DocBook or DITA: conditional markup and reusable content.
The next version of the Windows operating system is scheduled for release in two years, but if you are creating online documentation for the windows platform, you should take a look at "Microsoft 'Longhorn' Help Highlights" by WritersUA and the Longhorn Help Authoring Guide, which is still incomplete and subject to changes, but it shows the basic principles of the new help system. [via Gary Conroy]

Norman Walsh has created a first draft of what he would like to see as the next major DocBook version. Read his posting for more information.

There is an interesting article by Martin Fowler on Writing with XML. He points out the advantages of using XML as base format for writing does not go into technical details. I consider this article a good starting point for writing structured documents with XML. [via Der Schockwellenreiter]

I have found two great tool for creating XML Schema documentation. They become a lot more useful, if you add xs:annotation and xs:documentation to each element, type and attribute.
The xs3p - XML Schema Documentation Generator is a web-based documentation generator which creates nice single-page output and Bluetetra Soft offers a Java-based documentation generator which creates hyperlinked multi-page output.

If you are interested in technical writing, you should read everything on this page. It even provides tips on hiring a technical writer, if you don't want to write yourself. Thanks to Darren Barefoot for the link.

Usable Help links to an interesting article about Manuals in Extreme Programming projects. The first point should apply to all documentation: Keep you manuals, short and to the point, otherwise your readers will not read it, and if they do not read it, the manual will add no value to the product. The second point is about integration of technical writing in the XP project lifecyle, As Extreme Programming involves short incremental releases, the documentation should also feature short incremental cycles and should be at at least one cycle behind the implementation. The challenging part is to tighten the workflow of writing, editing and reviewing that it will fit between two releases.

Alexander Klimetschek has set up a website for DocSynch, an universal approach to collaborative text editing over IRC. The idea is to exchange information about added and deleted characters in an IRC channel via special messages. The protocol is editor-independant, but currently there is only one reference implementation for jEdit.
The next implementation will be an Eclipse plugin and later perhaps a VIM extension.
Currently the protocol uses an editing token that will be handed over to the current editor, in oder to start editing you will need to grab the token and release it after editing. Future version will support automatic token passing which will make the dynamic editing transparent to the user and it will appear as if two persons can edit the same document at a time.
The website also offers an interesting list of resources on collaborative real-time editing.

A German post about a German book. If you cannot understand this post, you will not be interested in it's content.

Permalink | Comments[0]