[DOC] Update documentation

Leuchtfeuer · May 10, 2020 · 4217fdf · 4217fdf
1 parent 37f28b6
commit 4217fdf
Show file tree

Hide file tree

Showing 31 changed files with 356 additions and 222 deletions.
diff --git a/...ntation/Miscellaneous/ChangeLog/2-0-0.rst → Documentation/About/ChangeLog/2-0-0.rst b/...ntation/Miscellaneous/ChangeLog/2-0-0.rst → Documentation/About/ChangeLog/2-0-0.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/2-0-1.rst → Documentation/About/ChangeLog/2-0-1.rst b/...ntation/Miscellaneous/ChangeLog/2-0-1.rst → Documentation/About/ChangeLog/2-0-1.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/2-0-2.rst → Documentation/About/ChangeLog/2-0-2.rst b/...ntation/Miscellaneous/ChangeLog/2-0-2.rst → Documentation/About/ChangeLog/2-0-2.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/2-0-3.rst → Documentation/About/ChangeLog/2-0-3.rst b/...ntation/Miscellaneous/ChangeLog/2-0-3.rst → Documentation/About/ChangeLog/2-0-3.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/2-0-4.rst → Documentation/About/ChangeLog/2-0-4.rst b/...ntation/Miscellaneous/ChangeLog/2-0-4.rst → Documentation/About/ChangeLog/2-0-4.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/2-0-5.rst → Documentation/About/ChangeLog/2-0-5.rst b/...ntation/Miscellaneous/ChangeLog/2-0-5.rst → Documentation/About/ChangeLog/2-0-5.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/2-0-6.rst → Documentation/About/ChangeLog/2-0-6.rst b/...ntation/Miscellaneous/ChangeLog/2-0-6.rst → Documentation/About/ChangeLog/2-0-6.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/3-0-0.rst → Documentation/About/ChangeLog/3-0-0.rst b/...ntation/Miscellaneous/ChangeLog/3-0-0.rst → Documentation/About/ChangeLog/3-0-0.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/3-0-1.rst → Documentation/About/ChangeLog/3-0-1.rst b/...ntation/Miscellaneous/ChangeLog/3-0-1.rst → Documentation/About/ChangeLog/3-0-1.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/3-0-2.rst → Documentation/About/ChangeLog/3-0-2.rst b/...ntation/Miscellaneous/ChangeLog/3-0-2.rst → Documentation/About/ChangeLog/3-0-2.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/3-0-3.rst → Documentation/About/ChangeLog/3-0-3.rst b/...ntation/Miscellaneous/ChangeLog/3-0-3.rst → Documentation/About/ChangeLog/3-0-3.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/4-0-0.rst → Documentation/About/ChangeLog/4-0-0.rst b/...ntation/Miscellaneous/ChangeLog/4-0-0.rst → Documentation/About/ChangeLog/4-0-0.rst
diff --git a/...ntation/Miscellaneous/ChangeLog/4-1-0.rst → Documentation/About/ChangeLog/4-1-0.rst b/...ntation/Miscellaneous/ChangeLog/4-1-0.rst → Documentation/About/ChangeLog/4-1-0.rst
diff --git a/Documentation/About/ChangeLog/4-1-1.rst b/Documentation/About/ChangeLog/4-1-1.rst
@@ -0,0 +1,28 @@
+.. include:: ../../Includes.txt
+
+===================
+Version 4.1.1 - TBA
+===================
+
+This release is a future release.
+
+Download
+========
+
+Download this version from the `TYPO3 extension repository <https://extensions.typo3.org/extension/secure_downloads/>`__ or from
+`GitHub <https://github.com/Leuchtfeuer/typo3-secure-downloads/releases/tag/v4.1.1>`__.
+
+All Changes
+===========
+
+This is a list of all changes in this release::
+
+   2020-05-10 [DOC] Update readme (Commit d113073 by Florian Wessels)
+   2020-05-10 [FOLLOW-UP][BUGFIX] Show overlay icon for files (Commit dc0e8a3 by Florian Wessels)
+   2020-05-10 [BUGFIX] Show overlay icon for files (Commit 866140c by Florian Wessels)
+   2020-05-09 [TASK] Stream file where possible (Commit 0307df6 by Florian Wessels)
+   2020-05-09 [TASK] Mark several properties and methods as deprecated (Commit 20a5053 by Florian Wessels)
+   2020-05-09 [BUGFIX] Perform group check only if file is covered by group check (Commit 88dab5c by Florian Wessels)
+   2020-05-09 [BUGFIX] Apply group check only to configured directories (Commit c908f06 by Florian Wessels)
+   2020-05-09 [TASK] Set version to 4.1.1-dev (Commit c5be46b by Florian Wessels)
+
diff --git a/...ntation/Miscellaneous/ChangeLog/Index.rst → Documentation/About/ChangeLog/Index.rst b/...ntation/Miscellaneous/ChangeLog/Index.rst → Documentation/About/ChangeLog/Index.rst
diff --git a/Documentation/About/Contributing/Index.rst b/Documentation/About/Contributing/Index.rst
@@ -0,0 +1,18 @@
+.. include:: ../../Includes.txt
+
+.. _about-contributing:
+
+============
+Contributing
+============
+
+You can contribute by making a **pull request** to the
+`master branch <https://github.com/Leuchtfeuer/typo3-secure-downloads/tree/master>`__ of the extension repository or by using
+the "❤️ Sponsor" button on `Github <https://github.com/Leuchtfeuer/typo3-secure-downloads>`__. Or just send us some **beers** 🍻...
+
+.. _about-contributing-documentation:
+
+Documentation
+=============
+
+You are welcome to help improve this guide. Just click on "Edit on GitHub" on the top right to submit your change request.
diff --git a/Documentation/About/Index.rst b/Documentation/About/Index.rst
@@ -0,0 +1,86 @@
+.. include:: ../Includes.txt
+
+.. _about:
+
+=====
+About
+=====
+
+In TYPO3, assets like PDFs, TGZs or JPGs etc. are normally just referenced by a URL e.g. to `fileadmin/...`. The file itself is
+delivered directly by the web server, and is therefore not part of the TYPO3 access control scheme – files remain unprotected,
+since URLs can be re-used, emailed, Search engine included or even guessed.
+
+The "Secure Downloads" extension (`EXT:secure_downloads`) changes this behavior: Files will now be accessed through a script that
+honors TYPO3 access rights. The converted URL's will then look like this:
+
+::
+
+   /seduredl/sdl-eyJ0eXAiOiJKV1QiLCJhbGciO[...]vcM5rWxIulg5tQ/protected_image.jpg
+
+This works regardless of where the files come from and is not limited to special plugins, etc.
+
+Since in most cases you will not want to protect everything (which means that everything undergoes rather performance-consuming
+access right checking), Secure Downloads is highly configurable. You may choose:
+
+* what directories to protect (e.g. you can include typo3temp or not)
+* what file types to protect (do you want to protect JPGs or not? etc.)
+
+As a complementary measure, you will of course need to configure your web server not to deliver these things directly (e.g. using
+.htaccess settings).
+
+.. _about-compatibility:
+
+Compatibility
+=============
+We are currently supporting following TYPO3 versions:<br><br>
+
+.. csv-table:: Version Matrix
+   :header: "Extension Version", "TYPO3 v10 Support", "TYPO3 v9 Support"
+   :align: center
+
+        "5.x", "🙋‍♂️", "🙅‍♀️"
+        "4.x", "🙋‍♂️", "🙋‍♂️"
+
+Version 5 is an upcoming release. Its package name has been changed to `leuchtfeuer/secure-downloads`.
+
+.. _about-compatibility-outdatedVersions:
+
+Outdated Versions
+-----------------
+For the following versions no more free bug fixes and new features will be provided by the authors:
+
+
+.. csv-table:: Version Matrix
+   :header: "Extension Version", "TYPO3 v9", "TYPO3 v8", "TYPO3 v7", "TYPO3 v6.2", "TYPO3 v4.5"
+   :align: center
+
+        "3.x", "🙋‍♂️", "🙋‍♂️", "🙅‍♀️", "🙅‍♀️", "🙅‍♀️"
+        "2.0.4 - 2.x", "🙅‍♀️", "🙋‍♂️", "🙋‍♂️", "🙅‍♀️", "🙅‍♀️"
+        "2.0.0 - 2.0.3", "🙅‍♀️", "🙅‍♀️", "🙋‍♂️", "🙋‍♂️", "🙅‍♀️"
+        "1.x", "🙅‍♀️", "🙅‍♀️", "🙅‍♀️", "🙋‍♂️", "🙋‍♂️"
+
+Version 1 was released as `EXT:naw_securedl <https://extensions.typo3.org/extension/naw_securedl>`__ or `typo3-ter/naw-securedl`.
+
+.. _about-links:
+
+Links
+=====
+
+:TYPO3 Extension Repository:
+   https://extensions.typo3.org/extension/secure_downloads/
+
+:Source Code and Git Repository:
+   https://github.com/Leuchtfeuer/typo3-secure-downloads/
+
+.. _about-knownLimitations:
+
+Known Limitations
+=================
+
+* Files inside Direct Mail newsletters do not work correctly with this extension 🥺
+
+.. toctree::
+    :maxdepth: 3
+    :hidden:
+
+    ChangeLog/Index
diff --git a/...orManual/ExtensionConfiguration/Index.rst → ...on/Admin/ExtensionConfiguration/Index.rst b/...orManual/ExtensionConfiguration/Index.rst → ...on/Admin/ExtensionConfiguration/Index.rst
@@ -1,41 +1,47 @@
 .. include:: ../../Includes.txt
 
