[TYPO3-doc] TypoScript rendering

[Martin Bless]

Hi Elmar,

>Hello,
>
>I just observe that the TypoScript in my documentation is rendered differently from TSref. 
>
>* http://docs.typo3.org/typo3cms/TyposcriptReference/ContentObjects/Hmenu/Index.html
>* http://docs.typo3.org/typo3cms/extensions/esp/TypoScriptReference.html
>
>Seems mine is based on a little outdated specification.

It's not exactly outdated. The background is this:

The tables in the old TypoScript Reference were very irregular.
Some tables cells contained only some letters and others were
filled with whole chapters. So we decided to translate them into
something different than tables. In ReST source these are
definition list. And besides, we couldn't use tables at that time.

I've put a little bit of "intelligence" into my t3tablerows.py
Sphinx extension. Well, it's rather stupid and just recognises
some patterns we've been using in the old Tsref. I've now added
your "['property', 'datatype', 'description', 'example']" pattern.
Any of those values may be missing but the order is significant.

Nevertheless the definition lists in the ReST sources are only a
workaround. Those page are still hard to read.


Best solution would be:
======================
I've made up a model of how the source could and should be
rewritten here:
http://docs.typo3.org/typo3cms/TyposcriptReference/Functions/Imagelinkwrap/Index.html

So the best solution would be to rewrite the source like in that
example.


Second best solution
=====================
could be to use tables again. The ".. t3field-list-table::"
directive makes that easy. I would consider this solution if the
table I get as a result still could be resized reasonably on a
Smartphone or tablet PC.



> I observe some differences. Which of them matters:
>
>1.) TSref includes at the top:
>
>. include:: ../../Includes.txt

Meanwhile we're usally doing that and recommend it as it
simplifies things later on. But this will have no effect on your
manual at the moment.


>
>2.) TSref contains:
>
>. ### BEGIN~OF~TABLE ###
>. ###### END~OF~TABLE ######


That's just comment and nowhere used at the moment. It tells you
something about your original document.


>
>Pure comments?

Yes, indeed.

>
>3.) Dotted line in mine above container:: table-row:
>
>. ..................................

The dotted line is just comment.




>. container:: table-row

Yes, that's important. This will wrap the content with a 
"<div class="table-row"> | </div>"


BUT: Beforehand a Sphinx extension I wrote and called
"t3tablerows.py" will travel the internal document tree and check
those containers. If a special pattern in the content is found the
rendering ist structurally changed. And your pattern should now be
recognized as well.


>
>4.) I use a property "Example"

Yes, that's it. The module didn't know about it. But now it should
:-)

I've just changed it on the server directly, will still have to
add it to the RestTools.git repository.

>
>5.) Other?

No.

Well, your scheme of properties is simply new to the writer. 

>Thanks

Thank you!

Martin

PS: I triggered a new rendering. Appearance has changed already!


-- 
Certified TYPO3 Integrator | TYPO3 Documentation Team Member

http://mbless.de