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

[François Suter]

Hi Martin,

> I have reworked the imageLinkWrap chapter in the Tsref:
>
> http://docs.typo3.org/typo3cms/TyposcriptReference/Functions/Imagelinkwrap/Index.html

Thanks for your brave attempt at this difficult topic.

I think all your changes are globally an improvement, but we're clearly 
not there yet. Most importantly I think we loose one very important 
aspect with your proposed changes: the quick overview of all available 
properties.

IMO this is the single most important thing that people want to see 
quickly. Indeed, it's all about being a "reference". With all the 
constraints that it implied, it is something that the table layout did 
nicely: provide a quick overview of all the properties. Now they are not 
well visible.

So I'm fine with having a short introduction, but I would move all 
examples to the bottom (where they can be reached with one click anyway 
if we have a good "intra-page navigation"). I would put the list of 
properties (Configuration) right after the introduction.

The list of properties is also not readable enough IMO. Those small grey 
headings are just too bland. Can we attach attributes to sections? The 
idea would be that sections representing properties get a special class 
upon rendering to HTML, so that we can style them differently, for 
example by adding an icon in front of them. Or have some form of visual 
separation, a line below each property, for example.

It's a good idea to try and place the default value the way you did, but 
we should take into account that it may not always be a simple value (I 
don't have examples at hand now).

> - 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

Yes indeed. We should be able to link to each data type description. 
Actually Christopher introduced labels (and you can see them translated 
to id attributes in the rendered HTML), but they are not recognized by 
Sphinx because they are not attached to sections.

> - improve the "within page navigation"

Definitely.

Cheers

-- 

Francois Suter
Cobweb Development Sarl - http://www.cobweb.ch