-.. _configuration:
+.. _admin-extensionConfiguration:
 
 =======================
 Extension Configuration
 =======================
 
 All configuration is made in the "Extension Configuration" section of the "Settings" module beneath the "Admin Tools".
 
+.. figure:: ../../Images/ExtensionConfiguration.png
+   :alt: Extension Configuration
+   :class: with-shadow
+
+   The extension configuration can be found in the admin tools.
+
 Properties
 ==========
 
 .. container:: ts-properties
 
-	==================================== ==================================== ==================
-	Property                             Tab                                  Type
-	==================================== ==================================== ==================
-	securedDirs_                         Parsing                              string
-	securedFiletypes_                    Parsing                              string
-	linkPrefix_                          Link Generation                      string
-	tokenPrefix_                         Link Generation                      string
-	cachetimeadd_                        Link Generation                      positive integer
-	documentRootPath_                    Link Generation                      string
-	enableGroupCheck_                    Group Check                          boolean
-	groupCheckDirs_                      Group Check                          string
-	excludeGroups_                       Group Check                          string
-	strictGroupCheck_                    Group Check                          boolean
-	outputFunction_                      File Delivery                        options
-	protectedPath_                       File Delivery                        string
-	forcedownload_                       File Delivery                        boolean
-	forcedownloadtype_                   File Delivery                        string
-	log_                                 Module                               boolean
-	==================================== ==================================== ==================
+   ==================================== ==================================== ==================
+   Property                             Tab                                  Type
+   ==================================== ==================================== ==================
+   securedDirs_                         Parsing                              string
+   securedFiletypes_                    Parsing                              string
+   linkPrefix_                          Link Generation                      string
+   tokenPrefix_                         Link Generation                      string
+   cachetimeadd_                        Link Generation                      positive integer
+   documentRootPath_                    Link Generation                      string
+   enableGroupCheck_                    Group Check                          boolean
+   groupCheckDirs_                      Group Check                          string
+   excludeGroups_                       Group Check                          string
+   strictGroupCheck_                    Group Check                          boolean
+   outputFunction_                      File Delivery                        options
+   protectedPath_                       File Delivery                        string
+   forcedownload_                       File Delivery                        boolean
+   forcedownloadtype_                   File Delivery                        string
+   log_                                 Module                               boolean
+   ==================================== ==================================== ==================
 
 .. ### BEGIN~OF~TABLE ###
 
