[TYPO3-doc] Experiences with ReSTructured Text

[Sebastian Kurfürst]

Hey François,

sorry for not answering your email for such a long time -- I somehow
missed to respond to it...

Thanks a lot for your productive and detailed feedback :)


>> [Extensibility]
>
> This is very important. Indeed one very important manual that we have
> and need to migrate is the TSref (but also TSconfig and TCA
> reference). The current format - in tables in the OpenOffice document
> - makes it impossible to reuse that information in a different format,
> in particular to turn it into a true online reference, which would be
> hugely useful to everyone.
>
> While researching on the migration to DocBook I came to a satisfying
> format for representing the TSref with DocBook [1]. With appropriate
> rendering that structure could lead to have an HTML page per TS
> property, all "keyed" logically by the use of id attributes respecting
> strict naming conventions.
>
> If we should choose to use ReST we need to make sure that we can
> achieve something similar.

OK, let me elaborate on this one a little more.

First, it is very simple to generate any desired HTML URL. Basically,
there is an *1:1* mapping between input and output documents. So, if you
have the input ReST document structure of:

index.rst
quickstart/index.rst
ts/config/global_config.rst

then the output will also be in the files:

index.html
quickstart/index.html
ts/config/global_config.html

In order to include other files, there is the "Table of Contents" tree
directive, looking like:

http://git.typo3.org/FLOW3/Documentation.git?a=blob;f=TheDefinitiveGuide/Index.rst

So, essentially, there are two "dimensions" which one can manipulate.
First, the file structure in the file system,
and second, the hierarchical structure of the document. These two
dimensions do not need to be similar, but it makes sense in most cases I
would say.

One more thing regarding cross-linking: All possible link targets in the
above documents are part of a single index. So, even if somebody would
rename global_config.rst to globalConfig.rst; this would *not* break any
links.

>> Graphviz + UML support
>> ----------------------
>
> Could be nice although it's not a crucial point IMO.
Yeah, that was just to illustrate the extensibility of the platform, as
that is implemented though standard extension mechanisms.

>> Cross-Linking
>> =============
>>
>
> That seems to be clean and easy indeed. Is it actually possible to
> view the index of targets?
Not out of the box, as it seems, but we can create a simple python
script which we can use for that:

http://groups.google.com/group/sphinx-dev/browse_thread/thread/ef92ffdf7aff6191

... or even do some more fancy visualization :-)

> Rendering DocBook to PDF seems to be quite convoluted. It could also
> be a big selling point for ReST if it were easier. Could you go in a
> bit more detail about how it compares?
As said, there are two ways of generating PDF: one using LaTeX and one
using rst2pdf. Here are example outputs:

LaTex: http://sphinx.pocoo.org/sphinx.pdf
rst2pdf: http://sphinx.pocoo.org/sphinx-rst2pdf.pdf

Generally the whole conversion process is also triggered with a simple
command. When using the LaTeX route, one needs LaTeX skills to adjust
the documentation output. For rst2pdf, there is some stylesheet language
for adjusting the styles.

For my diploma, I am using the LaTeX route; but we should also test the
other one and see how difficult/easy the adjustments are.

> Indeed this needs to be tested. The sure thing is that Pootle is not
> appropriate for translation of DocBook format. Every tag gets
> converted to an individual string, making it near impossible to
> translate stuff when there are too many nested tags. This is based on
> a test set up by Laurent Cherpit.
Yeah, however that would not necessarily be a blocker. If we can't find
a good technical solution like Pootle for translation, we can still copy
the document, translate it, and apply the changes to the original
document manually afterwards. That needs some more structure and
planning, but I think it's also possible.

>> Build chain
>> ===========
>
> How would you rate the complexity of setting up and tuning the build
> chain? One thing which kept me worried about DocBook is the use of
> XSLT, which I find really inconvenient to use.
IMHO the build chain is a *lot* easier to set up, as it is just one
easy_install command; and we can use the standard Sphinx build chain; no
custom Phing / Bash / XSLT stuff needed... I once tried to write some
Phing scripts for installing a DocBook build chain and setting it up
correctly; and it was quite complex IMHO...

> About the need for WYSIWYG I would mitigate it. I think it's ok to
> rely on plain text editing as long as there's an easy way to preview.
> This is true both for DocBook and ReST. Indeed some DocBook editors
> give an impression of WYSIWYG but it may actually be misleading (as
> was pointed at by Tom Schraitle quite a while ago). So whatever format
> we adopt eventually, we will need to provide an online service to
> easily preview the HTML format, complete with the skin that applies on
> typo3.org.
Agreed :) I think that would be quite easy for  both ReST and DocBook.

> About the workflow the idea is to deliver only the documentation
> source (DocBook or ReST) with an extension. Rendering would happen on
> the server. This is the only way to ensure a coherent look and feel
> across all manuals. It also solves issues like having the right fonts
> installed for rendering (in case of the PDF format).
+1. Although it is a big benefit that the toolchain can be *easily*
installed locally; and I think that's much more simple with ReST.

Greets,
Sebastian