Merge pull request #616 from anaqreon/doco

Doco updates

7 files changed, 175 insertions, 28 deletions

diff --git a/doc/Hubzilla_on_OpenShift.bb b/doc/Hubzilla_on_OpenShift.bb
index 9ccd66284..bdc8bf9bf 100644
--- a/doc/Hubzilla_on_OpenShift.bb
+++ b/doc/Hubzilla_on_OpenShift.bb
@@ -1,4 +1,4 @@
-[b]Hubzilla on OpenShift[/b]
+[b]$Projectname on OpenShift[/b]
 You will notice a new .openshift folder when you fetch from upstream, i.e. from [url=https://github.com/redmatrix/hubzilla.git]https://github.com/redmatrix/hubzilla.git[/url] , which contains a deploy script to set up Hubzilla on OpenShift with plugins and extra themes.
 
 As of this writing, 2015-10-28, you do not have to pay for OpenShift on the Free plan, which gives you three gears at no cost. The Bronze plan gives you three gears at no cost too, but you can expand to 16 gears by paying, and this requires you to register your payment card. The three gears can give three instances of Hubzilla with one gear each, or you can combine two gears into one high-availability Hubzilla instance and one extra gear. The main difference to be aware of is this: gears on the Free plan will go into hibernation if left idle for too long, this does not happen on the Bronze plan. 
diff --git a/doc/admin/administrator_guide.md b/doc/admin/administrator_guide.md
index 47592b58c..bb5c821ee 100644
--- a/doc/admin/administrator_guide.md
+++ b/doc/admin/administrator_guide.md
@@ -1,16 +1,16 @@
 
 # Overview
 
-Hubzilla is more than a simple web application. It is a
+$Projectname is more than a simple web application. It is a
 complex communications system which more closely resembles an email server
 than a web server. For reliability and performance, messages are delivered in
 the background and are queued for later delivery when sites are down. This
 kind of functionality requires a bit more of the host system than the typical
 blog. Not every PHP/MySQL hosting provider will be able to support
-Hubzilla. Many will but please review the requirements and confirm these
+$Projectname. Many will but please review the requirements and confirm these
 with your hosting provider prior to installation.
 
-We've tried very hard to ensure that Hubzilla will run on commodity
+We've tried very hard to ensure that $Projectname will run on commodity
 hosting platforms such as those used to host Wordpress blogs and Drupal
 websites. It will run on most any Linux VPS system. Windows LAMP platforms
 such as XAMPP and WAMP are not officially supported at this time however
@@ -31,7 +31,7 @@ issues.
 
 ## Choose a domain name or subdomain name for your server
 
-Hubzilla can only be installed into the root of a domain or sub-domain, and can 
+$Projectname can only be installed into the root of a domain or sub-domain, and can 
 not be installed using alternate TCP ports.
 
 ## Decide if you will use SSL and obtain an SSL certificate before software installation
@@ -61,15 +61,15 @@ Free "browser-valid" certificates are available from providers such as StartSSL
 and LetsEncrypt. 
 
 If you do NOT use SSL, there may be a delay of up to a minute for the initial
-install script * while we check the SSL port to see if anything responds there.
-When communicating with new sites, Hubzilla always attempts connection on the
+install script - while we check the SSL port to see if anything responds there.
+When communicating with new sites, $Projectname always attempts connection on the
 SSL port first, before falling back to a less secure connection.  If you do not
 use SSL, your webserver MUST NOT listen on port 443 at all.
 
 If you use LetsEncrypt to provide certificates and create a file under 
 .well-known/acme-challenge so that LetsEncrypt can verify your domain ownership, 
 please remove or rename the .well-known directory as soon as the certificate is 
-generated. Hubzilla will provide its own handler for ".well-known" services when
+generated. $Projectname will provide its own handler for ".well-known" services when
 it is installed, and an existing directory in this location may prevent some of 
 these services from working correctly. This should not be a problem with Apache,
 but may be an issue with nginx or other web server platforms.
@@ -111,7 +111,7 @@ PHP might differ from the _webserver_ version
 
 # Manual Installation #
 
-## Unpack the Hubzilla files into the root of your web server document area ###
+## Unpack the $Projectname files into the root of your web server document area ###
 If you copy the directory tree to your webserver, make sure that you include the
 hidden files like .htaccess.
 
@@ -168,7 +168,7 @@ Create searchable representations of the online documentation. You may do this
     util/importdoc
 
 # Automated installation via the .homeinstall shell script
-There is a shell script in (``.homeinstall/hubzilla-setup.sh``) that will install Hubzilla and its dependencies on a fresh installation of Debian 8.3 stable (Jessie). It should work on similar Linux systems but your results may vary.
+There is a shell script in (``.homeinstall/hubzilla-setup.sh``) that will install $Projectname and its dependencies on a fresh installation of Debian 8.3 stable (Jessie). It should work on similar Linux systems but your results may vary.
 
 ## Requirements
 The installation script was originally designed for a small hardware server behind your home router. However, it has been tested on several systems running Debian 8.3:
@@ -194,7 +194,7 @@ The installation script was originally designed for a small hardware server behi
 1. `sed -i "s/^upload_max_filesize =.*/upload_max_filesize = 100M/g" /etc/php5/apache2/php.ini`
 1. `sed -i "s/^post_max_size =.*/post_max_size = 100M/g" /etc/php5/apache2/php.ini`
 1. `service apache2 reload`
-1. Open your domain with a browser and step throught the initial configuration of Hubzilla.
+1. Open your domain with a browser and step throught the initial configuration of $Projectname.
 
 # Service Classes
 
@@ -296,16 +296,16 @@ empty:
 
     util/config system directory_server ""
 
-# Upgrading from RedMatrix to Hubzilla
+# Upgrading from RedMatrix to $Projectname
 
-## How to migrate an individual channel from RedMatrix to Hubzilla
+## How to migrate an individual channel from RedMatrix to $Projectname
 
-1. Clone the channel by opening an account on a Hubzilla hub and performing a basic import (not content) from the original RedMatrix hub. Give your new clone time to sync connections and settings.
+1. Clone the channel by opening an account on a $Projectname hub and performing a basic import (not content) from the original RedMatrix hub. Give your new clone time to sync connections and settings.
 1. Export individual channel content from your RedMatrix hub to a set of JSON text files using the red.hub/uexport tool. Do this in monthly increments if necessary.
-1. Import the JSON data files sequentially in chronological order into the Hubzilla clone using the new.hub/import_items tool.
+1. Import the JSON data files sequentially in chronological order into the $Projectname clone using the new.hub/import_items tool.
 1. Inform your Friendica and Diaspora contacts that your channel moves. They need to reconnect to your new address.  
 1. After successful import (check!) delete your channel on the old RedMatrix Server.
-1. On the Hubzilla server visit new.hub/locs and upgrade to your channel to a primary one. And when the old Redmatrix server is still listed delete them here as well. Press "Sync" to inform all other server in the grid.
+1. On the $Projectname server visit new.hub/locs and upgrade to your channel to a primary one. And when the old Redmatrix server is still listed delete them here as well. Press "Sync" to inform all other server in the grid.
 
 # Troubleshooting
 ## Log files
@@ -319,7 +319,7 @@ There are three different log facilities.
 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 Hubzilla 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.
 
diff --git a/doc/admin/hub_snapshots.md b/doc/admin/hub_snapshots.md
new file mode 100644
index 000000000..7e4ba95b2
--- /dev/null
+++ b/doc/admin/hub_snapshots.md
@@ -0,0 +1,127 @@
+# Hub Snapshot Tools
+
+Hubzilla developers frequently need to switch between branches that might have 
+incompatible database schemas or content. The following two scripts create and 
+restore complete snapshots of a Hubzilla instance, including both the hub web 
+root and the entire database state. Each script requires a config file called 
+`hub-snapshot.conf` residing in the same folder and containing the specific 
+directories and database details of your hub.
+
+# Config
+
+The format of the config file is very strict. There must be no spaces between the 
+variable name and the value. Replace only the content inside the quotes with your 
+configuration. Save this file as `hub-snapshot.conf` alongside the scripts.
+
+    # Location of hub root. Typically this is the location of the Hubzilla repo clone.
+    HUBROOT="/var/www/"
+    # MySQL database name
+    DBNAME="hubzilla"
+    # MySQL database user
+    DBUSER="hubzilla"
+    # MySQL database password
+    DBPWD="akeufajeuwfb"
+    # The target snapshot folder where the git repo will be initialized
+    SNAPSHOTROOT="/root/snapshots/hubzilla/"
+    
+# Snapshot
+
+Example usage:
+
+    sh hub-snapshot.sh my-hub.conf "Commit message for the snapshot" 
+
+**hub-snapshot.sh**:
+
+    #!/bin/bash
+    
+    if ! [ -f "$1" ]; then
+    	echo "$1 is not a valid file. Aborting..."
+    	exit 1
+    fi
+    source "$1"
+    #echo "$DBNAME"
+    #echo "$DBUSER"
+    #echo "$DBPWD"
+    #echo "$HUBROOT"
+    #echo "$SNAPSHOTROOT"
+    MESSAGE="snapshot: $2"
+    
+    if [ "$DBPWD" == "" -o "$SNAPSHOTROOT" == "" -o "$DBNAME" == "" -o "$DBUSER" == "" -o "$HUBROOT" == "" ]; then
+    	echo "Required variable is not set. Aborting..."
+    	exit 1
+    fi
+    
+    if [ ! -d "$SNAPSHOTROOT"/db/ ]; then
+    	mkdir -p "$SNAPSHOTROOT"/db/
+    fi
+    if [ ! -d "$SNAPSHOTROOT"/www/ ]; then
+    	mkdir -p "$SNAPSHOTROOT"/www/
+    fi
+    
+    if [ ! -d "$SNAPSHOTROOT"/www/ ] || [ ! -d "$SNAPSHOTROOT"/db/ ]; then
+    	echo "Error creating snapshot directories. Aborting..."
+    	exit 1
+    fi
+    
+    echo "Export database..."
+    mysqldump -u "$DBUSER" -p"$DBPWD" "$DBNAME" > "$SNAPSHOTROOT"/db/"$DBNAME".sql
+    echo "Copy hub root files..."
+    rsync -va --delete --exclude=.git* "$HUBROOT"/ "$SNAPSHOTROOT"/www/
+    
+    cd "$SNAPSHOTROOT"
+    
+    if [ ! -d ".git" ]; then
+    	git init
+    fi
+    if [ ! -d ".git" ]; then
+    	echo "Cannot initialize git repo. Aborting..."
+    	exit 1
+    fi
+    
+    git add -A
+    echo "Commit hub snapshot..."
+    git commit -a -m "$MESSAGE"
+    
+    exit 0
+
+# Restore
+
+    #!/bin/bash
+    # Restore hub to a previous state. Input hub config and commit hash
+    
+    if ! [ -f "$1" ]; then
+            echo "$1 is not a valid file. Aborting..."
+            exit 1
+    fi
+    source "$1"
+    COMMIT=$2
+    
+    if [ "$DBPWD" == "" -o "$SNAPSHOTROOT" == "" -o "$DBNAME" == "" -o "$DBUSER" == "" -o "$HUBROOT" == "" ]; then
+            echo "Required variable is not set. Aborting..."
+            exit 1
+    fi
+    RESTOREDIR="$(mktemp -d)/"
+    
+    if [ ! -d "$RESTOREDIR" ]; then
+    	echo "Cannot create restore directory. Aborting..."
+    	exit 1
+    fi
+    echo "Cloning the snapshot repo..."
+    git clone "$SNAPSHOTROOT" "$RESTOREDIR"
+    cd "$RESTOREDIR"
+    echo "Checkout requested snapshot..."
+    git checkout "$COMMIT"
+    echo "Restore hub root files..."
+    rsync -a --delete --exclude=.git* "$RESTOREDIR"/www/ "$HUBROOT"/
+    echo "Restore hub database..."
+    mysql -u "$DBUSER" -p"$DBPWD" "$DBNAME" < "$RESTOREDIR"/db/"$DBNAME".sql
+    
+    chown -R www-data:www-data "$HUBROOT"/{store,extend,addon,.htlog,.htconfig.php}
+    
+    echo "Restored hub to snapshot $COMMIT"
+    echo "Removing temporary files..."
+    
+    rm -rf "$RESTOREDIR"
+    
+    exit 0
+
diff --git a/doc/developer/developer_guide.md b/doc/developer/developer_guide.md
index 3c0f7294d..7ec76714f 100644
--- a/doc/developer/developer_guide.md
+++ b/doc/developer/developer_guide.md
@@ -1,4 +1,4 @@
-## Who is a Hubzilla developer? Should I read this?
+# Who is a Hubzilla developer? Should I read this?
 
 Anyone who contributes to making Hubzilla better is a developer. There are many different and important ways you can contribute to this amazing technology, _even if you do not know how to write code_. The software itself is only a part of the Hubzilla project. You can contribute by 
 
@@ -11,31 +11,31 @@ _Software_ developers are of course welcomed; there are so many great ideas to i
 
 This document will help you get started learning and contributing to Hubzilla.
 
-## Versioning system
+# Versioning system
 
 The versioning system is similar to the popular semantic versioning but less stringent. Given x.y.z,  x changes yearly. y changes for "stable" monthly builds, and z increments when there are interface changes. We maintain our date and build numbers for medium grain version control (commits within a certain date range) and of course git revs for fine grained control.
 
-## Git repository branches
+# Git repository branches
 
 There are two official branches of the Hubzilla git repo. 
 
 * The stable version is maintained on the **master** branch. The latest commit in this branch is considered to be suitable for production hubs. 
 * Experimental development occurs on the **dev** branch, which is merged into **master** when it is deemed tested and stable enough.
 
-## Developer tools and workflows
+# Developer tools and workflows
 
-### Hub Snapshots
+## Hub Snapshots
 
 The [[Hub Snapshots]] page provides instructions and scripts for taking complete 
 snapshots of a hub to support switching between consistent and completely known 
 states. This is useful to prevent situations where the content or database schema 
 might be incompatible with the code. 
 
-## Translations
+# Translations
 
 Our translations are managed through Transifex. If you wish to help out translating Hubzilla to another language, sign up on transifex.com, visit [https://www.transifex.com/projects/p/red-matrix/](https://www.transifex.com/projects/p/red-matrix/) and request to join one of the existing language teams or create a new one. Notify one of the core developers when you have a translation update which requires merging, or ask about merging it yourself if you're comfortable with git and PHP. We have a string file called 'messages.po' which is gettext compliant and a handful of email templates, and from there we automatically generate the application's language files.   
 
-### Translation Process
+## Translation Process
 
 The strings used in the UI of Hubzilla is translated at [Transifex][1] and then
 included in the git repository at github. If you want to help with translation
@@ -98,7 +98,7 @@ view/de/hmessages.po you would do the following.
    repository, push it to your fork of the Hubzilla repository at github and
    issue a pull request for that commit.
 
-### Utilities
+## Utilities
 
 Additional to the po2php script there are some more utilities for translation
 in the "util" directory of the Hubzilla source tree.  If you only want to
@@ -108,7 +108,7 @@ works.
 
 For further information see the utils/README file.
 
-### Known Problems
+## Known Problems
 
 * Hubzilla uses the language setting of the visitors browser to determain the
   language for the UI. Most of the time this works, but there are some known
@@ -116,7 +116,7 @@ For further information see the utils/README file.
 * the early translations are based on the friendica translations, if you 
   some rough translations please let us know or fix them at Transifex.
 
-## To-be-organized information
+# To-be-organized information
 
 **Here is how you can join us.**
 
diff --git a/doc/toc.html b/doc/toc.html
index bc5097d0e..a2ebea318 100644
--- a/doc/toc.html
+++ b/doc/toc.html
@@ -77,6 +77,7 @@
         <div id="administrators" class="panel-collapse collapse in">
             <ul class="list-group">
                 <li class="doco-list-group-item"><a href="/help/admin/administrator_guide">Guide</a></li>
+                <li class="doco-list-group-item"><a href="/help/admin/hub_snapshots">Hub Snapshots</a></li>
             </ul>
         </div>
     </div>
@@ -416,7 +417,7 @@
             if(pageName === linkName) {
                 var tocUl = $(this).closest('li').append('<ul>').find('ul');
                 tocUl.removeClass();  // Classes are automatically added to <ul> elements by something else
-                tocUl.toc({content: "#doco-content", headings: "h1,h2"});
+                tocUl.toc({content: "#doco-content", headings: "h1"});
                 tocUl.addClass('toc-content');
                 if( $(window).height() > 499) {
                 tocUl.sticky({topSpacing:$('nav').outerHeight(true), zIndex: 1000});
diff --git a/view/theme/redbasic/css/style.css b/view/theme/redbasic/css/style.css
index 2f3da7542..ae4853ec6 100644
--- a/view/theme/redbasic/css/style.css
+++ b/view/theme/redbasic/css/style.css
@@ -109,6 +109,11 @@ input, optgroup, select, textarea {
 	resize: vertical;
 }
 
+#help-content pre code {
+	overflow-x: auto;
+	white-space: pre;
+}
+
 pre code {
 	border: none;
 }
diff --git a/view/tpl/help.tpl b/view/tpl/help.tpl
index 96d52e0e9..2faaa3853 100644
--- a/view/tpl/help.tpl
+++ b/view/tpl/help.tpl
@@ -3,6 +3,20 @@
 	<h2>{{$title}}</h2>
 	</div>
 	<div class="section-content-wrapper" id="doco-content">
+	<h1>Contents</h1>
+	<ul id="doco-top-toc"></ul>
+	<hr>
 	{{$content}}
 	</div>
 </div>
+
+<script>
+
+	// Generate the table of contents in the side nav menu (see view/tpl/help.tpl)
+	$(document).ready(function () {
+
+		$('#doco-top-toc').toc({content: "#doco-content", headings: "h1,h2,h3,h4"});
+
+	});
+
+</script>
\ No newline at end of file