Tidy up various bits of documentation

doc/admin/administrator_guide.md

@@ -1,4 +1,3 @@
-
 ### Overview
 
 $Projectname is more than a simple web application. It is a
@@ -24,7 +23,7 @@ can about your operating environment and provide as much detail as possible
 about any error messages you may see, so that we can prevent it from happening
 in the future. Due to the large variety of operating systems and PHP platforms
 in existence we may have only limited ability to debug your PHP installation or
-acquire any missing modules * but we will do our best to solve any general code
+acquire any missing modules, but we will do our best to solve any general code
 issues.
 
 ### Before you begin
@@ -45,7 +44,6 @@ site for the first time, please use the SSL ("https://") URL if SSL is available
 This will avoid problems later. The installation routine will not allow you to
 use a non browser-valid certificate.
 
-
 This restriction is incorporated because public posts from you may contain
 references to images on your own hub. Other members viewing their stream on
 other hubs will get warnings if your certificate is not trusted by their web
@@ -87,9 +85,9 @@ There are several ways to deploy a new hub.
   Example config scripts are available for these platforms in doc/install.
   Apache and nginx have the most support.
 
-* PHP 5.5 or later. 
+* PHP 7.1 or later.
- * Note that on some shared hosting environments, the _command line_ version of 
+ * Note that on some shared hosting environments, the _command line_
-PHP might differ from the _webserver_ version
+   version of PHP might differ from the _webserver_ version
 
 * PHP *command line* access with register_argc_argv set to true in the
   php.ini file * and with no hosting provider restrictions on the use of
@@ -150,7 +148,7 @@ web-based administrative tools to function:
 
 #### Official addons
 ##### Installation
-Navigate to your website. Then you should clone the addon repository (separately). We'll give this repository a nickname of 'hzaddons'. You can pull in other hubzilla addon repositories by giving them different nicknames::
+Navigate to your website. Then you should clone the addon repository (separately). We'll give this repository a nickname of 'hzaddons'. You can pull in other hubzilla addon repositories by giving them different nicknames:
 
     cd mywebsite
     util/add_addon_repo https://framagit.org/hubzilla/addons.git hzaddons
@@ -203,9 +201,9 @@ We recommend the following addons be installed on all public sites:
 
 Several web communities have begun to converge using common protocols. The protocols involved are somewhat limited in their abilities. The GNU-Social protocol for instance offers no privacy modes, and the Diaspora protocol is somewhat restrictive in what kinds of communications are allowed. All comments must be signed in a very unique manner by the original author. The ActivityPub protocol is also being considered and may be supported at a future date. No other existing protocol supports nomadic location as used by this project. This presents some support challenges as some features work with some networks and don't work with others. Nevertheless the federation protocols allow connections to be made to a much larger community of people worldwide. They are provided as addons.
 
-> diaspora - The Diaspora Protocol used by Diaspora and Friendica. You should enable 'Diaspora Statistics' (statistics) first to enable all the available features. 
+* diaspora - The Diaspora Protocol used by Diaspora and Friendica. You should enable 'Diaspora Statistics' (statistics) first to enable all the available features.
 
-> gnusoc - The GNU-Social Protocol, used by GNU-Social, Mastodon and several other communities. This addon requires you first install the 'pubsubhubbub' service (also an addon). 
+* gnusoc - The GNU-Social Protocol, used by GNU-Social, Mastodon and several other communities. This addon requires you first install the 'pubsubhubbub' service (also an addon).
 
 Each member of your site must choose whether or not to allow these protocols individually as they may conflict with several desirable core features and abilities of this software (such as channel migration and cloning). They do this from their 'Settings -> Feature/Addon Settings' page. The administrator may also set the following:
 
@@ -314,7 +312,6 @@ empty:
 
     util/config system directory_server ""
 
-
 ### Administration
 
 #### Site Administration
@@ -327,45 +324,112 @@ For security reasons there is no web page or interface on the system which will
 
 A hub can have multiple admins and there is no limit to how administrators you can have. Repeat the above process for every account you wish to provide with administration rights.
 
-
 ### Troubleshooting
 
 #### Log files
 
-The system logfile is an extremely useful resource for tracking down things that go wrong. This can be enabled in the admin/log configuration page. A loglevel setting of LOGGER_DEBUG is preferred for stable production sites. Most things that go wrong with communications or storage are listed here. A setting of LOGGER_DATA provides [b]much[/b] more detail, but may fill your disk. In either case we recommend the use of logrotate on your operating system to cycle logs and discard older entries. 
+The system logfile is an extremely useful resource for tracking down
+things that go wrong. This can be enabled in the admin/log
+configuration page. A loglevel setting of `LOGGER_DEBUG` is preferred
+for stable production sites. Most things that go wrong with
+communications or storage are listed here. A setting of LOGGER_DATA
+provides *much* more detail, but may fill your disk. In either
+case we recommend the use of logrotate on your operating system to
+cycle logs and discard older entries.
 
