[TYPO3-doc] Restoring the official manual example

[Martin Bless]

Hi François,

>Hi all,
>
>I worked on restoring the official manual example, adapted to 
>ReStructured Text. This is meant - as before - to be the basis for new 
>official manuals. I have pushed a first version to Gerrit:
>
>https://review.typo3.org/#/c/13084/
>
>I would be very glad for reviews, especially from Martin,

Did that. See patchset #2. Right now you're finding the result of that
patchset here:
http://preview.docs.typo3.org/TYPO3/OfficialManualExample/


[...]

>Some questions I have already:
>
>- for admonitions, I stuck to what we had chosen for DocBook, i.e. 
>"tip", "note" and "caution". Do we want others? Do we want to leave the 
>liberty to use all of the admonitions available? (this would mean having 
>to style them all and also could induce confusion in the editors, for 
>excess of choice).


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


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



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


>- BTW we need to discuss a strategy for storing images. All in one 
>folder or in separate folder along the page tree. I would favor all in 
>one folder, as it would simplify the work of people updating screenshots.

Let's start with all in one folder at the top. If somebody adds a long
gallery to - let's say - something in the appendix he can still create
an extra Images folder nearby.

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


>Thanks in advance for your reviews and opinions.
>
>Cheers

Same - cheers!

Martin