TASK: Refine "Introduction" and "Using and setting TypoScript"

Documentation/Introduction/Index.rst

@@ -93,7 +93,6 @@ Always remember: In this manual the case of objects **is** important.
 Version numbers
 """""""""""""""
 
-For new features TSref includes a note in which TYPO3 version the
-feature was added. If such a note is missing, the feature is part of
-TYPO3 since version 7.6 at least.
-
+For new features TypoScript Reference includes a note in which TYPO3 version the
+feature was added. If such a note is missing, the feature is part of TYPO3 since
+version 7.6 at least.

Documentation/UsingSetting/Constants.rst

@@ -1,73 +1,104 @@
 .. include:: ../Includes.txt
 
 
+.. _typoscript-syntax-what-are-constants:
 .. _typoscript-syntax-constants:
 
 Constants
-^^^^^^^^^
+=========
 
+Constants are values defined in the "Constants" field of a template.  They
+follow the :ref:`syntax of ordinary TypoScript
+<t3coreapi:typoscript-syntax-syntax>` and are case sensitive! They are used to
+manage *in a single place* values, which are later used in *several places*.
 
-.. _typoscript-syntax-what-are-constants:
+Defining constants
+------------------
+
+Other than constants in programming languages, values of constants in TypoScript
+can be overwritten. Constants in TypoScript can more be seen as variables in
+programming languages.
 
-What are constants?
-"""""""""""""""""""
+**Reserved name**
 
-Constants are values defined in the "Constants" field of a template.
-They follow the :ref:`syntax of ordinary TypoScript <t3coreapi:typoscript-syntax-syntax>` and are
-case sensitive! They are used to manage *in a single place* values,
-which are later used in *several places*.
+The object or property "file" is always interpreted as data type ":ref:`resource
+<data-type-resource>`". That means it refers to a file, which has to be uploaded
+in the TYPO3 CMS installation.
 
-.. note::
+**Multi-line values: The ( ) signs**
 
-   **Reserved name**
+Constants do not support multiline values!
 
-   The object or property "file" is always interpreted as data type
-   ":ref:`resource <data-type-resource>`". That means it refers
-   to a file, which you have to upload in your TYPO3 CMS installation.
+Example
+"""""""
 
-.. important::
+Here :ts:`bgCol` is set to "red", :ts:`file.toplogo` is set to
+:file:`fileadmin/logo.gif` and :ts:`topimg.file.pic2` is set to
+:file:`fileadmin/logo2.gif`, assuming these files are indeed available at the
+expected location.
 
-   **Multi-line values: The ( ) signs**
+.. code-block:: typoscript
+   :emphasize-lines: 2,7
 
-   Constants do not support multiline values!
+   bgCol = red
+   file {
+       toplogo = fileadmin/logo.gif
+   }
+   topimg {
+       width = 200
+       file.pic2 = fileadmin/logo2.gif
+   }
 
+The objects in the highlighted lines contain the reserved word "file" and the
+properties are always of data type ":ref:`resource <data-type-resource>`".
 
-Example
-~~~~~~~
+.. _typoscript-syntax-using-constants:
 
-Here :code:`bgCol` is set to "red", :code:`file.toplogo` is set to
-"fileadmin/logo.gif" and :code:`topimg.file.pic2` is set to
-"fileadmin/logo2.gif", assuming these files are indeed available
-at the expected location.
+Using constants
+---------------
+
+When a TypoScript Template is parsed by TYPO3 CMS, constants are replaced, as
+one would perform any ordinary string replacement. Constants are used in the
+"Setup" field by placing them inside curly braces and prepending them with a
+:ts:`$` sign:
 
 .. code-block:: typoscript
-   :emphasize-lines: 3,4
 
-   bgCol = red
-   topimg.width = 200
-   topimg.file.pic2 = fileadmin/logo2.gif
-   file.toplogo = fileadmin/logo.gif
+   {$bgCol}
+   {$topimg.width}
+   {$topimg.file.pic2}
+   {$file.toplogo}
+
+Only constants, which are actually defined in the "Constants" field, are
+substituted.
 
-This could also be defined in other ways, e.g. like this:
+Constants in included templates are also substituted, as the whole
+template is one large chunk of text.
+
+A systematic naming scheme should be used for constants. As "paths" can be
+defined, it's also possible to structure constants and prefix them with a common
+path segment. This makes reading and fining of constants easier.
+
+Example
+"""""""
 
 .. code-block:: typoscript
-   :emphasize-lines: 2,7
 
-   bgCol = red
-   file {
-     toplogo = fileadmin/logo.gif
-   }
-   topimg {
-     width = 200
-     file.pic2 = fileadmin/logo2.gif
+   page = PAGE
+   page {
+       typeNum = 0
+       bodyTag = <body bgColor="{$bgCol}">
+       10 = IMAGE
+       10.file = {$file.toplogo}
    }
 
-(The objects in the highlighted lines contain the reserved word "file"
-and the properties are always of data type ":ref:`resource <data-type-resource>`".)
+For the above example to work, the constants from the last example have to be
+defined in the constants field.
 
-.. figure:: ../Images/TemplatesConstants.png
-   :alt: Overview of the defined constants
+.. figure:: ../Images/TemplatesSetup.png
+   :alt: Overview of the defined setup
 
+Constants in the setup code are substituted, marked in green. In the Object
+Browser, it's possible to show constants substituted and unsubstituted.
 
-The :code:`module` constant which is visible in the above screenshot
-comes from the TYPO3 CMS core itself.
+The "Display constants" function is not available if "Crop lines" is selected.

Documentation/UsingSetting/Debugging.rst

@@ -1,50 +1,69 @@
 .. include:: ../Includes.txt
 
+.. _typoscript-debugging:
 
-.. _typoscript-syntax-templates-debugging:
-.. _typoscript-syntax-debugging:
+Debugging / Analyzing
+=====================
 
-Debugging
-^^^^^^^^^
+Debugging TypoScript can be complicated as there are many influences like the
+active page and conditions. Also constants can be used which get substituted.
+The following sections provide information about how to debug TypoScript and how
+to find errors within TypoScript.
+
+Analyzing defined constants
+---------------------------
+
+The *TypoScript Object Browser* provides an tree view to all defined constants
+on the currently active page.
+
+.. figure:: ../Images/TemplatesConstants.png
+   :alt: Overview of the defined constants
+
+.. _typoscript-syntax-finding-errors:
 
-There are no tools that will tell you that your TypoScript code is
-100% correct. The TypoScript Object Browser will warn you about syntax errors
-though:
+Finding errors
+--------------
+
+There are no tools that will tell whether the given TypoScript code is 100%
+correct. The TypoScript Object Browser will warn about syntax errors though:
 
 .. figure:: ../Images/TemplatesSyntaxError.png
    :alt: The TypoScript Object Browser showing a syntax error
 
-
-Errors will also appear in the Template Analyzer, when viewing the
-content of a give template. It is also possible to see the full
-TypoScript code by clicking on the "View the complete TS listing"
-button at the bottom of the Template Analyzer:
+Errors will also appear in the Template Analyzer, when viewing the content of a
+give template. It is also possible to see the full TypoScript code by clicking
+on the "View the complete TS listing" button at the bottom of the Template
+Analyzer:
 
 .. figure:: ../Images/TemplatesViewFullListingButton.png
    :alt: The TypoScript Object Browser showing a syntax error
 
-
-The result is a long listing with all compiled line numbers, which
-makes it easy to find the error reported by the TypoScript Object Browser.
+The result is a long listing with all compiled line numbers, which makes it
+possible to find the error reported by the TypoScript Object Browser.
 
 .. figure:: ../Images/TemplatesFullListing.png
    :alt: The TypoScript Object Browser showing a syntax error
 
+In the frontend, the Admin Panel is another possibility to debug TypoScript; use
+its section called "TypoScript". It shows selected rendered (configuration)
+values, SQL queries, error messages and more.
 
-In the frontend, the Admin Panel is another possibility to debug
-TypoScript; use its section called "TypoScript"! It shows you selected
-rendered (configuration) values, SQL queries, error messages and more.
+.. _typoscript-syntax-debugging:
+.. _typoscript-syntax-templates-debugging:
+
+Debugging
+---------
 
 TypoScript itself offers a number of debug functions:
 
 - :ref:`stdWrap <stdwrap>` comes with the properties
   :ref:`debug <stdwrap-debug>`, :ref:`debugFunc <stdwrap-debugfunc>` and
-  :ref:`debugData <stdwrap-debugdata>` which help checking which values
-  are currently available and which configuration is being handled.
+  :ref:`debugData <stdwrap-debugdata>`
+  which help checking which values are currently available and which
+  configuration is being handled.
 
 - :ref:`GMENU <gmenu>`, :ref:`TMENU <tmenu>` and
   :ref:`IMGMENU <imgmenu>` come with the property
-  :ref:`debugItemConf <menu-common-properties>`. If set
-  to "1", it outputs the configuration arrays for each menu item.
-  Useful to debug :ref:`optionSplit <objects-optionsplit>`
-  things and such.
+  :ref:`debugItemConf <menu-common-properties>`.
+  If set to :ts:`1`, it outputs the configuration arrays for each menu item.
+  Useful to debug :ref:`optionSplit <objects-optionsplit>` things and such.

Documentation/UsingSetting/Entering.rst

@@ -4,7 +4,7 @@
 .. _typoscript-syntax-typoscript-templates-structure:
 
 Entering and structuring TypoScript templates
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+=============================================
 
 At its most basic, TypoScript is entered manually in both the
 "Constants" and "Setup" fields of template records (which are
@@ -18,7 +18,7 @@ stored in the database in table "sys_template").
 
 If the "t3editor" system extension is not installed or has been
 disabled via configuration options, the "Constants" and "Setup" fields
-will be just normal multi-line text fields.
+will be normal multi-line text fields.
 
 .. figure:: ../Images/TemplatesInputNoT3Editor.png
    :alt: The Constants and Setup fields without the t3editor enabled
@@ -27,32 +27,32 @@ will be just normal multi-line text fields.
 .. _typoscript-syntax-typoscript-templates-structure-includes:
 
 Inclusions
-""""""""""
+----------
 
 In both the "Constants" and "Setup" fields, the
 :ref:`INCLUDE_TYPOSCRIPT <t3coreapi:typoscript-syntax-includes>` syntax can be
