[TYPO3-doc] Restoring the official manual example

[François Suter]

Hi Martin,

Thanks for your feedback and reworked patch.

> I would like to propose and propagate 'note, important, caution, tip'.
> We can't really prohibit the others. But we can declare them to be
> evil and ban them (socially).  Please read my "definitions" and
> reasonings about how I see the admonitions. I did that directly in
> example form in the manual. Feel free to improve the wording:
>
> http://preview.docs.typo3.org/TYPO3/OfficialManualExample/Chapter1/Index.html

Fine with me. I improved the wording ;-)

>> - still about admonitions: can we give them a title or is a tip bound to
>> be a "Tip"?
>
> "tip" is bound to being "tip". It will show up as "Tipp" though if you
> set the rendering target language to "german". So they are localized.

OK, too bad ;-)

>> - I tried to put the Images folder in "Documentation/", but then failed
>> to refer to it from "Chapter1/Images.txt". Can this be done and - if yes
>> - how?
>
> Simple. Please see the diffs. All paths are relative to the files
> where they occur.

Thanks. Don't what I did wrong.

BTW I saw you moved some recurring info to a general include file, 
that's good. But what's the content actually? What are these roles and 
how are they used in the document? BTW does the example manual contain 
examples of usage? If not, it should IMO.

>> - still about images: rather than using |img-1| as a reference, I used
>> |img-login-screen|. Does it make sense to have more explicit references?
>> I would say yes, because it seems hard to manage the numbering manually
>> on a large manual. Do you agree?
>
> Sure! It's a nice to have.

OK, cool.

A further question about images. What about captions? I'm not sure we 
absolutely need them, but I think it's a better practice in general (I 
mean, the main reason why we never did it before is because we used 
OpenOffice and there was no way you could really attach a caption to an 
image).

 From what I saw in the ReST docs, the caption property is available 
only for the "figure" construct and not for the "image" construct. 
Should we recommend usage of "figure" rather than "image"?

And how does that fit with our included files? Does the caption have to 
go into the included file, along with the "image" or "figure" construct?

Cheers

-- 

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