-At the bottom of your .htconfig.php file are several lines (commented out) which enable PHP error logging. This reports issues with code syntax and executing the code and is the first place you should look for issues which result in a "white screen" or blank page. This is typically the result of code/syntax problems. 
+At the bottom of your .htconfig.php file are several lines (commented
-Database errors are reported to the system logfile, but we've found it useful to have a file in your top-level directory called dbfail.out which [b]only[/b] collects database related issues. If the file exists and is writable, database errors will be logged to it as well as to the system logfile.
+out) which enable PHP error logging. This reports issues with code
+syntax and executing the code and is the first place you should look
+for issues which result in a "white screen" or blank page. This is
+typically the result of code/syntax problems.  Database errors are
+reported to the system logfile, but we've found it useful to have a
+file in your top-level directory called dbfail.out which *only*
+collects database related issues. If the file exists and is writable,
+database errors will be logged to it as well as to the system logfile.
 
-In the case of "500" errors, the issues may often be logged in your webserver logs, often /var/log/apache2/error.log or something similar. Consult your operating system documentation. 
+In the case of "500" errors, the issues may often be logged in your
+webserver logs, often /var/log/apache2/error.log or something
+similar. Consult your operating system documentation.
 
 There are three different log facilities.
 
-**The first is the database failure log**. This is only used if you create a file called specifically 'dbfail.out' in the root folder of your website and make it write-able by the web server. If we have any database failed queries, they are all reported here. They generally indicate typos in our queries, but also occur if the database server disconnects or tables get corrupted. On rare occasions we'll see race conditions in here where two processes tried to create an xchan or cache entry with the same ID. Any other errors (especially persistent errors) should be investigated.
+**The first is the database failure log**. This is only used if you
+  create a file called specifically `dbfail.out` in the root folder of
+  your website and make it write-able by the web server. If we have
+  any database failed queries, they are all reported here. They
+  generally indicate typos in our queries, but also occur if the
+  database server disconnects or tables get corrupted. On rare
+  occasions we'll see race conditions in here where two processes
+  tried to create an xchan or cache entry with the same ID. Any other
+  errors (especially persistent errors) should be investigated.
 
-**The second is the PHP error log**. This is created by the language processor and only reports issues in the language environment. Again these can be syntax errors or programming errors, but these generally are fatal and result in a "white screen of death"; e.g. PHP terminates. You should probably look at this file if something goes wrong that doesn't result in a white screen of death, but it isn't uncommon for this file to be empty for days on end.
+**The second is the PHP error log**. This is created by the language
+  processor and only reports issues in the language environment. Again
+  these can be syntax errors or programming errors, but these
+  generally are fatal and result in a "white screen of death";
+  e.g. PHP terminates. You should probably look at this file if
+  something goes wrong that doesn't result in a white screen of death,
+  but it isn't uncommon for this file to be empty for days on end.
 
-There are some lines at the bottom of the supplied .htconfig.php file; which if uncommented will enable a PHP error log (*extremely* useful for finding the source of white screen failures). This isn't done by default due to potential issues with logfile ownership and write permissions and the fact that there is no logfile rotation by default.                                                                                                          
+  There are some lines at the bottom of the supplied `.htconfig.php`
+  file; which if uncommented will enable a PHP error log (*extremely*
+  useful for finding the source of white screen failures). This isn't
+  done by default due to potential issues with logfile ownership and
+  write permissions and the fact that there is no logfile rotation by
+  default.
 
