[TYPO3-doc] Reference of Typo Script

[Tyler Kraft]

Hi Matthew,

First I have nothing but utter respect for you, and your contributions, 
as I've found many times your comments have been helpful to me also. but 
I disagree on some of these points.


> They struggle to make sense of the multitude of information and TSREF
> remains one of the harder documents to read between the lines and see
> exactly how things like userFunc can help them.

As it is reference manual and not a tutorial, one would expect that. 
And rightly so.  Perhaps to get a better understanding of how TSref (or 
individual parts of TSref) can be of more use to them they should first 
study things like Typoscript syntax in depth, MTB 1, 2+3, templavolia, 
and Typoscript by example.  TSref is not meant to be a learning guide - 
the clue is in the name.

There is no reading between the lines so much as looking up different things



> 
> In my experience TSREF could be improved with links to more detailed
> documentation and more detailed practical examples. We share practical
> examples daily so it should not be difficult to research relevant ones from
> the archives to insert as needed. Adding actual links to current
> documentation and or websites is not very practical given TYPO3 does not
> have an integrated document referencing system. These links and references
> will change. 

I agree that having more examples would probably be helpful to all, but 
*not* in TSref.  As stated above it is a reference manual, so links or a 
more "Essential reading and resources" section in TSref that lists other 
places and literature to find information would be acceptable, I think 
the majority of users - myself included - would find a new TSref full of 
basic examples very frustrating to use and rather unwieldily! The last 
thing I want to have to do is wade through an extra 100 pages in TSref 
because newbies can't look up how to build a menu from the numerous posts.



> I have been considering a new Typoscript by example, let's call it volume 2
> that could act as a suitable repository for advanced contributed snippets
> and examples.
> 
> If this TSbyEX2 could be structured along the same format as TSREF then the
> two documents could work together and be cross referenced as a valuable
> technical AND practical resource.
> 
> I would presume beginners to start with the practical TSbyEX2 and refer back
> to the TSREF as needed and Developers would appreciate the convenience of
> TSbyEX2 on unfamiliar areas.


I think this makes very very good sense, and combined with Elmars 
posting about a better way to describe/name things in TSref (and 
probably in general).  If you do this and need help please let me know 
if I can aid in some way.

Tyler