-used to include TypoScript contained inside simple text files.
+used to include TypoScript contained inside files.
 
-Apart from this, it is also possible to include other TypoScript templates
+Apart from this, it is also possible to include other TypoScript template
 records (in the field called "Include Basis Template") and
 TypoScript provided by extensions (in the field called "Include static
-(from extension)").
+(from extensions)").
 
 .. figure:: ../Images/TemplatesIncludes.png
    :alt: Templates included from another template
 
 
-Obviously included templates can themselves include other templates.
+Included templates can themselves include other templates.
 
 .. _typoscript-syntax-typoscript-templates-structure-analyzer:
 
 Template Analyzer
-"""""""""""""""""
+-----------------
 
-With all those inclusions, it may happen that you lose the overview
-of your template structure. The "Template Analyzer" is there to help.
-It shows all the templates that apply on any given page, taking into
-account inclusions and inheritance along the page tree.
+With all those inclusions, it may happen that you lose the overview of the
+template structure. The "Template Analyzer" provides an overview of this
+structure. It shows all the templates that apply to the currently selected page,
+taking into account inclusions and inheritance along the page tree.
 
 .. figure:: ../Images/TemplatesAnalyzer.png
    :alt: All templates applying to a page, as used by the Introduction Package

Documentation/UsingSetting/Index.rst

@@ -4,7 +4,7 @@
 .. _typoscript-syntax-typoscript-templates:
 
 Using and setting TypoScript
-----------------------------
+============================
 
 TypoScript templates mainly consist of the Constants and the Setup field.
 Each template can include other (static) templates, which can again
@@ -21,6 +21,5 @@ The TypoScript template configuration can be viewed and edited in the
    Usage
    Entering
    Constants
-   UsingConstants
    TheConstantEditor
    Debugging