From 76c3a4dbed11b9a5df2437db00e96608244bd693 Mon Sep 17 00:00:00 2001
From: nodiscc <nodiscc@gmail.com>
Date: Sat, 18 Nov 2017 16:22:43 +0100
Subject: [PATCH] documentation cleanup  * In preparation of #930 work  *
 Remove/reorder duplicate documentation from
 Makefile/Unit-tests.md/Download-and-Installation.md (composer information is
 now in Unit-tests.md)  * Installation using git: add composer requirement to
 all git installation procedures, add python3-virtualenv requirement  *
 Styling (horizontal rulers, spacing, descriptive headers)

---
 Makefile                            | 11 ----------
 doc/md/Download-and-Installation.md | 34 +++++++++++++++++++----------
 doc/md/Unit-tests.md                | 10 +++++----
 3 files changed, 29 insertions(+), 26 deletions(-)

diff --git a/Makefile b/Makefile
index c2d5594..d659d90 100644
--- a/Makefile
+++ b/Makefile
@@ -1,17 +1,6 @@
 # The personal, minimalist, super-fast, database free, bookmarking service.
 # Makefile for PHP code analysis & testing, documentation and release generation
 
-# Prerequisites:
-# - install Composer, either:
-#   - from your distro's package manager;
-#   - from the official website (https://getcomposer.org/download/);
-# - install/update test dependencies:
-#   $ composer install  # 1st setup
-#   $ composer update
-# - install Xdebug for PHPUnit code coverage reports:
-#   - see http://xdebug.org/docs/install
-#   - enable in php.ini
-
 BIN = vendor/bin
 PHP_SOURCE = index.php application tests plugins
 PHP_COMMA_SOURCE = index.php,application,tests,plugins
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index be848c9..e64d1a4 100644
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -17,40 +17,44 @@ Using one of the following methods:
 - by cloning the Git repository
 - using Docker: [see the documentation](docker/shaarli-images)
 
----
+--------------------------------------------------------------------------------
 
 ## Latest release (recommended)
-### Download as an archive
-Get the latest released version from the [releases](https://github.com/shaarli/Shaarli/releases) page.
 
-**Download our *shaarli-full* archive** to include dependencies.
+### Download as an archive
+
+In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. **Download our *shaarli-full* archive** to include dependencies.
 
 The current latest released version is `v0.9.1`
 
-Or in command lines:
-
 ```bash
 $ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.1/shaarli-v0.9.1-full.zip
 $ unzip shaarli-v0.9.1-full.zip
 $ mv Shaarli /path/to/shaarli/
 ```
 
-In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. 
-Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).
-
 ### Using git
 
+Cloning using `git` or downloading Github branches as zip files requires additional steps:
+
+ * Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
+ * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation.
+
 ```
 $ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
 $ git clone -b latest https://github.com/shaarli/Shaarli.git .
 $ composer install --no-dev --prefer-dist
 $ make translate
+$ make htmldoc
 ```
 
+--------------------------------------------------------------------------------
+
 ## Stable version
 
 The stable version has been experienced by Shaarli users, and will receive security updates.
 
+
 ### Download as an archive
 
 As a .zip archive:
@@ -69,9 +73,9 @@ $ tar xvf stable.tar.gz
 $ mv Shaarli-stable /path/to/shaarli/
 ```
 
-### Clone with Git 
+### Using git
 
-[Composer](https://getcomposer.org/) is required to build a functional Shaarli installation when pulling from git.
+Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
 
 ```bash
 $ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
@@ -80,10 +84,15 @@ $ cd /path/to/shaarli/
 $ composer install --no-dev --prefer-dist
 ```
 
+
+--------------------------------------------------------------------------------
+
 ## Development version (mainline)
 
 _Use at your own risk!_
 
+Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
+
 To get the latest changes from the `master` branch:
 
 ```bash
@@ -93,8 +102,11 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
 $ cd /path/to/shaarli
 $ composer install --no-dev --prefer-dist
 $ make translate
+$ make htmldoc
 ```
 
+-------------------------------------------------------------------------------
+
 ## Finish Installation
 
 Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
diff --git a/doc/md/Unit-tests.md b/doc/md/Unit-tests.md
index d200634..f6030d5 100644
--- a/doc/md/Unit-tests.md
+++ b/doc/md/Unit-tests.md
@@ -2,12 +2,12 @@
 
 The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
 
-Regarding Composer, you can either use:
+### Install composer
+
+You can either use:
 
 - a system-wide version, e.g. installed through your distro's package manager
-- a local version, downloadable [here](https://getcomposer.org/download/)
-
-#### Sample usage
+- a local version, downloadable [here](https://getcomposer.org/download/).
 
 ```bash
 # system-wide version
@@ -29,6 +29,8 @@ $ composer update
 
 #### Install and enable Xdebug to generate PHPUnit coverage reports
 
+See http://xdebug.org/docs/install
+
 For Debian-based distros:
 ```bash
 $ aptitude install php5-xdebug