Overhaul Site Package tutorial

Documentation/ExtensionConfiguration/Index.rst

@@ -15,35 +15,40 @@ advise) the extension needs to contain its own :file:`composer.json`.
 
 .. include:: /CodeSnippets/ExtensionConfiguration/ComposerJson.rst.txt
 
-For historic reasons TYPO3 extension names have to be written in lower case
-separated by underscores. We suggest to use the extension key for the directory
-of the extension as well to minimize confusion. So the extension in the path
-:file:`site_package` has to have the
-same "extension-key" to be defined in the "extra" section of the composer.json.
+For historic reasons TYPO3 extension names are written in
+lower case words and separated by underscores if there are more than one. This
+is known as the extension key. The directory containing the extension should have
+the same name as the extension key. Composer package names are written in
+lower-case words but are separated with dashes if there is more than one word.
+
+At the top of the :file:`composer.json` file we see the Composer package name
+`t3docs/site-package` (with a dash) and at the bottom we see the TYPO3
+extension key in the extras section - :file:`site_package` (with an underscore).
+The Composer "name" consists of a vendor name followed by a forward slash and the
+lowercase extension name with dashes.
+
 
-The Composer name defined as "name" however has to consist of a vendor name
-followed by a forward slash and the lowercase extension name with minus scores.
 
 .. hint::
-   If composer does not find your site-package extension check if you are
-   using the correct separation chars in the correct places.
+   Make sure you don't mix up your underscores and dashes otherwise Composer
+   will not find your site-package extension.
 
 .. _extension-manager-configuration:
 
 Extension declaration file :file:`ext_emconf.php`
 =================================================
 
-Since version 11 this file is only mandatory if you are not using Composer.
+From version 11 this file is only mandatory if you are not using Composer.
 If you are using Composer you can omit this file as it is ignored by TYPO3
 anyway.
 
-If you are using a TYPO3 version below 11 or need to refrain from using
+If you are using a TYPO3 version below 11 or can't use
 Composer for some reason create a file called :file:`ext_emconf.php` in
 the root level of the extension. The content should look as follows:
 
 .. include:: /CodeSnippets/ExtensionConfiguration/ExtEmconf.rst.txt
 
-The values can and should be customized of course. A more meaningful and longer
+The values can and should be customized. A more meaningful and longer
 description is recommended.
 
 A detailed description of all configuration options can be found in
@@ -111,5 +116,5 @@ it stands now.
     site_package/Resources/Public/JavaScript
     site_package/Resources/Public/JavaScript/website.js
 
-At this point we can install the sitepackage extension in a TYPO3 instance,
+At this point we can install the sitepackage extension in an TYPO3 instance,
 which we will do in the next step.

Documentation/ExtensionInstallation/Index.rst

@@ -8,14 +8,14 @@ Extension installation
 
 This tutorial assumes that your TYPO3 instance is a brand new installation,
 without any themes, templates, pages or content. See the :doc:`TYPO3
-Installation Guide <t3install:Index>` for a detailed explanation how to set up
+Installation Guide <t3install:Index>` for a detailed explanation on how to set up
 a TYPO3 instance from scratch.
 
-We highly recommend to use :ref:`the Composer -based installation process
+We highly recommend using :ref:`the Composer -based installation process
 <t3start:install-extension-with-composer>`. During development you should work locally
-on your machine for example by running TYPO3 on ddev.
+on your machine, e.g. by running TYPO3 on ddev.
 
-If you need to follow the legacy way of installation, see :ref:`Site package
+If you need to follow the legacy installation method, see :ref:`Site package
 installation without Composer <extension-installation_without_composer>`.
 
 
@@ -24,16 +24,15 @@ installation without Composer <extension-installation_without_composer>`.
 Extension installation in Composer mode
 =======================================
 
-Starting with TYPO3 11.4 if composer is used, all extensions, including the
-site package extension must be installed via Composer.
+From TYPO3 v11.4 if Composer is used, all extensions, including our
+site package extension, must be installed via Composer.
 
-As a site package is usually developed together with the site-specific files it
-is usually desirable to keep them together in a version control system like
-Git.
+As a site package is created with site-specific files it is usually best to keep
+the files together in a version control system such as Git.
 
