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

[Martin Holtz]

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