Update: Rethinking this: "TypoScript in 45 minutes" has already some points I have suggested for introduction. We should review this and see if it can be integrated into the reference, or this can be linked to more prominently, or how the structure might be improved. The problem right now (in general) is that we often don't have a landing page or introduction section, it is difficult to find, etc.
Motivation
Currently, the page "Introduction" (in the TypoScript Reference) contains "About this document", "Credits", "Feedback and Fixing", Information about "Case Sensitivity" etc..
None of this is an introduction to the topic "TypoScript Templates", it is meta-information about what the reference is about, how to edit it and the "case sensitive" part is actually out of scope because that rather belongs in "TypoScript syntax"
You may argue that this is a Reference, a manual for at least intermediate audience.
But even then, this introduction could exist somewhere else. At the moment, it does not exist at all.
- What we do have is an introduction to Templating in Getting Started, but that rather focused on Fluid, not TypoScript.
- What we do have is "TypoScript in 45 minutes" but that is not even linked to in the TypoScript reference. Not on the start page, not in the "Introduction".
I think an introduction to this topic must not be long, it could even exist on the start page, but it should exist. It could be a summary of "TypoScript in 45 minutes" and refer to it.
Contents of Introduction
A "real" introduction could contain:
- What are TypoScript Templates?
- What can you do with it?
- historical relevance: e.g. explain what used to be written in TypoScript and how this has changed, e.g. now using FLUIDTEMPLATE is possible with Fluid templates
- explain TSFE and how TYPO3 renders frontend
- TypoScript vs. TSconfig
- TypoScript vs. Fluid
- Constants & Setup
- disambiguation: TypoScript is used for the TypoScript syntax language, TypoScript templating, constants etc. I often use the terms "TypoScript syntax language" or "TypoScript templates" to avoid using the term TypoScript for everything which makes it vague and confusing. E.g. consider the sentence: "TypoScript and TSconfig use TypoScript".
Maybe not literally included in text but things to keep in mind:
- Imagine someone new to TYPO3 who does not know what TypoScript is or only has a vague idea
- What are the most common usecase where you will need the TypoScript reference?
Should not contain
- TypoScript syntax is already covered in TYPO3 Explained. The same information should not be repeated, but referred to. A short summary should be ok.
- How to set TypoScript is already covered: file:///home/peters/prog.local/github-pull-requests/typo3-documentation/TYPO3CMS-Reference-Typoscript-sypets/Documentation-GENERATED-temp/Result/project/0.0.0/UsingSetting/Index.html
Sample text
Using existing text, I started sample text but this is unfinished!
The TypoScript Template Reference (TSref) is a reference for the core content objects, properties and functions available for template building in TYPO3 using the TypoScript template engine.