[TYPO3-doc] A proposal on how to use ReST markup for TypoScript documentation // imageLinkWrap in Tsref

[Martin Bless]

Welcome to 2013!


Inspired by the thread around:

http://lists.typo3.org/pipermail/typo3-english/2012-December/083986.html
I have reworked the imageLinkWrap chapter in the Tsref:

http://docs.typo3.org/typo3cms/TyposcriptReference/Functions/Imagelinkwrap/Index.html

I'm trying to find a notation that is better understandable
compared to the table-like descriptions of TypoScript we have used
so far. So, here's what I did:

- no legacy tables any more

- use normal ReST sections (headlines) to separate things

- introduce plenty of examples

- give the example headlines a speaking form. Not just "Example",
but "Example enable" for example

- make the examples complete by showing "imageLinkWrap" in
context! do not just write "enable=1" but "imageLinkWrap.enable=1"

- start with a section "What it does"

- add a section "Implementation" with links to the Api

- call the chapter that explains the TypoScript options
"Configuration"

- describe the possible values a TypoScript option may take by
linking to the appropriate "data type" description.

- use text role "Typoscript" where appropriate (like
:ts:`imageLinkWrap`)

- use many headlines within the page to make navigation easier

To do:

- rewrite the already existing "data-type-XXX" sections in the
Tsref so that they have a headline that can be used as explanatory
linktext like shown in the "imageLinkWrap" example chapter with
the ":ref:`my-data-type-XXX` links

- deal with the section "What should get a description somewhere"

At docs.typo3.org:

- improve the "within page navigation"


Keep on writing!

Martin

-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de