[TYPO3-doc] Restoring the official manual example
François Suter
fsu-lists at cobweb.ch
Sun Jul 29 22:15:49 CEST 2012
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
More information about the TYPO3-project-documentation
mailing list