[TYPO3-core] ReStructured Text in the TYPO3 backend

[Ernesto Baschny [cron IT]]

François Suter schrieb am 19.05.2013 21:50:

> Here's the promised second mail (result of the brainstorming session I
> had on Friday with Xavier and Dominique).
> 
> Once we have converted the sysext manuals to ReST, we will have a
> complete ReST-based documentation infrastructure available, since
> official manuals are already in ReST and extension manuals are
> automatically converted (although with a lower quality of result than if
> they are natively written in ReST).
> 
> So we must think about how to handle this in TYPO3 CMS, in the backend
> in particular. The 6.+ Extension Manager dropped the link to the
> OpenOffice file, but it doesn't mean that documentation shouldn't be
> accessible anymore. On the contrary, it is an opportunity to build
> something more useful.
> 
> First and foremost is what to do to enable visualization of the
> documentation, since although ReST is readable, it is not convenient to
> do so. We can of course simply provide a link to the online, rendered
> version, but it is not sufficient, since some TYPO3 installations do not
> have access to the Internet. Some possible scenarios:

> - package rendered documentation with the Core. Possible, but does not
> address all cases, since it doesn't cover extension manuals.
> - offer some download possibility. The same problem exists without
> Internet connection, but at least the whole documentation can be
> retrieved from some other machine and uploaded to the server.

The "offline group" is of course important, but they are used of having
to fetch the documentation somewhere. The vast majority can (and will)
read the documentation online, as this might in future also contain
comments and updates.

So in my opinion offering a download of PDFs for offline reading is
enough for the "offline-users". We don't even need to ship the PDFs with
the Core, but could create a parallel distribution
"typo3_docs-4.5.tar.gz" (or something like that).

I consider rendering the docs as PDF to be a much more important task
than having a ReST HTML converter in the TYPO3 backend. A PDF is self
contained (includes images, fonts) and is a single file (archive). Only
drawback could be lack of cross-linking support.

> - provide local rendering facilities. This is possible as Xavier has
> demonstrated with his "Sphinx" extension [1]. It requires to have Python
> on the server and - of course - Sphinx installation won't work (again)
> if the server is not connected to the Internet.
> - possibly other ideas can come up during the discussion.
> 
> What we thought for sure is that we should define a place where rendered
> documentation is expected to be. This way any backend module that relies
> on documentation would know where to find it, no matter how it was made
> available on the server.

The idea from Jigal sounds nice. But sounds also like a ambitious project.

> Anyway there needs to be some extension managing this: display, possibly
> retrieval too. Would it be the Extension Manager? Or a separate
> extension? Probably the latter is better, since language package
> retrieval was already separated. It would provide a module to view all
> available documentation and make it possible to retrieve it (and also
> provide a Scheduler task for it I guess (probably better packaged as an
> Extbase command controller)). It would be or not be integrated with the
> EM to provide links to documentation there.

I guess the EM doesn't need to have anything to do with it, because the
documentation is more than just "extensions". Noone (except us which
know the old EM) expects documentation to be found in the Extension Manager.

> Going with further ideas we thought it would be nice to provide an API
> for linking to a particular piece of documentation in the TYPO3 backend.
> This could provide some kind of enhanced CSH or maybe even replace it
> over time. It would certainly make it easier to maintain system
> extension "cshmanual". It could also provide a menu in the top bar with
> links to "favorited" documentation (could be customized per user or user
> group).

Yes, that sounds indeed great! CSH are one of the most important pieces
of information with which a regular editor "works" on a daily basis, so
putting more "love" into them (by having them managed as official
documentation by the DocTeam in ReST) would be a great improvement.

Cheers,
Ernesto