[TYPO3-core] ReStructured Text in the TYPO3 backend

[Philipp Gampe]

Hi François Suter,

François Suter wrote:

> 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?

Contact the author of the documentation extension and ask him to transfer 
the key.
The extension does nothing, but to display an iframe of which the URL is 
defined in the extension settings.

> 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).

IMHO this module should just show a table of all documention and a link/icon 
for each type. If the documentation is not available, grey it out or display 
a download button instead.

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

Something for later.

> 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).

I would prefer if we can just download the PDF for all core extensions. They 
could be offered as a full zip package that can be dumped into 
typo3conf/Documentation/<package-key>/
Translation should then go to typo3conf/l10n/<lang>/Documentation/<package-
key>

> - 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.

IMHO this should be put behind in favor of the PDF rendering, unless it 
turns out that this works pretty much out of the box (which is unlikely do 
to the TYPO3 specific ReST parts).

> - 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.

Second step IMHO. Most docs are not translated anyway.

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

No, please leave it out for the moment. We can add links any time later.

Just some thoughts on this ...
-- 
Philipp Gampe – PGP-Key 0AD96065 – TYPO3 UG Bonn/Köln
Documentation – Active contributor TYPO3 CMS
TYPO3 .... inspiring people to share!