[TYPO3-hci] Documenting Typoscript

[Christopher]

JoH wrote:
>>> In the list for the Extension Coordination Team, we've been having a
>>> little discussion on inline documentation for Typoscript.  Kasper
>>> suggested we move the discussion here as a usablity improvement for
>>> developers in 4.5.....
>> If we are going to document TS, I have one request that comes before
>> anything else I can think of:
>>
>> *ALPHABETICAL ORDER* in property tables!
>>
>> An order like this (GIFBUILDER properties):
>>
>> 1,2,3,4...
>> XY
>> format
>> reduceColors
>> transparentBackground
>> transparentColor
>> quality
>> backColor
>> offset
>> workArea
>> maxWidth
>> maxHeight
>>
>> ...is insane.
> 
> Well, maybe you should reconsider this statement, especially regarding
> things like stdWrap properties.
> Usually things are "executed" in the order of their appearance in the TSref.
> This is why you can't do something like this:
> 
> 10.dataWrap = 1+1
> 10.prioriCalc = intval
> 
> prioriCalc is "executed" before dataWrap, so you won't get the expected
> result here.
> 
> Regarding the GIFBUILDER properties I think it is a good choice to sort them
> by importance and not alphabetically.
> You will use things like XY and format quite often, while maxWidth and
> maxHeight are used more seldomly.

It's of very little importance /why/ the items are sorted 
non-alphabetically. The result is a severe impediment to usability for 
developers.

> Maybe it would be a better idea to have an alphabetical index listing all
> the different properties with links to the corresponding sections.

*Yes*!

I would also like to see a sorting link added to the TSob for the 
purpose of tracking down properties/objects alphabetically (in the TSob, 
it's even more obvious that the given order is important, but it would 
be nice to be able to search a little more effectively).

For that matter, it would not be difficult in principle to write a 
little js switch that sorted the property tables in the online TSref 
alphabetically in response to a mouse click etc...hm...

But I'm sticking with my claim that the order items are shown in is 
entirely crazy. The TSref and extension docs are /references/. I've 
never seen another technical reference where long lists of 
non-memorizable items/objects/properties are neither listed nor 
cross-referenced alphabetically--and don't bother to find one as a 
counter-example, 'cause I'll just call _it_ crazy too ;-)

TS can really only /grow/ at this point, and I don't want to be looking 
at the new TSref in five years and finding it's twice as long as it used 
to be and no better organized...


-Christopher