+**The third is the "application log"**. This is used by $Projectname
+  to report what is going on in the program and usually reports any
+  difficulties or unexpected data we received. It also occasionally
+  reports "heartbeat" status messages to indicate that we reached a
+  certain point in a script. **This** is the most important log file
+  to us, as we create it ourself for the sole purpose of reporting the
+  status of background tasks and anything that seems weird or out of
+  place. It may not be fatal, but maybe just unexpected. If you're
+  performing a task and there's a problem, let us know what is in this
+  file when the problem occurred. (Please don't send me 100M dumps
+  you'll only piss me off). Just a few relevant lines so I can rule
+  out a few hundred thousand lines of code and concentrate on where
+  the problem starts showing up.
 
-**The third is the "application log"**. This is used by $Projectname to report what is going on in the program and usually reports any difficulties or unexpected data we received. It also occasionally reports "heartbeat" status messages to indicate that we reached a certain point in a script. **This** is the most important log file to us, as we create it ourself for the sole purpose of reporting the status of background tasks and anything that seems weird or out of place. It may not be fatal, but maybe just unexpected. If you're performing a task and there's a problem, let us know what is in this file when the problem occurred. (Please don't send me 100M dumps you'll only piss me off). Just a few relevant lines so I can rule out a few hundred thousand lines of code and concentrate on where the problem starts showing up.
+These are your site logs, not mine. We report serious issues at any
+log level. I highly recommend `DEBUG` log level for most sites - which
+provides a bit of additional info and doesn't create huge
+logfiles. When there's a problem which defies all attempts to track,
+you might wish to use `DATA` log level for a short period of time to
+capture all the detail of what structures we were dealing with at the
+time. This log level will use a lot of space so is recommended only
+for brief periods or for developer test sites.
 
-These are your site logs, not mine. We report serious issues at any log level. I highly recommend 'DEBUG' log level for most sites - which provides a bit of additional info and doesn't create huge logfiles. When there's a problem which defies all attempts to track, you might wish to use DATA log level for a short period of time to capture all the detail of what structures we were dealing with at the time. This log level will use a lot of space so is recommended only for brief periods or for developer test sites.
+I recommend configuring logrotate for both the php log and the
+application log. I usually have a look at dbfail.out every week or
+two, fix any issues reported and then starting over with a fresh
+file. Likewise with the PHP logfile. I refer to it once in a while to
+see if there's something that needs fixing.
 
-I recommend configuring logrotate for both the php log and the application log. I usually have a look at dbfail.out every week or two, fix any issues reported and then starting over with a fresh file. Likewise with the PHP logfile. I refer to it once in a while to see if there's something that needs fixing.
+If something goes wrong, and it's not a fatal error, I look at the
+application logfile. Often I will
 
-If something goes wrong, and it's not a fatal error, I look at the application logfile. Often I will
 ```
 tail -f logfile.out
 ```
 
-While repeating an operation that has problems. Often I'll insert extra logging statements in the code if there isn't any hint what's going wrong. Even something as simple as "got here" or printing out the value of a variable that might be suspect. You can do this too - in fact I encourage you to do so. Once you've found what you need to find, you can
+While repeating an operation that has problems. Often I'll insert
+extra logging statements in the code if there isn't any hint what's
+going wrong. Even something as simple as "got here" or printing out
+the value of a variable that might be suspect. You can do this too -
+in fact I encourage you to do so. Once you've found what you need to
+find, you can
 
 ```
 git checkout file.php
 ```
 
-To immediately clear out all the extra logging stuff you added.  Use the information from this log and any detail you can provide from your investigation of the problem to file your bug report - unless your analysis points to the source of the problem. In that case, just fix it. 
+To immediately clear out all the extra logging stuff you added.  Use
+the information from this log and any detail you can provide from your
+investigation of the problem to file your bug report - unless your
+analysis points to the source of the problem. In that case, just fix
+it.
 
 ##### Rotating log files
 
@@ -373,13 +437,25 @@ To immediately clear out all the extra logging stuff you added.  Use the informa
 1. Create a directory in your web root called `log` with webserver write permissions
 1. Go to the **logrot** admin settings and enter this folder name as well as the max size and number of retained log files.
 
-
 #### Reporting issues
 
-When reporting issues, please try to provide as much detail as may be necessary for developers to reproduce the issue and provide the complete text of all error messages.
+When reporting issues, please try to provide as much detail as may be
-
+necessary for developers to reproduce the issue and provide the
-We encourage you to try to the best of your abilities to use these logs combined with the source code in your possession to troubleshoot issues and find their cause. The community is often able to help, but only you have access to your site logfiles and it is considered a security risk to share them.   
+complete text of all error messages.
-
-If a code issue has been uncovered, please report it on the project bugtracker (https://framagit.org/hubzilla/core/issues). Again provide as much detail as possible to avoid us going back and forth asking questions about your configuration or how to duplicate the problem, so that we can get right to the problem and figure out what to do about it. You are also welcome to offer your own solutions and submit patches. In fact we encourage this as we are all volunteers and have little spare time available. The more people that help, the easier the workload for everybody. It's OK if your solution isn't perfect. Every little bit helps and perhaps we can improve on it. 
 
+We encourage you to try to the best of your abilities to use these
+logs combined with the source code in your possession to troubleshoot
+issues and find their cause. The community is often able to help, but
+only you have access to your site logfiles and it is considered a
+security risk to share them.
 
+If a code issue has been uncovered, please report it on the project
+bugtracker (https://framagit.org/hubzilla/core/issues). Again provide
+as much detail as possible to avoid us going back and forth asking
+questions about your configuration or how to duplicate the problem, so
+that we can get right to the problem and figure out what to do about
+it. You are also welcome to offer your own solutions and submit
+patches. In fact we encourage this as we are all volunteers and have
+little spare time available. The more people that help, the easier the
+workload for everybody. It's OK if your solution isn't perfect. Every
+little bit helps and perhaps we can improve on it.