[TYPO3-core] ReStructured Text in the TYPO3 backend

[François Suter]

Hi all,

I have made a summary of the comments so far, coupled with the ideas 
originally submitted.

- a dedicated module seems the way to go. It could be called 
"documentation" or "library" (although both keys are already registered; 
"documentation" can be found in TER, last update in 2006; "library" is 
not public).

Could we make a choice for the name?

A nice summary of features has been provided by Jigal:

It doesn't have to be created overnight. We can start with the foundations
- an API to register / detect documentation
- an API to get links to documentation
- a module to provide links to the documentation

About the last point, this module could be seen as a real central place 
to link to all possible documentation, including whatever format is is 
delivered in (OO, ReST, HTML, PDF, txt) and also reference files such as 
NEWS.txt or INSTALL.txt that come with the TYPO3 source.

This extension would also define a central place where documentation 
should be installed or downloaded so that it can be easily found (when 
it is not in expected places like inside extensions).

It would also provide a form of "favorites" menu, definable per user or 
user group.

The JSON format seems the best for BE integration. Problems needs to be 
solved first [1].

The PDF format would be ideal for downloads and offline usage. Progress 
must be made on that topic.

Having all documentation available offline could be achieved using some 
Scheduler task. A package for the Core could also be provided, for 
easier download, but that seems feasible only if it can be automated 
(i.e. integrated in the release script).


- some form of local rendering for the ReST files would be desirable. 
Zeta Components [2] were mentioned in the discussion. It might be 
difficult to render the official documentation with these, but it's 
worth a try, as it could provide a PHP-way of rendering docs. This could 
be part of the "documentation" extension. Other extensions, like 
Xavier's "sphinx" could of course be used too.


- opinions are rather favorable for using ReST for CSH. Obviously it 
would not be a full replacement, current CSH must continue to work as 
is. However ReST should be an alternative and definitely an improvement 
for large stuff such as "cshmanual". Translations could be handled by 
Pootle too.


- integration with the EM: should the "documentation" extension 
integrate with the EM to provide links to documentation? Opinions are 
split here.


Please continue to express yourselves on this topic. Don't hesitate to 
correct my summary.

Based on further remarks I would propose to start drawing a first a plan 
and gather more feedback from the community based on this.

Cheers

-- 

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

[1] http://forge.typo3.org/issues/48087
[2] 
http://zetacomponents.org/documentation/trunk/Document/tutorial.html#xhtml-rendering