[TYPO3] Complicated documentation? No reference guide? Do you know any good documentation?

[Cate & Peter]

Hey Dmitry

> It is very nteresting to know how TSRef looks from beginner's view. Can
you make
> some examples of what exactly is hard to understand?
> 
> I think one thing, which is hard for us (developers) to catch, is what
others find
> unclear. Examples would really help us improve.
> 
Mmmm ... there is so much :) Um ... well, here is a situation from last
night.

Trying to work out how typolinks work, having not used them until now.

The example Christopher posted for me didn't work when I pasted it into my
ts template, so I thought that I must need to add some information that he
assumed I would know ... the snippet had the HTML content object. So, off to
TSRef I go, to have a look at HTML ... when I get there I find only one
property "value" ... with the datatype stdWrap, and the description "raw
HTML code".

The examples under are: 

Example:
10 = HTML
10.value = This is a text in uppercase
10.value.case = upper

Example:
10 = HTML
10.value.field = bodytext
10.value.br = 1

Well, nothing in either of those examples looks remotely what I would
imagine "raw HTML code" to look like ... so I still haven't figured out what
Kasper means by that. Nevertheless, off to stdWrap I go, to see what I can
include here ...

p.10: ""... / stdWrap":
When a datatype is set to "type / stdWrap" it means that the value is parsed
through the stdWrap function with the properties
of the value as parameters."

!! :S

My brain reads:

"The value is "parsed" (oh bugger, coding jargon ... um um ... Cate's
translation= "processed") through the stdWrap function (the what??? Even if
I find it, I won't understand it ...what will that do??) with the properties
of the value as parameters (parameters ... parameters ...more jargon ...
Cate's translation= limiters)."

Ok ... sort of get that ... now to work out what values I can use...

Go to page 22 ... and the first thing is an IMAGE of the tslib/content.php/,
function stdWrap() (oh, how funny ... literally as I write this I have just
realised that this is what the previous passage is referring to! Lol!).

Anyhow, it is an image ... so I can't even cut and paste into another
document to make my own comments, put spacing in between the rows to make it
easier to work out or anything ... the font is small, so I struggle, zooming
in to read that, then zooming out to read the information around it ...

So, still reading it all with the thought of the HTML object at the back of
my mind, I have a huge list of properties, data types, descriptions, and the
occasional default ... but where is the "value" I am looking for?? I mean, I
sort of work out that is it the stuff in "properties", but that is only from
looking at all the examples ... it is NOT intuitive.

So, going back to the examples above ...

Example:
10 = HTML
10.value = This is a text in uppercase
10.value.case = upper

How do I know that "upper" can be used with case? (Yes, I know it is not a
hugely difficult thing, but as an example...) TSRef gives me a description
of

TSRef:
"Converts case
Uses "renderCharset" for the operation."

Ok ... but what are the parameters I can set here? Upper? Lower? Block?
Camel?

Example:
10 = HTML
10.value.field = bodytext
10.value.br = 1

Ok ...

TSRef:
 br: Boolean: PHP function nl2br(); Converts linebreaks to <br />-tags

Boolean I get (although I still consciously have to think, 1=on) ... but "
PHP function nl2br();"?? What the?? Likewise for the two properties
following ...

TSRef:
brTag string All ASCII-codes of "10" (CR) is substituted with value
encapsLines ->encapsLines Lets you split the content by chr(10) and proces
each line independently.
Used to format content made with the RTE.

I have NO idea what this means... Anyhow, back to my problem ... the
typolinks ...so I cover it over and keep reading ...

TSRef:
"keywords- Boolean- splits the content by characters "," ";" and chr(10)
(return), trims each value and returns a comma-separated list of the
values."
"innerWrap wrap /stdWrap"
"innerWrap2 wrap /stdWrap"

:S so how would you use keywords ... 10.value.keywords = 1 ... then what?
And what is chr(10)???

And these recursive wraps, just make my brain wrap around a telegraph pole
... the wrap is a property of stdWrap, and has as its own properties stdWrap
.... :S. I have sort of figured out how to use them but I have to REALLY
think about it.

Going further...

TSRef:
preCObject - cObject- cObject prepended the content
postCObject- cObject- cObject appended the content

? why? What is it used for? Why would I want to add a cObject in this way to
the conten ... and what content? Where is it sourced from? I have no
idea....

So, I find typolink: ->typolink - Wraps the content with a link-tag. Great
... looks simple enough ... except I have to go to typolink.