[TYPO3-doc] using reST for printed documents

[Xavier Perseguers]

Hi Michael,

> We are considering creating company-internal manuals (e.g. training
> material for TYPO3 editors we train) in reST format (well, converting
> existing manuals into reST). In most cases, we provide a printed version
> of these manuals during our training sessions and offer an electronic
> version as PDF.
> 
> I wonder if someone already tested such a process, e.g. a working
> "output-to-PDF" workflow, etc.? I would also appreciate any comments,
> practical tips, known issues and challenges around using the reST format
> as the basis for a printed version of the document at the end. Things
> like having page breaks, etc. come to my mind.

There is basically no big deals creating PDF. I use the following
workflow since months and it works really well:

- English documentation in ReST, stored in a Git repository
- When I push to Git, this is done automatically:
	- Content is extracted and put in Pootle (same as
translation.typo3.org) to let me translate it (currently in French,
German and Italian)
	- JSON version is compiled from ReST and pushed to my website
(integration into TYPO3 with EXT:restdoc [1])
	- PDF version is compiled with LaTeX and pushed to my website
	- Localization is extracted from Pootle and used to generate alternate
versions of JSON and PDF and pushed to my website

You can see the result here: [2]

To output as PDF, you have basically two ways: rst2pdf and LaTeX.

With rst2pdf you will only get basic rendering, not something really nice.

With LaTeX, you will ask Sphinx to compile as LaTeX project and then
compile it as any LaTeX project (Makefile provides a shortcut
instruction for doing both at once but the workflow is still the same).

The ReST-LaTeX section in the wiki is quite sparse ATM [3] but for
out-of-the-box rendering, what I actually do for [2], you've nothing to
do, standard output is already quite nice.

With LaTeX you have a professional typographic system, and really good
output automatically. If you need more, you may:

- Change the default template and providing yours (started for TYPO3,
see [2] for a few pointers but WIP)
- Add LaTeX-specific markup in your ReST document [4], something I would
avoid a bit if possible but I did in my own extension documentation to
get a pretty ChangeLog table when my documentation gets compiled as PDF
(see tabular instruction in [5])

and of course:

- Do not use ReStructuredText but LaTeX for your whole documentation.
This way you have full control over typography (but you won't be able to
integrate your documentation into your website as nicely as with ReST)

As said, you can integrate your ReST documentation into your website
with EXT:restdoc [1] and since yesterday you may integrate it into the
Backend, along with other manuals with EXT:sphinx [6]. Please see [7]
for instructions. The Sphinx Documentation Viewer I describe is a WIP
and will probably get merged (either completely or partially) as part of
the workshop Francois Suter and I will hold during the TYPO3 Developer
Days in July, please see the recent news about it: [8]

I hope I answered your question and you now have a few pointers to move on.

Kind regards
Xavier


References:

[1] http://typo3.org/extensions/repository/view/restdoc
[2] https://www.lionsbase.org/resources/documentation.html
[3] http://wiki.typo3.org/Rendering_reST_on_Linux#Installing_LaTeX
[4]
http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw-directive
[5]
http://docs.typo3.org/typo3cms/extensions/sphinx/_sources/ChangeLog/Index.txt
[6] http://typo3.org/extensions/repository/view/sphinx
[7]
http://docs.typo3.org/typo3cms/extensions/sphinx/Development/SignalSlots/RegisteringCustomDocumentation.html#custom-documentation-sample
[8]

-- 
Xavier Perseguers
Release Manager TYPO3 4.6

TYPO3 .... inspiring people to share!
Get involved: http://typo3.org