[TYPO3-doc] Using Rest - the first steps.

[Fabien Udriot]

Hi Martin,

Actually, your "first" steps come at a good moment. I have just pushed a - yet rudimentary -
doc_template based on reST https://github.com/fudriot/doc_template

I will steal some words from your lines.

Cheers,

Fabien

On 4/20/12 10:52 PM, Martin Holtz wrote:
> Hi,
> 
> i had some first steps with ReST now and i think it would be helpfull to 
> have an basic overview what markup can be used. I just start with what i 
> know so far:
> 
> Like in TypoScript, attention to details matters. Especially newlines and 
> spaces are important!
> 
> =========
> Header H1
> =========
> 
> IMHO the headers are pretty easy. But as far as i know, everybody could use 
> its own style to define the different headers, but we should just stick to 
> one. This three levels are used that way in the FLOW3 documentation 
> allready.
> 
> The Header H1 seems to be used only one time in an rst-File. You can use it 
> more often, but perhaps it make sense to define it only once per file.
> 
> Header H2
> =========
> 
> 
> Header H3
> ---------
> 
> I do not know if they used more then three headers. But i guess usually you 
> do not need more.
> 
> 
> Inline Markup
> =============
> 
> You can mark inline text as *italic*, as **strong** or you can use ``code as 
> inline text``. I guess, there are many possibilities more. If you need to, 
> just escape the special characters (\*italic\*).
> 
> 
> Code
> ====
> 
> .. code-block:: php
>    :linenos:
>    :emphasize-lines: 4,5
> 
>    /**
>     * returns an increased counter
>     */
>    function inc(int $counter = -1) {
>      return $counter +1;
>    }
> 
> As you expect, this would render a code block with linenumbers (:linenos:) 
> and with lines 4 and 5 highlighted.
> 
> It is possible to add the content of an file to show. Search for 
> *literalinclude* in that case.
> 
> 
> .. _link-to-section-links:
> 
> Links
> =====
> 
> Afaik there is a easy syntax to link to a section in the same document. But 
> this syntax described here, does work with cross-references in different 
> documents (f.e. link to TSref or TSconfig).
> 
> :ref:`link-to-section-links` creates a link and uses the section name.
> :ref:`different label <link-to-section-links>` creates a link with linktext 
> "different label"
> 
> You can define an anchor anywhere 
> .. _this-is-a-anchor:
> But if you want to link to that anchor, you need to define an label.
> 
> 
> Footnotes
> =========
> 
> I can add an footnote by adding an link to it: [#]_ This will link to the 
> first footnote.
> 
> .. [#] This is the first footnote you linked to.
> 
> 
> That is what i know so far about ReST.
> 
> greetings,
> martin