-.. _admin-configuration-securedDirs:
+.. _admin-extensionConfiguration-securedDirs:
 
 securedDirs
 -----------
@@ -50,10 +56,10 @@ securedDirs
    Description
          List of directories of your TYPO3 Server in that files should be secured, separated by pipe (|). Files in subdirectories
          will also be secured.
-         You can use :ref:`regex` for this option.
+         You can use :ref:`regular expressions <admin-regularExpressions>` for this option.
 
 
-.. _admin-configuration-securedFileTypes:
+.. _admin-extensionConfiguration-securedFileTypes:
 
 securedFiletypes
 ----------------
@@ -68,10 +74,10 @@ securedFiletypes
    Description
          List of file types (file extensions) that should be protected. Multiple file extension patterns can be separated by a
          pipe (|). You can use an asterisk (*) if you want to protect all files within configured directories.
-         You can use :ref:`regex` for this option.
+         You can use :ref:`regular expressions <admin-regularExpressions>` for this option.
 
 
-.. _admin-configuration-linkPrefix:
+.. _admin-extensionConfiguration-linkPrefix:
 
 linkPrefix
 ----------
@@ -87,7 +93,7 @@ linkPrefix
          Prefix for generated links (the `"securedl"` part in "https://example.com/securedl/sdl-[JWT]/image.png").
 
 
