lots or minor corrections and updates

doc/README.Install.md

@@ -5,8 +5,8 @@ REQUIREMENTS
 ============
 
 SeedDMS is a web-based application written in PHP. It uses MySQL,
-sqlite3 or postgresql to manage the documents that were uploaded into
+SQLite3 or PostgreSQL to manage the documents that were uploaded into
-the application. Be aware that postgresql is not very well tested.
+the application. Be aware that PostgreSQL is not very well tested.
 
 Make sure you have PHP >= 7.2 and MySQL 5 or higher installed. SeedDMS
 will work with PHP running in CGI-mode as well as running as a module under
@@ -15,11 +15,11 @@ apache.
 Here is a detailed list of requirements:
 
 1. A web server with at least php 7.2
-2. A mysql database, unless you use sqlite
+2. A mysql database, unless you use SQLite
 3. The php installation must have support for `pdo_mysql`, `pdo_pgsql` or `pdo_sqlite`,
    `php_gd2`, `php_mbstring`, `php_xml`
 4. Depending on the configuration the extensions `php_ldap`, `php_mycrypt`,
-   `php_gmp`, `php_libsodium`must be installed
+   `php_gmp`, `php_libsodium` must be installed
 5. Various command line programms to convert files into text for indexing
    pdftotext, catdoc, xls2csv or scconvert, cat, id3 (optional, only needed
    for fulltext search)
@@ -30,7 +30,8 @@ Here is a detailed list of requirements:
 It is highly recommended to use the quickstart archive
 (seeddms-quickstart-x.y.z.tar.gz) because it includes all software packages
 (excluding those listing above in item 1. to 6.) for running SeedDMS. Hence,
-you still need a working web server with PHP and in addition a mysql or postgres database unless you intend to use sqlite.
+you still need a working web server with PHP and in addition a mysql or
+PostgreSQL database unless you intend to use SQLite.
 
 QUICKSTART
 ===========
@@ -39,8 +40,8 @@ The fastes way to get SeedDMS running is by unpacking the archive
 `seeddms-quickstart-x.y.z.tar.gz` on your webserver.
 Let's assume you use seeddms-quickstart-5.1.x.tar.gz.
 It will create a new directory `seeddms51x` containing everything you
-need to run SeedDMS with sqlite3. Even if you intend to use mysql in the
+need to run SeedDMS with SQLite3. Even if you intend to use mysql in the
-long run it is advisable to first set up SeedDMS with sqlite3 and than
+long run it is advisable to first set up SeedDMS with SQLite3 and than
 just switch the database.
 
 Setting up the web server
@@ -86,8 +87,8 @@ set an alias like described above).
 It will first ask to unlock the installer by creating a file
 `ENABLE_INSTALL_TOOL` in the diretory `seeddms51x/conf/`. Change all paths by
 replacing `/home/www-data` with your base directory where you put seeddms51x.
-Set httpRoot to '/' (if  the document root points to`seeddms51x/www`) or
+Set httpRoot to `/` (if  the document root points to `seeddms51x/www`) or
-'/seeddms51x' (if you have set an alias `seeddms51x` like described above).
+`/seeddms51x` (if you have set an alias `seeddms51x` like described above).
 
 Once your configuration is done,
 save it, remove the file `ENABLE_INSTALL_TOOL` and point your browser to
@@ -97,10 +98,10 @@ SECURITY CONSIDERATIONS
 =======================
 
 You should always access your SeedDMS installation through
-a secured https connection, unless you know precisly what are you doing.
+a secured https connection, unless you precisly know what you are doing.
 SeedDMS ships an .htaccess file which already has some common security
 http headers set. In order for them to apply you need to activate the
-headers module. On Debian this can be done with
+headers module. On Debian/GNU Linux this can be done with
 
 ```
 a2enmod headers
@@ -110,19 +111,13 @@ Protect directories with data or configuration
 ---------------------------------------------
 
 A crucial point when setting up SeedDMS is the propper placement of the
-data directory. Do not place it below your document root as
+data directory. Do not place it below your document root of your web server!
-configured in your web server! If you do so, there is a good change that
+If you do so, there is a potential way that
 attackers can easily access your documents with a regular web browser.
-If you cannot place the data directory outside of document root, than either
+If you cannot place the data directory outside of document root, then either
-restrict access to it with an appropriate .htaccess file or/and change
+restrict access to it with an appropriate `.htaccess` file like the following.
-the `contentOffsetDir` in `settings.xml` to something random, but ensure it
+The SeedDMS quickstart archive already includes this `.htaccess` file.
-is still a valid directory name. If you change contentOffsetDir then
-do not forget to move `data/1048576` to `data/<your random name>`.
-Also turn off directory listings in your apache configuration for the
-`data` directory.
 
-Example for .htaccess file in data directory
-----------------------------------------------
 ```
 # line below if for Apache 2.4
 <ifModule mod_authz_core.c>
