[TYPO3-doc] Wanted: Starter document [Re: ReST Migration: planning the next steps]

[Martin Bless]

[François Suter] wrote & schrieb:

>Indeed "official_template" would be the manual to use, after its reST 
>version is cleaned up and updated.
>
>Fabien has actually mentioned (off list) that he was interested in 
>working on that.


Even better! Go, Fabien, go, ...


1. This is the reST source:
http://srv123.typo3.org/~mbless/DOCROOT_SRC/TYPO3v4/official_template/OpenOffice/official_documentation_template.rst



2. The "reStructuredText Demonstration" show what reST markup
constructs we have to think of in general:

http://docutils.sourceforge.net/docs/user/rst/demo.txt

This version already has a bit of TYPO3 styling so its better to read
for our eyes:

http://mbless.de/4us/typo3-oo2rest/02-styling-experiment-ff8700-high-contrast-4/01-demo-by-David-Goodger.rst.html

This is the original version with almost no styling:

http://docutils.sourceforge.net/docs/user/rst/demo.html



3. The field-list-table directive in the (1.) reST source needs to be
rewritten by a normal reST construct.


4. Convention about the markup of the sections (heading levels):

See http://sphinx.pocoo.org/rest.html#sections for a good rule. Quoted
from there:
"""
Normally, there are no heading levels assigned to certain characters
as the structure is determined from the succession of headings.
However, for the Python documentation, this convention is used which
you may follow:

    # with overline, for parts
    * with overline, for chapters
    =, for sections
    -, for subsections
    ^, for subsubsections
    ", for paragraphs
"""

I would go with this. Will look like this (switch to monospace view
please):

#####
Part
#####

*********
Chapter 1
*********

Introduction
============

About us
--------

More details
^^^^^^^^^^^^

A Paragraph about Life, the Universe and All
""""""""""""""""""""""""""""""""""""""""""""

And one more
~~~~~~~~~~~~

Single Apostrophes work well
''''''''''''''''''''''''''''

I noticed in the existing documents that the deeper the nesting was
the shorter the headlines used to be. And they were sometimes pretty
well "hidden" in a jungle of code examples. There it was good to
have clearly visible underlinings again:


Example:
########

Case 1:
*******


************************
So my recommendation is:
************************

    # with overline, for parts
    * with overline, for chapters
    =, for sections
    -, for subsections
    ^, for subsubsections
    ", for paragraphs

    ~, for the next level
    ', for the next level
    #, for the next level
    *, for the next level

Hhm, usually I've seen at the top of single documents the

==============
Document Title
==============

Don't know right now how this fits in. We'll see.


... go, wreSTler go, ...


Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de