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

[Jigal van Hemert]

Hi,

On 1-1-2013 13:50, Martin Bless wrote:
> I have reworked the imageLinkWrap chapter in the Tsref:
>
> http://docs.typo3.org/typo3cms/TyposcriptReference/Functions/Imagelinkwrap/Index.html

Thanks for making the attempt.

> - no legacy tables any more
> - use normal ReST sections (headlines) to separate things

+1

> - introduce plenty of examples

It's a reference. Maybe this would fit better in "TypoScript by example" 
or another tutorial. Examples in a reference should only be used if it 
is easier to use an example to explain an option than just a description.

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

Can they somehow be "glued" more to the example itself? It's not very 
clear that the title belongs to the example and that the text below the 
example is a new part of information.

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

Repeating all that is not recommended in blocks of code. If the same 
"path" is repeated more than twice it's recommended to use curly brackets.

> - start with a section "What it does"

I'm not convinced yet...

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

-1 It's a TypoScript reference and an integrator is not really 
interested where it's implemented in the core code. Devs have more use 
for a description of the structures in core documentation and then they 
can easily find the implementation of a particular function.

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

TypoScript is a configuration language by itself, so everything is 
already configuration :-)

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

The current form is rather cryptic:
[tag; stdWrap]
A subsection with type: and default: leaves room for more explanation 
than just a short description.

> - use many headlines within the page to make navigation easier

+1 In-page navigation is useful for more complex objects/options.

> 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

+1

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

eID scripts are described in the core documentation, but are of little 
to no interest to most integrators.

ImageMagick: direct references to IM features should not be used anyway 
IMO. We're trying to make everything that deals with external tools (IM 
/ databases / etc.) as abstract as possible.
Once we support other image processors (such as remote solutions now 
that FAL is in the core) we simply cannot point to IM features; we will 
support a subset of the possible operations.

tx_cms_showpic: again, only describe the options relevant to an 
integrator. It's not even sure what the name of this script is or if it 
will be a standalone script in the future.

I would also prefer as few references to PHP features as possible. Often 
we're lazy enough to directly use PHP functions as the implementation of 
a TS function, but we can't expect PHP knowledge of integrators. Also, 
if the PHP function is somehow changed we will implement the previous 
behaviour in the core routines (for backwards compatibility) and the 
reference to the PHP function has become invalid.

Just a few thoughts :-)

The improvements in the online documentation are great! I'm loving it.

-- 
Jigal van Hemert
TYPO3 Core Team member

TYPO3 .... inspiring people to share!
Get involved: typo3.org