@@ -141,6 +136,14 @@ IndexIgnore *
 </ifModule>
 ```
 
+Alternatively or in addition you can change
+the `contentOffsetDir` in `settings.xml` to something random, but ensure it
+is still a valid directory name. If you change contentOffsetDir, then
+do not forget to move `data/1048576` to `data/<your random name>`.
+Also turn off directory listings in your apache configuration for the
+`data` directory.
+
+
 Securing the configuration file
 ---------------------------------
 
@@ -152,27 +155,40 @@ administrator. For now you need to make the configuration file `settings.xml`
 unwritable for the web server. In that case the SeedDMS administrator can
 still see the configuration but will not be able to change it.
 
+Since version 5.1.23 and 6.0.16 of SeedDMS there is some preliminary way to
+hide parts of the configuration which makes them unchangeable for the
+SeedDMS administrator.
+
 Setting a new encryption key
 ------------------------------
+
 Though this is not related to setting up the web server environment, it is
 important to recreated the encryption key in SeedDMS once SeedDMS is running.
 Just open the settings in the admin tools and empty the currently set
 encryption key on the tab 'System'. Save the settings and check the key again.
-It should be new one. Save the settings again
+It should be a new one. Save the settings again. The encryption key is
+mainly used for creating tokens in HTML forms to prevent CSRF attacks.
 
-UPGRATING FROM A PREVIOUS VERSION OR SEEDDMS
+UPGRADING FROM A PREVIOUS VERSION OF SEEDDMS
 =============================================
 
 As SeedDMS is a smooth continuation of LetoDMS there is no difference
-in updating from LetoDMS or SeedDMS
+in updating from LetoDMS or SeedDMS.
 
-You have basically two choices to update SeedDMS
+You have basically two choices to update SeedDMS:
 
 - you install a fresh version of SeedDMS and copy over your data and configuration
 - you replace the software in your current installation with a new version
 
 The first option is less interuptive but requires to be able to set up a second
-temporary SeedDMS installation.
+temporary SeedDMS installation, which may not be possible, e.g. because of storage
+limitations. It can be the only option if you change servers.
+
+The first update procedure is only needed if the version changes on the minor
+or major version number. Changes in the subminor version number will never
+include database changes and consequently it is sufficient to use the existing
+data directory and database with the new version. Choose the second update
+option in this case.
 
 In both cases make sure to have a backup of your data directory, configuration
 and database.
@@ -180,56 +196,70 @@ and database.
 Fresh installation and take over of data
 -----------------------------------------
 
-- just do a fresh installation somewhere on your web server and make sure it
+The first update option is to set up a new instance of SeedDMS and once
-  works. It is fine to use
+that is running take over the data from your current (old) instance.
-  sqlite for it, even if your final installation uses mysql.
+
-- replace the data directory in your new installation with the data directory
+1. just do a fresh installation somewhere on your web server and make sure it
-  from your current installation. Depending on the size of that directory you
+   works. It is fine to use
-  may either copy, move or place a symbolic link. The content of the data directory
+   SQLite for it, even if your final installation uses MySQL.
-  will not be changed unless you modify your documents. Its perfectly save to
+2. replace the data directory in your new installation with the data directory
-  browse through your documents and download them.
+   from your current installation. Depending on the size of that directory (and
-- copy over the configuration settings.xml into your new installation
+   whether the new installation is on a new server or the old server) you
-- if you use mysql you could as well make a copy of the database to make sure
+   may either copy, move or place a symbolic link. The content of the data directory
-  your current database remains unchanged. As long as you do not do any modification,
+   will not be changed during the update. Its even perfectly save to
-  you could even use your current database.
+   browse through your documents and download them after finishing the
-- modify the settings.xml to fit the fresh install. This will mostly be the
+   update. The data directory will not be modified until you actually modify
-  httpRoot, the paths to the installation directory and possibly the database
+   documents.
-  connection.
+3. copy over the configuration `settings.xml` into your new installation. This will
-- create a file `ENABLE_INSTALL_TOOL` in the conf directory and point
+   effectively make your new installation use the data from your old installation,
-  your browser at http://hostname/seeddms/install
+   because all paths are still pointing to the old installation.
-  The install tool will detect the version of your current SeedDMS installation
+4. if you use mysql you could as well make a copy of the database to make sure
-  and run the required database updates.
+   your current database remains unchanged.
-  If you update just within the last version number (e.g. from 5.1.6 to 5.1.9),
+5. modify the `settings.xml` to fit the environment of the new installation.
-  this step
+   This will mostly be the
-  will not be required because such a subminor version update will never
+   httpRoot, the paths to the installation directory and possibly the database
-  contain database updates.
+   connection.
-- test your new installation. 
+6. create a file `ENABLE_INSTALL_TOOL` in the `conf` directory and point
+   your browser at http://hostname/seeddms/install
+   The install tool will detect the version of your current SeedDMS installation
+   and run the required database updates.
+   If you update just within the last version number (e.g. from 5.1.6 to 5.1.9),
+   this step
+   will not be required because such a subminor version update will never
+   contain database updates.
 
 Upgrading your current installation
 -----------------------------------
 
-- make a backup of your data folder and the configuration file settings.xml
+Instead of setting up a new installation, you may as well replace the php files
-- in case you use mysql then dump your current database
+in your current installation with new versions from the quickstart archive.
-- get the SeedDMS archive seeddms-x.y.z.tar.gz and all pear packages
+
-  SeedDMS_Core, SeedDMS_Lucene, SeedDMS_Preview and extract them over your
+1. get the SeedDMS quickstart archive `seeddms-quickstart-x.y.z.tar.gz` and
-  current instalation. As they do not contain a data directory nor a settings.xml
+   unpack it somewhere on your disc.
-  file, you will not overwrite your existing data and configuration.
+2. copy the directory `seeddms-x.y.z` from the unpacked archive into your
-- you may compare your conf/settings.xml file with the shipped version
+   current installation and make the link `seeddms` point to this new directory.
-  conf/settings.xml.template for new parameters. If you don't do it, the next
+3. copy the directory `pear` from the unpacked archive into your current
-  time you save the configuration the default values will be used.
+   installation, replacing the existing directory. Make a backup of `pear` before
-- create a file `ENABLE_INSTALL_TOOL` in the conf directory and point
+ 	 the replacement if you want to ensure to be able to go back to your old version.
-  your browser at http://hostname/seeddms/install
+4. you may compare your `conf/settings.xml` file with the shipped version
-  The install tool will detect the version of your current SeedDMS installation
+   `conf/settings.xml.template` for new parameters. If you don't do it, the next
-  and run the required database updates.
+   time you save the configuration the default values will be used.
-  If you update just within the last version number (e.g. from 5.1.6 to 5.1.9),
+5. create a file `ENABLE_INSTALL_TOOL` in the `conf` directory and point
-  this step
+   your browser at http://hostname/seeddms/install
-  will not be required because such a subminor version update will never
+   The install tool will detect the version of your current SeedDMS installation
-  contain database updates.
+   and run the required database updates.
+   If you update just within the last version number (e.g. from 5.1.6 to 5.1.9),
+   this step
+   will not be required because such a subminor version update will never
+   contain database updates.
 
 
 THE LONG STORY
 ================
 
+This section is mostly outdated but may still contain some valueable
+information for those trying to understand the installation process.
+
 If you intend to run a single instance of SeedDMS, you are most likely
 better off by using the quickstart archive as described above. This
 section is mostly for users who wants to know more about the internals
@@ -315,7 +345,7 @@ http://localhost/seeddms/
 * Point you web browser towards http://hostname/seeddms/install/
 
 * Follow the instructions on the page and create a file `ENABLE_INSTALL_TOOL`
-  in the conf directory.
+  in the `conf` directory.
 
 * Create a data directory with the thre sub directories staging, cache
   and lucene.
@@ -424,7 +454,7 @@ If you install SeedDMS for the first time continue with the database setup.
   e.g. for mysql:
 	> cat create_tables-innodb.sql | mysql -useeddms -p seeddms
   This step can also be done by the install tool.
-* create a file `ENABLE_INSTALL_TOOL` in the conf directory and point
+* create a file `ENABLE_INSTALL_TOOL` in the `conf` directory and point
   your browser at http://hostname/seeddms/install