-Therefore create a directory for all locally version-controlled extension at
-root-level of your Composer -based installation. The name is arbitrary, we use
-:file:`packages` here.
+Create a directory for local version-controlled extensions at the
+root-level of your Composer-based installation. The name is arbitrary, we use
+:file:`packages/` here.
 
 Then edit your :file:`composer.json` in the root of your installation directory
 to add the path as a local repository.
@@ -44,7 +43,7 @@ Add the following lines:
    :caption: page_root/composer.json
 
    {
-      "name": "myvendor/my-project",
+      "name": "myvendor/site-package",
       "repositories": [
          {
             "type": "path",
@@ -58,29 +57,29 @@ Add the following lines:
       "..." : "..."
    }
 
-Move your the extension folder :file:`site_package` directly into the folder
-:file:`packages`. Then *require* the extension via Composer  using the
-`name` defined in the site package extensions :file:`composer.json` now located
-at :file:`packages/site_package/`. For example if you defined the name as
+Move your extension folder :file:`site_package/` into the :file:`packages/`
+folder. Then *require* the extension via Composer using the
+package name defined in the site package extension's :file:`composer.json` now located
+at :file:`packages/site_package/`
 
 .. code-block:: json
    :caption: packages/site_package/composer.json
 
    {
-      "name": "myvendor/site-package-myproject"
+      "name": "myvendor/site-package"
    }
 
 require it by:
 
 .. code-block:: bash
    :caption: Execute in directory page_root
 
-    composer require myvendor/site-package-myproject:@dev
+    composer require myvendor/site-package:@dev
 
 .. hint::
 
-   Starting with TYPO3 11.4 all extensions required via Composer are
-   automatically considered active. In previous versions it is still necessary
+   From TYPO3 v11.4 all extensions required via Composer are
+   automatically active. In previous versions it was still necessary
    to activate the extension after the Composer-based installation via the
    :guilabel:`Extension Manager`.
 

Documentation/Index.rst

@@ -24,11 +24,11 @@ TYPO3 Sitepackage Tutorial
 
 ----
 
-This tutorial describes the steps required to create a fully functional TYPO3
-website from a design template (HTML, CSS, JavaScript, etc.) - with the support
-of a *sitepackage extension*.
+This tutorial describes how to create a fully functional TYPO3 website from
+design templates (HTML, CSS, JavaScript, etc.) by using a
+*sitepackage extension*.
 
-The final code of the sitepackage extension can be retrieved from the
+A working copy of the sitepackage extension can be retrieved from the
 `TYPO3CMS-Tutorial-SitePackage-Code`_ repository.
 
 .. _TYPO3CMS-Tutorial-SitePackage-Code: https://github.com/TYPO3-Documentation/TYPO3CMS-Tutorial-SitePackage-Code/tree/main

Documentation/Introduction/Index.rst

@@ -13,84 +13,80 @@ Introduction
 Sitepackage Benefits
 ====================
 
-The development of a website can be approached in several ways. Standard
-websites usually consist of HTML documents, which contain texts and have image
-files, video files, styles, etc. referenced. The enterprise content management
-system TYPO3 features a clean separation between design, content and
-functionality of a website and allows developers/integrators to add simple as
-well as sophisticated functions to the system easily.
+Developing a website can be approached in different ways. Standard
+websites usually consist of HTML documents which contain text and reference
+image files, video files, styles, etc. Because it is an enterprise content
+management system, TYPO3 features a clean separation between design, content and
+functionality and allows developers/integrators to add simple or
+sophisticated functionality easily.
 
 Encapsulation
 -------------
-Using extensions are a powerful way to get the most out of TYPO3. Extensions
-can be installed, deinstalled, replaced, etc. and extend the core system with
-functions and features not shipped with the core system. An extension typically
-consists of PHP files, but can also (or only) contain design templates (HTML,
-CSS, JavaScript files, etc.) and global configuration. The visual appearance of
-a website does not necessarily require any PHP code. However, the sitepackage
-extension described in this tutorial contains exactly two PHP files (plus a
-handful of HTML/CSS and configuration files) to work as an *extension* in
+Using extensions is a powerful way to get the most out of TYPO3. Extensions
+can be installed, uninstalled and replaced. They can extend the core TYPO3
+system with further functions and features. An extension typically
+consists of PHP files, and can also contain design templates (HTML,
+CSS, JavaScript files, etc.) and global configuration settings. The visual
+appearance of a website does not necessarily require any PHP code. However, the
+sitepackage extension described in this tutorial contains exactly two PHP files
+(plus a handful of HTML/CSS and configuration files) and is an *extension* to
 TYPO3. The PHP code can be copied from this tutorial if the reader does not
-have any programming knowledge as such.
+have any programming knowledge.
 
 Version Control
 ---------------
-By building the sitepackage as an extension, all relevant files are stored at
-a central point and changes can easily be tracked in a version control system
-such as Git. Despite the fact that TYPO3 supports several methods of
-implementing websites, this approach is a very flexible and professional way.
-At the same time the process is not overly complicated.
+In building the sitepackage as an extension, all relevant files are stored in
+one place and changes can easily be tracked in a version control system
+such as Git. The site package approach is not the only way of creating TYPO3
+websites but it is flexible and professional and not overly complicated.
 
 Dependency Management
 ---------------------
-Another important benefit of a TYPO3 extension is the fact that dependencies to
-other extensions and/or the TYPO3 version can be defined. This makes
-deployments easier and more fail-safe. This feature is called "Dependency
-Management". Most TYPO3 sites require a number of extensions. This could be
-"News" or "Powermail" for example. By building a sitepackage
-extension, which may contain global configuration for these add-ons, the
-dependencies can be defined. When the sitepackage extension is installed in an
-empty TYPO3 instance, all dependent extensions are downloaded from the `TYPO3
-Extension Repository <https://extensions.typo3.org>`__ and installed
-automatically.
+TYPO3 extensions allow dependencies to other extensions and/or the TYPO3 version
+to be defined. This is called "Dependency Management" and makes deployment easy
+and fail-safe. Most TYPO3 sites are dependent on a number of extensions. Some
+examples are "News" or "Powermail". A sitepackage extension which contains
+global configuration settings for these extensions will define the dependencies
+for you. When the sitepackage extension is installed in an
+empty TYPO3 instance, all dependent extensions are automatically downloaded from
+the `TYPO3 Extension Repository <https://extensions.typo3.org>`__ and installed.
 
 Clean Separation from the Userspace
 -----------------------------------
-Without using an extension, template files are often stored in the
-:file:`fileadmin/` directory of a TYPO3 instance. As a matter of fact, files in
-this directory are indexed by TYPO3's File Abstraction Layer (FAL). This
-results in irrelevant and avoidable records in the database. From a logical
-perspective, the :file:`fileadmin/` area is the "userspace". This area is meant to
-belong to editors. Even if access permissions restrict editors from accessing
-or manipulating files in :file:`fileadmin/`, site configuration components should
-not be stored in the userspace by all means.
+In a TYPO3 installation that doesn't use extensions, template files are often
+stored in the :file:`fileadmin/` directory. Files in
+this directory are indexed by TYPO3's :ref:`File Abstraction Layer (FAL) <t3coreapi:fal>` resulting in
+possibly irrelevant records in the database. To avoid this the :file:`fileadmin/`
+area should be seen as a "userspace" which is only available for editors to
+use. Even if access permissions restrict editors from accessing or manipulating
+files in :file:`fileadmin/`, site configuration components should
+still not be stored in the userspace.
 
 Security
 --------
-Files in :file:`fileadmin/` are typically meant to be publicly accessible per
+Files in :file:`fileadmin/` are typically meant to be publicly accessible by
 convention. To avoid disclosing sensitive system information (see the
 :ref:`TYPO3 Security Guide <t3coreapi:security>` for further details),
 configuration files should not be stored in :file:`fileadmin/`.
 
 Deployment
 ----------
-Modern versions of TYPO3 CMS follow the *convention over configuration*
-paradigm. As a consequence, if files and directories of the sitepackage
-extension use a specific naming convention, they are loaded automatically as
-soon as the extension is installed/activated in the system. This leads to
-another important advantage of the sitepackage extension. The extension can be
-deployed easily by using the Extension Manager and/or the PHP composer method.
-This also enables system administrators to automate the deployment for example.
+TYPO3 follows the *convention over configuration*
+paradigm. If files and directories in the sitepackage
+extension use the naming convention, they are loaded automatically as
+soon as the extension is installed/activated. This means the
+extension can be easily deployed using the Extension Manager and/or PHP composer.
+Deployment can be automated by system administrators.
 
 Distributable
 -------------
-In virtue of the motto "TYPO3 inspires people to share!", the sitepackage
-extension can also be shared with the community via the official `TYPO3
+By virtue of the motto "TYPO3 inspires people to share!", the sitepackage
+extension can be shared with the community via the official `TYPO3
 Extension Repository <https://extensions.typo3.org>`__ and/or in a publicly
 accessible version control system such as `GitHub <https://github.com>`__.
 
-Last, but not least, configuration implemented in the sitepackage can be
-overwritten in the TypoScript setup and constants as required.
+Last, but not least, configuration settings in the sitepackage can
+be overwritten using TypoScript setup and constants.
 
 
 .. _prerequisites:
@@ -105,13 +101,11 @@ following areas:
 * SSH/FTP (copy files and directories to and from the server)
 
 It is also recommended that the reader has worked with TYPO3 before, knows what
-the *frontend*, *backend* and *Extension Manager* is and how to access the
+the *frontend*, *backend* and *Extension Manager* are and how to access the
 *Install Tool*. Missing knowledge can be acquired by working through the TYPO3
 documentation, for example the :doc:`Getting Started Tutorial <t3start:Index>`.
 
-Due to the fact that the sitepackage discussed in the next chapters implements
-a new, fresh, clean website skin from scratch, an empty TYPO3 instance is a
-prerequisite, too. This means, we assume we have a TYPO3 site without any
-pages, any design templates, any configuration, etc. However, a valid TYPO3
-backend user with administrator privileges is required and SSH/FTP access to
-the server is recommended.
+The sitepackage in this tutorial will build a new, clean website from scratch,
+so it is assumed you have an empty TYPO3 instance with no pages, design
+templates, configuration, etc. You will need a valid TYPO3 backend user login with
+administrator privileges and SSH/FTP access to the server is recommended.

Documentation/MinimalExample/Index.rst

@@ -7,14 +7,14 @@
 Minimal example
 ===============
 
-Here, we intend to create a site package that outputs a single web page with the
-minimal effort. This site package can serve to test system output or as an
-example of the fewest required steps to create a working site package.
+We want to create a site package that outputs a single web page with
+minimal effort. This site package can be used to simply test system output or as
+an example of the fewest possible steps to create a working site package.
 
-For this example, in the CMS backend, create a standard page named
+To start, in the TYPO3 backend, create a standard page named
 :guilabel:`Minimal example` just under (inside) the page tree TYPO3 logo
-container. On this standard page, create a new TypoScript template record.
-Give the new TypoScript template a title, and make it a root level template,
+container. Create a new TypoScript template record on this page.
+Give the TypoScript template a title, and make it a root level template,
 but do not include any static templates.
 
 The TypoScript-only version
@@ -32,15 +32,16 @@ In the TypoScript template Setup field, add the following three lines:
 View the web page.
 
 This TypoScript-only design has the least instructions required to output a
-web page from the CMS. This TypoScript template is self contained,
-there are no other files or database records needed. Changing this content
-requires the appropriate access needed to make changes to TypoScript templates. 
+web page from TYPO3. This TypoScript template is self contained and
+no other files or database records needed. Changing this content
+only requires the appropriate access needed to make changes to TypoScript
+templates.
 
 The TYPO3 Fluid version
 =======================
 
 Empty the :guilabel:`Minimal design` page TypoScript template Setup field,
-then add the following lines in the field:
+then add the following lines:
 
 .. code-block:: typoscript
    :caption: TypoScript Setup
@@ -63,16 +64,17 @@ for this to work
 
 Now view the web page.
 
-This approach puts the page content into a HTML file, allowing for separate
-access controls and it also allows for an editing workflow that does not need as much TypoScript.
-The CMS renderer still requires a TypoScript template on the :guilabel:`Minimal design` page to know what file to process for the page content.
+Here we are putting the page content into a separate HTML file, allowing for
+separate access control and for an editing workflow that does not need much
+TypoScript. The TYPO3 renderer still requires a TypoScript template on the
+:guilabel:`Minimal design` page to know which file to process.
 
 Resulting web page
 ==================
 
 Here is the resulting web page HTML source for both the TypoScript-only and
-the Fluid based implementations. Notice how the CMS added default markup
-surrounding the single line of content:
+the Fluid based implementations. Notice how TYPO3 has added default markup
+around the single line of content:
 
 .. code-block:: html
    :caption: Example frontend output