[TYPO3-core] ReStructured Text in the TYPO3 backend

François Suter fsu-lists at cobweb.ch
Sun May 26 15:04:15 CEST 2013


Hi Michael,

> I have assumed, the "Docs in TYPO3 BE" aims for (please correct me, if I
> am wrong):
>
> (1) having manuals of installed extensions available in the BE
> (2) having manuals of system extensions available in the BE
> (3) having official TYPO3 docs (e.g. references, guides, etc.) in the BE
> (4) having reference files (e.g. NEWS.txt or INSTALL.txt) in the BE

Right, that covers it.

> A nice side effect with (1), (2) and (4) is, that they are already
> locally available: in the "Documentation/" folder of the extension(s) or
> (looking at (4)) somewhere else (to be specified).

They are locally available, but we expect most documentation to be 
ReST-based in the future. This format is not easily readable and must 
this be rendered to a more user-friendly format. Although this may be 
possible locally, it should not be necessary to have such a local setup.

Hence the discussion about being able to download, the "download" action 
here being retrieving the already rendered stuff from docs.typo3.org.

> (3) is the only component, that possibly needs to be downloaded from a
> remote server or repository, right?

Of course this is even more a "download", because there's nothing 
locally to start with.

> In regards to naming... we are talking about an extension key and a
> "name" in general, correct? So, for example "name" used in a menu in the
> BE. "Documentation" sounds ok to me. Another option could be "Manuals"
> for example. Maybe better for end-user, editors, etc.

The discussion was rather about the key, but the name is certainly worth 
a debate too. I have now written to the owner of the "documentation" 
key. Wait and see.

About the name, it could be "Documentation Library".

> Sorry, maybe I missed something, but I am not sure, if we really need a
> remote service at day 1. I mean, a ReST-to-HTML converter (ideally in
> PHP only) is essential but why not focusing on rendering ReST docs which
> are already locally available (in the TYPO3 instance)?
>
> Adding a remote service (in order to download docs of type (3) for
> example) could be developed at a later stage.

As said above, rendering locally may not be trivial. We'll definitely 
make a try with Zeta components - which would enable a PHP-only 
solution. If the rendering is good enough, even if not optimal, it may 
be an alternative. But we can't expect people to have to setup a full 
Sphinx install, just to view their documentation...

For me the idea is mostly to have a central and flexible location for 
all documentation. Obviously the "no-access-to-internet" situation is an 
edge case, but an important one nonetheless. If we can throw together an 
architecture which knows where to look for locally (or remotely - as a 
fallback) for available documentation and provides links to it, we have 
the most important component.

Any other component that renders or downloads (or writes automatically 
with an infinite number of monkeys) documentation can then do its job 
without further complications as long as it stores the result of its 
work in the right place(s).

> Similar thing with PDF creation: nice idea, but most of the ReST docs
> are on docs.typo3.org anyway (docs from the TER, official TYPO3 docs,
> etc.), so if we would have a PDF generator on docs.typo3.org that would
> already be a big step forward.

Absolutely, first have PDF creation on docs.typo3.org. The things is 
that if we have a proper setup to create PDFs on docs.typo3.org, we can 
provide instructions (or packages or whatever) to also do it locally, 
given the proper setup. So making it work in one place also helps making 
work elsewhere.

Cheers

-- 

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


More information about the TYPO3-team-core mailing list