[TASK] Align with new TYPO3 documentation standards (#285)

* [TASK] Align with new TYPO3 documentation standards - align Settings.cfg, Index.rst, Includes.rst.txt - add genindex.rst - add Sitemap.rst - add .editorconfig - add README.rst - remove outdated _make/ - rename Includes.txt to Includes.rst.txt - remove outdated Targets.rst See TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument@c2bb63b for further details. * [DOCS] Remove oudated encoding note * [DOCS] Fix rendering warnings
TYPO3-Documentation · Mar 26, 2022 · b47efa8 · b47efa8
1 parent 22eeb4b
commit b47efa8
Show file tree

Hide file tree

Showing 45 changed files with 206 additions and 971 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,24 @@
+
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[{*.rst,*.rst.txt}]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 3
+max_line_length = 80
+
+# MD-Files
+[*.md]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+max_line_length = 80
diff --git a/Documentation/In-depth/Distributions/Index.rst b/Documentation/In-depth/Distributions/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _the-distributions:

diff --git a/Documentation/In-depth/Index.rst b/Documentation/In-depth/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _in-depth-installation:

diff --git a/Documentation/In-depth/SystemRequirements/Index.rst b/Documentation/In-depth/SystemRequirements/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _system-requirements:
@@ -24,16 +19,16 @@ TYPO3 requires a web server, PHP and a database system.
    * Certain PHP extensions are necessary, others recommended. See file :file:`INSTALL.md` as mentioned below.
    * You possibly want to adjust the memory limit; at least 128 MB is
      recommended:
-     
+
      php.ini:
-     
+
      .. code-block:: none
-     
+
         memory_limit = 128M
 
 * MySQL >= 5.5 <= 5.7 (or compatible such as Percona or MariaDB)
-* If you want TYPO3 to automatically carry out image processing – for example 
-  scaling or cropping – you will need GraphicsMagick or ImageMagick (version 6 or 
+* If you want TYPO3 to automatically carry out image processing – for example
+  scaling or cropping – you will need GraphicsMagick or ImageMagick (version 6 or
   newer) installed on the server.
 
 A detailed list of these requirements is enclosed in the file

diff --git a/Documentation/In-depth/TheInstallTool/Index.rst b/Documentation/In-depth/TheInstallTool/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _the-install-tool-in-depth:
@@ -41,7 +36,7 @@ of your database with the expected structure for the TYPO3 version you
 are using. The next step allows you to update the structure of your
 database accordingly.
 
-The **Clear all Cache** functionality can empty all caches: Frontend, 
+The **Clear all Cache** functionality can empty all caches: Frontend,
 Backend and language caches.
 
 The **Check for broken extensions** can be run to make sure that
@@ -63,7 +58,7 @@ Configuration presets
 
 This section provides default settings for different setups.
 
-The section "Character set conversion settings" allows you to select 
+The section "Character set conversion settings" allows you to select
 the program which should be used for character set conversions.
 
 The section "Debug settings" allows you to activate debugging. E.g. if
@@ -88,7 +83,7 @@ Here you can configure *all* installation options concerning your TYPO3
 installation. We suggest you go through the whole list and read the
 description of the settings carefully at least once, so you get an
 impression of what you can configure. Normally you *can*, but you *don't
-have to* change anything here during installation, as the previous steps 
+have to* change anything here during installation, as the previous steps
 took care of the most important settings.
 
 
@@ -97,7 +92,7 @@ took care of the most important settings.
 Upgrade wizard
 """"""""""""""
 
-You don't need the upgrade wizard while *installing* TYPO3. This function 
+You don't need the upgrade wizard while *installing* TYPO3. This function
 will be explained in a later chapter about upgrading TYPO3.
 
 
@@ -108,8 +103,8 @@ System environment
 
 The section contains a huge number of environment checks, which notify
 you of (potential) problems in your installation. It checks Apache
-settings and the status of important PHP modules and PHP settings. It 
-also contains full output of :code:`phpinfo()` and some constants used 
+settings and the status of important PHP modules and PHP settings. It
+also contains full output of :code:`phpinfo()` and some constants used
 by TYPO3.
 
 
@@ -119,7 +114,7 @@ Folder structure
 """"""""""""""""
 
 This section shows whether the files and folders in your installation have
-the correct permissions. This is important so that TYPO3 can function properly 
+the correct permissions. This is important so that TYPO3 can function properly
 and so that other users on the web server do not get access to (possibly confidential)
 data.
 
@@ -132,7 +127,7 @@ Test setup
 The section "Test setup" contains a test for the mail function and for
 image processing. Try each test to see if you have configured your image
 generation settings correctly. If you have problems, check the
-explanation of the test for a hint on how to solve them. Additionally, 
+explanation of the test for a hint on how to solve them. Additionally,
 have a look at the image processing settings in the section "All
 configuration".
 

diff --git a/Documentation/In-depth/ThePackageInDetail/Index.rst b/Documentation/In-depth/ThePackageInDetail/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _the-distributions-in-detail:

diff --git a/Documentation/In-depth/TranslatingTheBackend/Index.rst b/Documentation/In-depth/TranslatingTheBackend/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _translating-the-backend:

diff --git a/Documentation/In-depth/WhichPackageAndFormat/Index.rst b/Documentation/In-depth/WhichPackageAndFormat/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _which-package-and-which-file-format:
@@ -16,8 +11,8 @@ Which Package and which File Format?
 Which Package to use
 """"""""""""""""""""
 
-There is only one TYPO3 Package, called “TYPO3 Source”, with which you can install an empty instance of TYPO3. 
-Once the main installation process is complete, you will be asked whether you want to load additional “Distributions” 
+There is only one TYPO3 Package, called “TYPO3 Source”, with which you can install an empty instance of TYPO3.
+Once the main installation process is complete, you will be asked whether you want to load additional “Distributions”
 to “kick start” an out-of-the-box working environment.
 
 An overview of all available packages and versions (which also contains older supported releases) can be found at

diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt
@@ -0,0 +1,34 @@
+.. More information about this file:
+   https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt
+
+.. ----------
+.. text roles
+.. ----------
+
+.. role:: aspect(emphasis)
+.. role:: bash(code)
+.. role:: html(code)
+.. role:: js(code)
+.. role:: php(code)
+.. role:: rst(code)
+.. role:: sep(strong)
+.. role:: sql(code)
+
+.. role:: tsconfig(code)
+   :class: typoscript
+
+.. role:: typoscript(code)
+.. role:: xml(code)
+   :class: html
+
+.. role:: yaml(code)
+
+.. default-role:: code
+
+.. ---------
+.. highlight
+.. ---------
+
+.. By default, code blocks guesses syntax highlighting
+
+.. highlight:: guess
diff --git a/Documentation/Includes.txt b/Documentation/Includes.txt
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -1,89 +1,47 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: Includes.txt
-
+.. include:: /Includes.rst.txt
 
 .. _start:
 
 ==============================
 Installation and Upgrade Guide
 ==============================
 
-:Previous Key:
-      doc_guide_install
-
 :Version:
-      |release|
+   |release|
 
 :Language:
-      en
-
-:Description:
-      This document describes the file structure of TYPO3 and takes you
-      step by step through the installation. It does not focus on
-      specific operating systems, but contains some hints on general
-      TYPO3 installation issues with regards to Apache, PHP and MySQL.
-
-:Keywords:
-      forAdmins, forBeginners
-
-:Copyright:
-      2000-2015
+   en
 
 :Author:
-      Documentation Team
-
-:Email:
-      documentation@typo3.org
+   TYPO3 contributors
 
 :License:
-      Open Publication License available from `www.opencontent.org/openpub/
-      <https://www.opencontent.org/openpub/>`_
+   This document is published under the
+   `Open Publication License <https://www.opencontent.org/openpub/>`__.
 
 :Rendered:
-      |today|
-
-The content of this document is related to TYPO3,
-
-a GNU/GPL CMS/Framework available from `www.typo3.org
-<https://typo3.org/>`_
+   |today|
 
+----
 
-**Official documentation**
+This document explains how to install and upgrade TYPO3 and migrate from
+Legacy to Composer mode.
 
-This document is included as part of the official TYPO3 documentation.
-It has been approved by the TYPO3 Documentation Team following a peer
-review process. The reader should expect the information in this
-document to be accurate; please report discrepancies to the
-Documentation Team (documentation@typo3.org). Official documents are
-kept up-to-date to the best of the Documentation Team's abilities.
-
-
-**Guide**
-
-This document is a Guide. Guides are designed to familiarize a reader
-with a specific topic in order to provide a working knowledge of that
-particular process. Readers should peruse the guide from cover to
-cover in order to gain a practical overview of the process. Once
-completed, the Guide becomes a practical reference tool to which a reader
-can refer as needed. Guides offer advice on how best to achieve a
-given task.
-
-
-**Table of Contents**
+----
 
 .. toctree::
-   :maxdepth: 5
    :titlesonly:
-   :glob:
 
    Introduction/Index
    QuickInstall/Index
    In-depth/Index
    Upgrade/Index
-   UpgradeLTS/Index
    Troubleshooting/Index
-   Targets
+
+.. Meta Menu
+
+.. toctree::
+   :hidden:
+
+   Sitemap
+   genindex
diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../Includes.txt
+.. include:: /Includes.rst.txt
 
 
 .. _introduction:

diff --git a/Documentation/QuickInstall/GetAndUnpack/Index.rst b/Documentation/QuickInstall/GetAndUnpack/Index.rst
@@ -1,9 +1,4 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../../Includes.txt
+.. include:: /Includes.rst.txt
 .. highlight:: bash
 
 .. _get-and-unpack-the-typo3-package:
@@ -49,7 +44,7 @@ Installing on a Unix server
     Some servers installations do not allow a symlink on a php file, especially on shared hosting environments. Here you should copy the index.php like this:
 
         cp typo3_src/index.php index.php
-    
+
 
 #. Create an empty file :file:`FIRST_INSTALL` to enable the Install Tool
    to set up and configure the instance in the next step::