Expand | Collapse

2. Quick start ▶

1. Introduction

1.1. What is xhtml2to1?

It is a set of XSLT stylesheets for publishing XHTML 2.0 documents, converting it to the XHTML 1.0 format which can be read by Web browsers.

It is geared towards technical documentation that is mostly static (as opposed to a blog site, or photo gallery, for example), and requires highly-structured, careful markup (as opposed to a Wiki).

Consider it as an alternative1 to DocBook.

1.2. Features

  • Clean, pretty, modern XHTML and CSS output
  • Judicial use of client-side JavaScript to improve usability2
  • Documents are not monolithic, thus enabling incremental processing
  • The tool is well-documented
  • Modular and easily extensible3
  • Extensions to XHTML (from a separate XML namespace) are used for footnotes, cross-referencing, indexing, and literate programming.
  • Most features written in pure XSLT 1.0, with optional use of non-XSLT extensions

1.3. Why use xhtml2to1, and not DocBook?

In a nutshell, DocBook being such a complex beast, it is not generally easy for a user to wade in and customize the presentation or add new semantic markup. DocBook processing can also be quite slow in some areas. (On the other hand, DocBook is advantageous in being fairly standard, with lots of off-the-shelf tools that work with it.)

Of course, it is usually easy to criticize something and much harder to come up with the correct fix. The present program, xhtml2to1, is the author’s attempt at that fix, developed after years of using DocBook. He hopes that the quality of its output, and the quality of its construction, will convince the reader that he has succeeded.

Another XML documentation system is the tbook System for XML Authoring, which the author of xhtml2to1 came across after already started xhtml2to1. The author of tbook also makes some criticisms of DocBook, that this author partly agrees with. But the goals of tbook are different from those of xhtml2to1: tbook focuses very much on print output of non-computer-technical documents, and is more LaTeXy; xhtml2to1 focuses on online use (e.g. for literate programming) and works more like HTML web pages.


Notes

  1. xhtml2to1 works a lot like the DocBook Website document type, but based on XHTML rather than DocBook.
  2. Unlike the DocBook XSL stylesheets, which seem to be stuck in the iron age with regards to its support for Web browser features.
  3. Yes, the DocBook XSL stylesheets are modular in theory. But DocBook and its stylesheets are usually too complex to extend for most users. Note, for example, in all these years, nobody has added much real CSS and JavaScript support for its HTML output.

Formatted using xhtml2to1 by Steve Cheng.