[TYPO3-doc] Reference of Typo Script

[Peter]

Tyler Kraft wrote:
> Poor poor Peter... I bet he never thought his off the cuff bit of 
> frustration would end up being discussed like this ;-)
hehe. No go on! That is exactly what I wanted!

Cheers
Peter
> 
> 
> 
> Matthew Manderson wrote:
> 
>>> What happens when there is a crucial piece of info ina
>>> page comments section but not in the documentation that gets installed
>>> with an extension?  ITs not there and potentially never realised to
>>> exist - which I can say form personal experience is very very 
>>> frustrating.
>>
>>
>> So true - disjointed distributed knowledge!
>>
>>
>>> Maybe these examples are the starting point of what should be collated?
>>> Matthew whats your though reagrding this?  I assume they - these
>>> comments - still exist somewhere that we could request to get them...
>>
>>
>> I wish, I have asked without expectation of a reply yet but at least 
>> to flag
>> awareness that user annotations tend to be very well thought out and
>> extremely valuable to TYPO3 users generally.
>>
>> Extensions and documentation. Well one approach is that the EM does 
>> flag new
>> versions so if the .sxw has been updated it will at least warn your BE 
>> for
>> you to update the extension/docs as appropriate.
>>
>> At this stage I am unfamiliar with the mechanism for insterting updated
>> documentation. From time to time I resubmit an updated .sxw to the author
>> but as yet I have not seen the doc available for download. This must 
>> partly
>> be down to the individual and their workload to update docs.
>>
>> Ideally I would expect to pass the key so to speak and allow TYPO3 
>> users to
>> make changes on the fly and trust them not to screw it up.
>>
>> This is partly what the annotations do but of course, many annotations do
>> not make it into the docs and to some degree why should they. The docs 
>> are
>> struggling to be concise tutorials and references. Many annotations are
>> more like TSbyEX type additions rather than core and can be quite long.
>>
>> If the journey from typing some useful example of TS or other TYPO3 
>> related
>> snippets to the docs / annotations is too cumbersome and especially if 
>> the
>> result is lost or never published the motivation is lost.
>>
>> We now have wiki / .sxw / online docs / lists and currently inaccessible
>> annotations.
>>
>> I proposed an idea a while back that the paper docs contained the same
>> references as the online docs in such a way as urls from the paper .sxw's
>> could lead you straight to the online doc where you can find annotations.
>>
>> I never developed it back then but perhaps if the document titles were
>> structured say "4.1 /tsref/conditions/" This .sxw chapter title would 
>> have
>> the same url as the relevant page on typo3.org ie
>> typo3.org/tsref/conditions/
>>
>> If presumed all documentation was structured similarly you can see how 
>> each
>> parent page on typo3.org would contain the necessary HMENU to navigate
>> quickly to the relevant detailed section found in the .sxw
>>
>> Going back to the collation of information, if the old annotations can be
>> recovered then they already provide a lot of structured content as a
>> starting point.
>>
>> Gaps along the way can be filled in from refined searches of the 
>> archives.
>>
>> Several other non TYPO3 sites have grown up with great content so we 
>> can't
>> deny the search engine its role in pulling together the disparate 
>> content.
>>
>> If we make sure the lists and the docs and the annotations are reliably
>> accessible to the search engines then this is a big step in the right
>> direction.
>>
>> Picking up on Tylers suggestion of simpy rebuilding tsbyex then this 
>> is also
>> possible. The danger as I see it is 1) effort on rewriting something that
>> is already written 2) not flagging up that tsbyex is now a NEW document
>> counteracted by the fact that tsbyex2 would be yet another document to
>> stack on the TYPO3 library shelf.
>>
>> I think the emphasis should be search first .sxw second
>>
>> Matthew
>>
>>> Matthew Manderson wrote:
>>>
>>>>> I am still a friend of user comments under each webpage.
>>>>
>>>>
>>>> +1
>>>>
>>>> It also has the important spin off of being indexed by the search 
>>>> engines
>>>> and so easily accessible to users in the context of the formal
>>>> documentation.
>>>>
>>>>
>>>>
>>>>> http://typo3.org/ts/datatype/gettext
>>>>
>>>>
>>>> This is a really interesting idea.
>>>>
>>>> On this basis if documentation was xml structured both the print and 
>>>> the
>>>> typo3.org web versions could possibly be maintained from a single file.
>>>>
>>>> Even smarter maybe the idea of allowing the edited version to be online
>>>> say as in the wiki format and as a printed version was required it 
>>>> could
>>>> be generated on the fly with or without the annotations. Using only XML
>>>> stylesheets to format the appearance for either version.
>>>>
>>>> Good.
>>
>>
>>