[TYPO3-doc] reST migration: status update

[François Suter]

Hi all,

I'm finally taking time to write a bit about the current progress of the 
planned migration of the documentation to reStructured Text.

Two weeks ago I had an online meeting with Martin Bless and Sebastian 
Kurfürst. It was a kind of strategic-technical meeting, with the goal of 
clarifying some ideas and coming out with clear next steps.

To avoid spreading ourselves too thinly we set a clear first goal to 
achieve:

=> publish all English documentation in HTML format, based on reST

It is obvious that translations will be handled in the future too, and 
we're also going to deliver other formats, but having English manuals 
rendered to HTML is clearly the most important thing to achieve and so 
has top priority.

The rendered HTML will be directly accessed when reading a manual 
online. It won't be stored in a database and served dynamically. To 
enable dynamic features however (like comments, first and foremost) we 
plan to load JavaScript files inside the rendered HTML that will call up 
those dynamic features using AJAX. The URL of each HTML page will indeed 
be its URI and used as an identifier.

We are thinking of hosting the documentation on a separate server, using 
the documentation.typo3.org subdomain, as it would make it possible to 
maintain the whole documentation server separately. We have yet to check 
with the Server Admin Team what this entails (they just got mail ;-) ).

The URIs would use the following scheme:

http://documentation.typo3.org/[language]/(product)/(category)/(key)/(version)/

- the language would be option and default to English
- the product would be "TYPO3v4", "FLOW3", etc.
- the category is whatever categories of documents each product has. For 
v4 it would be core references, guides, tutorials, system extension 
manuals and extension manuals
- the key is a unique key per manual. In the case of extension manuals, 
that would be the extension key
- the version is simply the version number. There would always be a 
"current" alias, pointing to the latest version.

Examples:

http://documentation.typo3.org/TYPO3v4/Guide/doc_guide_install/current/
http://documentation.typo3.org/TYPO3v4/Extensions/news/current/

Note for the first example: I used an existing extension key for the 
Installation Guide, but we will probably review these keys and they 
don't need to be so detailed anymore. Indeed we don't plan to package 
the official manuals as extensions anymore. OTOH extensions would still 
be packaged with their manual, whose rendering would be triggered upon 
release to the TER.

The cross-linking is still a rather hot topic, but Sebastian said that 
Intersphinx (http://sphinx.pocoo.org/ext/intersphinx.html) offered nice 
possibilities and it seems indeed promising. We very much want to offer 
solid cross-linking with the new documentation.

As you know from his various posts to this list, Martin had already made 
a lot of tries and tests with reST and it rendering to HTML. One this he 
dug into was how to define tables. Indeed we have a lot of tables in the 
TYPO3 documentation and he felt that the existing reST directives were 
too hard to use. He has now come up with a way to define tables like 
lists, which makes it much easier. This was the last hurdle to really 
start migrating the existing manuals to reST, which is now one of the 
very next steps we are going to take.

Another important next step is the whole triggering of the rendering 
process. Sebastian proposed that we use some kind of job queue. This 
would enable various sources to ask for the rendering of some manual. 
Investigation has barely started here and it's not the purpose of this 
thread to go into more details.

I think I've covered most of the recent stuff. Feel free to ask 
questions (or to correct me if your name is Martin Bless ;-) ).

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch