[TYPO3-doc] Restoring the official manual example

[François Suter]

Hi Martin,

Thanks for your extensive explanations, as usual :-)

>> BTW I saw you moved some recurring info to a general include file,
>> that's good.
>
> Yes, I think so. FLOW3 docs had _Includes.txt for this I think. But
> please let's have Includes.txt.

Fine with me.

> .. role::   underline

Thanks for the explanations. In this particular case, it's quite 
interesting as I would say that we should not use underline at all, if 
possible, mostly because it looks like links in HTML. I think we have 
enough with emphasis and strong emphasis. I would have to check where 
underlines were used in the official documentation.

> Once I knew how to create textroles on the fly I wanted to demonstrate
> that possibility and thought of 'typoscript' in first place. And
> because its a long word we can define textrole 'ts' inheriting from
> 'typoscript'. And because of the :class: option in the ".. role::"
> directive that defines the 'ts' textrole it works like this:

The other roles are interesting and useful IMO.

> Yes, that's cool. Up to now I had never gotten to the point where I
> had to think about this. Indeed, for our illustrations that belong to
> the documentation we should be using .. figure:: instead of ..
> image::. You can still decide if you make some images like the TYPO3
> logo, if it occurs, just an .. image::.
>
> You should only have to replace 'image::' by 'figure::' in our
> Images.txt file(s). And that's it.

Exactly.

> One more cool thing about figures is that they create crossreference
> targets right away and show up with the caption as default link text.

That's what I thought. I think we should really use "figure" instead of 
"image", except is some special cases where "image" is enough (even the 
use of the TYPO3 logo is not a good example, as this should be part of 
the template used in the rendering anyway).

I'll adapt the example manual accordingly.

> Well, the caption belongs to the .. figure:: directive. And if we have
> it in the included file the caption has to go there. You don't have to
> use the replacement technique with "|img-1|" of course. The you would
> just place the whole directive into your manuscript where it belongs:

OK, that's clear enough. I was just wondering what the impact would be 
for translations, but I would say it's maybe even better if image 
definitions stay in the Images.txt files, as translators can then take 
care of both changing the image and its caption.

Cheers

-- 

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