[TYPO3-doc] Experiences with ReSTructured Text

[Sebastian Kurfürst]

Hey Xavier,

Thanks for your detailed thoughts on the topic!

> I say that because until now I still did not find anything that could
> output a document as pretty as when created with LaTeX. Of course, we
> don't want to write documentation in LaTeX but still, we should have a
> really nice PDF output if we want people to switch from their
> most-liked WYSIWYG editor.
Well, ReStructured Text / Sphinx *outputs LaTeX*, which is then
converted to PDF. So, it is easily possible to adjust the conversion to
LaTeX, using custom styles, etc. The reason that the PDFs I sent "do not
look like LaTeX" is that ReST by default uses a custom LaTeX document
style -- for whichever reason.

So, to cut it short: We can fully adjust the intermediate LaTeX
representation; and if something is generatable in LaTeX, we can also do
it in ReST.

> This is depending on the language you write in... did you try with
> French (using "Chevrons") and German (with "double-comma" at the
> beginning)? What about additional typographic features such as quotes
> inside quotes which behave differently? => single quotes
> (opening/closing) in English, "English" quotes in French, ...
I am not sure about this; I guess they don't do any magic there, and if
we'd need it, we might be able to adjust it. However as most of our
documents are english anyways I think that's not really an issue.

> What about emphasized word within an emphasized paragraph? => should
> be (back to) regular in common typographic rules but the editor should
> not bother with that...
IMHO that's what will happen.

[code blocks]
> What about additional features such as highlighting lines? Or
> integrating links within a code block or making some part of the code
> "bold"?
That's still an issue right now; it is not possible to use "bold",
"links", etc inside a *syntax highlighted code block*; i.e. right now
you need to decide if you want to use bold, links, ... or syntax
highlighting.

However, in practice that's not really an issue IMHO. If you link inside
a code block it will most likely be based on some rules, f.e. link TS
Snippets to the TSRef, or Fluid ViewHelper Tags to the VH reference. And
that again would be possible by adjusting the code highlighter.

> I can easily take that for true, writing plain text is easier than
> writing XML. But is it easier than writing a documentation with
> OpenOffice or Word (:D) ? Because once you know the pitfalls in those
> editors, you still can do real good documents and very easily (I'm
> definitively not a Word adept, nor an OpenOffice adept but I must say
> that this has some good features and relatively good UX anyway).
I can just speak for myself: My writing productivity has enormously
increased, both compared to OpenOffice and to DocBook. We had to write
the Extbase book in OpenOffice...

> Very nice being able to extend it but if we start using it for
> documentation and replacing the OOo format, we have to make sure that:
>
> - it's straightforward to install and start writing (download,
> install, use, period)
> - output is already preconfigured to render as well as the current
> OpenOffice output (if not better)
> - anybody may without taking hours, reproduce any common needs of
> current documentation (picture, code block, enumerated lists, links,
> references) - just take current TSref with all missing intra-links, it
> should be dead easy to do that
It is easy to set up and of course we'd deliver all the "TYPO3 Corporate
Identity" styling.

    easy_install -U Sphinx
    git clone git://git.typo3.org/FLOW3/Documentation.git
    cd Documentation
    make html # on windows: make.bat html

> and once again, the output should really be pretty! I don't ask for
> the same polish as in LaTeX but PDFlib is a no-go for user acceptance.
As already pointed out: The PDF output *is* LaTeX :-) so we can style it
any way what is possible with LaTeX.

> What is your idea for extension authors? Should they publish a ReST
> source and some server will create the PDF and HTML out of it or
> should they distribute, let's say, the PDF as well? Allowing them to
> output the PDF with any workflow they like best, if wanted?
IMHO We should allow them to publish ReST source, and convert it to
HTML, PDF, ... on the server side.

However, if they want to use another documentation format, they'd need
to deliver the PDF.


Greets,
Sebastian