Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

DocTeam/DocBook migration

From TYPO3Wiki
Jump to: navigation, search
This page belongs to the Documentation Team (category DocTeam)

notice - Note

In September 2011 it was decided to not use DocBook as new documentation format. Instead reStructuredText (reST) will be used.
So the information below is outdated.


Goals

This project was born out of discussions about the need to make TYPO3 v4 and FLOW3/TYPO3 Phoenix documentation converge. TYPO3 v4 documentation is still based on OpenOffice, whereas FLOW3/TYPO3 Phoenix documentation is based on DocBook. Furthermore the designs used are not the same, which is not good for users, nor for the TYPO3 brand.

Migrating the TYPO3 v4 documentation to DocBook had been a long-standing idea. The fact that this technology was already used by the FLOW3/TYPO3 Phoenix documentation and the need to converge with the latter has set this project into motion again.

The goals of this project are thus:

  • to migrate all the official documentation of TYPO3 v4 to DocBook
  • to define a common design for TYPO3 v4 and FLOW3/TYPO3 Phoenix manuals
  • to adapt the FLOW3/TYPO3 Phoenix manuals to the common format and design
  • to define a number of DocBook transformations providing professional documentation for TYPO3 and related projects
  • tell the exact line number when a validation error of a manual occurs

Pros and cons

The decision to revive the migration to DocBook for TYPO3 v4 documentation was not preceded by a public (i.e. community-wide) debate. This was deemed appropriate as a) the idea was already in the air, b) DocBook brings some very real advantages to the documentation process.

Pros

  • strict separation of structure/content and design. DocBook describes the structure of the document and stores its content. The design is applied only during the rendering process. This makes it far easier to ensure layout consistency than with OpenOffice.
  • enforcement of structure: it's possible to define the exact structure to be used in the manuals and to enforce using a validation schema (in Relax NG).
  • plentiful rendering possibilities. It is possible to convert DocBook to a wide variety of formats. Such transformations need be only coded once, which means it is possible to create very clean renderings, better than what is achievable from OpenOffice.
  • text-based format. A long-standing problem of the use of OpenOffice was the binary format of OpenOffice files. Because of this it was not possible to keep track of changes via a Version Control System. This restricted the opening of some manuals (in particular core manuals) to more editors, thus creating a bottleneck in the maintenance process.
  • DocBook, once learned is similar and as easy to use as HTML (slight Con: it takes a little time to learn)

Cons

  • DocBook is obviously harder to use than OpenOffice, which is a simple word processor. This is somewhat mitigated by the fact that editors won't need to worry about style anymore. Also the enforcement of structure gives a better framework within which to work.
  • the TER needs to be adapted, although it does use DocBook already (transformation process: OpenOffice => DocBook => HTML). But the TER processes related to documentation are badly in need of a refresh anyway.
  • of course, the existing documents need to be migrated. This is probably going to be quite an important workload, as it is not clear yet whether the export from OpenOffice to DocBook can really be of any use if we want to have clean structures.

Milestones

Below are a number of milestones that represent a first organization of the project into several large steps. This should probably be improved. Some steps can be performed - or at least started - in parallel.

For all milestones you find the issues here: Forge Project DocBook-migration . Just add this a bookmark in your browser.

Milestone 1

Define the DocBook document structure that covers the needs of the TYPO3 v4 + v5 documentation. The result will a Relax NG schema against which all official manuals must validate. The structure will also be documented. A sample v4 manual will be converted during that phase.

Milestone 2

Create all the rendering scripts for the various output formats. This phase includes defining the design for the manuals in various formats (for the HTML rendering this will of course be in line with the design of typo3.org).

Files: First version of API Doc, ter_doc_html/static/css/setup.txt

Dedicated page: DocBook_migration/DocBook_Design_Elements

Milestone 3

Convert the main v4 manuals to DocBook. Modify existing FLOW3 and v5 manuals to match the chosen DocBook structure.

Milestone 4

Make the necessary changes to TER and typo3.org so that the new manuals can be displayed and downloaded properly.

Milestone 5

Provide an on-line tool for collaboratively editing DocBook manuals.

Budget

This project benefits from a budget allocation from the TYPO3 Association, thanks to a budget request made by François Suter.

The estimate for the budget were based on the above milestones:

  • Milestone 1: 3 man-days
  • Milestone 2: 5 man-days
  • Milestone 3: 5 man-days
  • Milestone 4: 3 man-days
  • Milestone 5: 15 man-days
  • Total: 31 man-days

This total is not expected to cover all the work to do (far from it), but to help compensate participants for their efforts and pay for some of the harder or more boring tasks ahead.

Tasks

Most of the actual tasks for the many steps to take have not yet been defined. There are however a couple of early tasks that are up for grabs:

  • Inquire into print-on-demand:
    • what providers are there out there? They should be global players to ensure that TYPO3 manuals can be bought world-wide. Note: one well-known such provider is lulu.com.
    • what are the (financial) conditions of these providers?
    • are there any particular technical issues to consider when preparing a file for print-on-demand?

Brainstorming and notes

Here is a mind map I use for thinking about the project and taking notes. I write down everything, from conceptual stuff down to small details. It's not about project management, it's about trying to think about all aspects.

File:DocBookMigration.pdf

Some other things to keep in mind:

Tools

This is a list of tools that can be used to work with DocBook files.

Applications

Command-line tools

Installing an application is really good only for writing the document, but to have an idea what the document will look like, it is necessary to render it. This is achieved by using DocBook-related tools on the command-line.

Installation

Mac OS X

One simple way to install the necessary tools on Mac OS X is to use Mac Ports.

sudo port install docbook-xml-5.0
sudo port install docbook-xsl

Fedora

Get the required package from repository

sudo yum install docbook5-style-xsl

Files will be in /usr/share/sgml/docbook/xsl-ns-stylesheets/

Usage

Once you have the necessary tools installed, rendering is achieved by calling the "xsltproc" command and using some of the available XSL transformation files. Example:

xsltproc --output reference.html /PATH/TO/DOCBOOK/XSL/xhtml/docbook.xsl ~/PATH/TO/DOCBOOK/FILES/reference.xml

The output of the above command is a HTML file which can be viewed simply in a browser.

Online editors

There are currently very few projects aiming to edit DocBook documents online and most are dead or dormant. As far as we could find during our research the only promising project is the PHP Online Editor. This project is used by the PHP team to work on the PHP documentation (which is based on DocBook).

The hope is to be able to adapt that tool for the TYPO3 documentation. This sub-project has its own wiki page.

Inline editing

There is a very intersting tool used by the Boost project documentation: http://en.highscore.de/cpp/boost/introduction.html

It's a JavaScript library that makes it possible to modify content inline (à la Aloha editor). When the "Save" button is pressed an AJAX script is called. This means it is possible to do more or less whatever one wants. In the case of the Boost documentation, a mail is sent to some person in charge. We could imagine using such a script in the HTML version of the TYPO3 documentation. The AJAX action could be to automatically create a ticket on Forge.

The script be downloaded here: http://www.highscore.de/liveedit.zip

The developer seems available for questions and discussing enhancements (NOTE: francois 17:35, 13 November 2010 (CET) - I have his contact and so does Karsten. It doesn't seem appropriate to put his e-mail address here).