DocTeam/ReST migration
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 ReST. Furthermore the designs used are not the same, which is not good for users, nor for the TYPO3 brand.
Migrating the TYPO3 v4 documentation away from OpenOffice had been a long-standing idea. The fact that ReST is 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 ReST
- 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 ReST 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 ReST for TYPO3 v4 documentation was preceded by a public debate in the mailing lists in September 2011.
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.
Milestone 1: Create a sample manual
and https://svn.typo3.org/TYPO3v4/Documentation/official_template/trunk/DocBook/manual.xml
Martin's rendering of this manual in reST: http://mbless.de/4us/typo3-oo2rest/The-TYPO3-Sphinx-Theme/build/html/doc_official_documentation_template/official_documentation_template.html
This finishes step 1.
Milestone 2: Create the rendering scripts
Most things are easy to do.
Problem: Complex tables
Idea to use a directive "list-tables": Write content as unordered lists => transform them into tables.
Even better: "field-list-tables". Creates a better structure in the reST-document. Fabien Udriot is working in that direction, too (related to the BLE projects).
Milestone 3: Convert the main v4 manuals to reST
Several ways to convert OOffice documents.
1) use XSLT transformation for converting the underlying XML
2) open a OOffice file, convert to HTML and write reST with docutils by adding a reST writer to docutils
Martin B. favors method 2.
Milestone 4: Make the needed changes to TER, typo3.org and the EM so that the new manuals can be displayed and downloaded
Have HTML, maybe with comments
Maybe also for extensions (optionally)
Milestone 5: Provide an environment for producing reST
Do what's possible to improve the user experience of writing reST. Ideas include:
1) have a service where people can upload their reST file and test the rendering (to avoid having to install Sphinx on their computer)
2) contribute improvements to http://rst.ninjs.org/ (open source, see: https://github.com/anru/rsted)
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:
- 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
Tools
This is a list of tools that can be used to work with ReST files.
Applications
Installation
Usage
Online editors
There are currently very few projects aiming to edit ReST documents online and most are dormant.
One project is http://rst.ninjs.org/. It is open source, see: https://github.com/anru/rsted.
Inline editing
There is a very interesting 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).