-.. _admin-configuration-tokenPrefix:
+.. _admin-extensionConfiguration-tokenPrefix:
 
 tokenPrefix
 -----------
@@ -103,7 +109,7 @@ tokenPrefix
          Prefix for generated token (the `"sdl-"` part in "https://example.com/securedl/sdl-[JWT]/image.png").
 
 
-.. _admin-configuration-cacheTimeAdd:
+.. _admin-extensionConfiguration-cacheTimeAdd:
 
 cachetimeadd
 ------------
@@ -120,7 +126,7 @@ cachetimeadd
          carries the link plus this value (in seconds).
 
 
-.. _admin-configuration-documentRootPath:
+.. _admin-extensionConfiguration-documentRootPath:
 
 documentRootPath
 ----------------
@@ -138,7 +144,7 @@ documentRootPath
          (e.g. "/proxy-typo3/").
 
 
-.. _admin-configuration-enableGroupCheck:
+.. _admin-extensionConfiguration-enableGroupCheck:
 
 enableGroupCheck
 ----------------
@@ -155,7 +161,7 @@ enableGroupCheck
          group in common. Enabling this makes the checks *less* restrictive!
 
 
-.. _admin-configuration-groupCheckDirs:
+.. _admin-extensionConfiguration-groupCheckDirs:
 
 groupCheckDirs
 --------------
@@ -170,9 +176,10 @@ groupCheckDirs
    Description
          A list of directories for the less restrictive group check, separated by a pipe (|). Leave empty if you want to enable
          the group check for all directories.
+         You can use :ref:`regular expressions <admin-regularExpressions>` for this option.
 
 
-.. _admin-configuration-excludeGroups:
+.. _admin-extensionConfiguration-excludeGroups:
 
 excludeGroups
 -------------
@@ -188,7 +195,7 @@ excludeGroups
          A comma separated list of groups that are excluded from the group check feature (if enabled).
 
 
-.. _admin-configuration-strictGroupCheck:
+.. _admin-extensionConfiguration-strictGroupCheck:
 
 strictGroupCheck
 ----------------
@@ -204,7 +211,7 @@ strictGroupCheck
          If enabled, files are only delivered if the user groups exactly match those of the secured link.
 
 
-.. _admin-configuration-outputFunction:
+.. _admin-extensionConfiguration-outputFunction:
 
 outputFunction
 --------------
@@ -217,15 +224,11 @@ outputFunction
    Default
          :code:`stream`
    Description
-         Due to possible restrictions in php and php settings, you probably need to adjust this value. By default "readfile" is
-         used to deliver the file. If this function is disabled in your php settings, you can try "fpassthru". If you have
-         problems with php `memory_limit` and big files to download, you need to set this to "stream", which delivers
-         the files in small portions.
-         For nginx web servers, there is also the possibility to deliver the file directly from the server by setting this
-         property to "x-accel-redirect".
+         Files are delivered as a file stream to the browser. For nginx web servers, there is the possibility to deliver the file
+         directly from the server by setting this property to "x-accel-redirect".
 
 
-.. _admin-configuration-protectedPath:
+.. _admin-extensionConfiguration-protectedPath:
 
 protectedPath
 -------------
@@ -249,7 +252,8 @@ protectedPath
             }
 
 
-.. _admin-configuration-forcedownload:
+
+.. _admin-extensionConfiguration-forcedownload:
 
 forcedownload
 -------------
@@ -266,7 +270,7 @@ forcedownload
          in the browser window.
 
 
-.. _admin-configuration-forcedownloadtype:
+.. _admin-extensionConfiguration-forcedownloadtype:
 
 forcedownloadtype
 -----------------
@@ -281,10 +285,10 @@ forcedownloadtype
    Description
          A list of file types that should not be opened inline in a browser, separated by a pipe. Only used if "forcedownload"
          (see: forcedownload_) is enabled. You can use an asterisk (*) if you want to force download for all file types.
-         You can use :ref:`regex` for this option.
+         You can use :ref:`regular expressions <admin-regularExpressions>` for this option.
 
 
-.. _admin-configuration-log:
+.. _admin-extensionConfiguration-log:
 
 log
 ---