Merge branch 'develop' for release v2.0v2.0

1 files changed, 52 insertions, 27 deletions

diff --git a/ldgallery-quickstart.7.md b/ldgallery-quickstart.7.md
index 2154d20..4c93f51 100644
--- a/ldgallery-quickstart.7.md
+++ b/ldgallery-quickstart.7.md
@@ -2,27 +2,41 @@
 pagetitle: Quickstart guide - ldgallery
 title: LDGALLERY-QUICKSTART(7) ldgallery
 author: Pacien TRAN-GIRARD, Guillaume FOUET
-date: 2020-05-01 (v1.0)
+date: 2020-09-19 (v2.0)
 ---
 
 # ABOUT
 
-This document is a step-by-step guide showing how to create, compile and deploy a new gallery with _ldgallery_.
+This document is a step-by-step guide showing how to create and compile a simple gallery and get familiar with _ldgallery_.
 
+It mainly describes how to structure the source gallery directory accepted by the _ldgallery_ compiler.
 
-# QUICKSTART GUIDE
+```
+[source gallery directory with items and their tags]
+  |
+  | ldgallery compiler
+  v
+[generated web gallery with embedded web viewer]
+  |
+  | copy
+  v
+[web server]
+```
 
-## Step 1: setting up the compiler
 
-The _ldgallery_ compiler's job is to transform a directory containing pictures and other types of items, alongside additional metadata to associate to those, into a gallery that can be viewed in a web browser.
+# QUICKSTART GUIDE
 
-This compiler program is typically installed and runs on the computer of the gallery's owner.
+## Step 1: initialising the gallery source directory
 
-It can be installed through a package manager (package name "ldgallery") or manually by extracting a prebuilt archive available on the project's website <https://ldgallery.pacien.org>.
+A new gallery can be initialised by creating a directory containing a gallery configuration file named __gallery.yaml__.
 
-## Step 2: initialising the gallery
+```
+./monument-gallery-source
+└── gallery.yaml ----------- gallery settings file
+```
 
-A minimal gallery can be initialised by creating a directory containing a gallery configuration file named "gallery.yaml" with the following content:
+__gallery.yaml__ holds the settings of the gallery.
+Its content can be as follows:
 
 ```yaml
 # gallery.yaml: ldgallery example gallery configuration file.
@@ -34,11 +48,20 @@ tagCategories:
   - city
 ```
 
-## Step 3: adding items
+## Step 2: adding items
 
 A new item, say a picture file named "DSC0001.jpg", can now be added to the directory created at the previous step.
 
-Optionally, some metadata such as a title and some tags can be associated by creating a file named "DSC0001.jpg.yaml" at the same location, with the following content:
+Optionally, some metadata such as a title and some tags can be associated by creating a file named "DSC0001.jpg.yaml" at the same location.
+
+```
+./monument-gallery-source
+├── gallery.yaml ----------- gallery settings file
+├── DSC0001.jpg ------------ a picture
+└── DSC0001.jpg.yaml ------- its associated optional sidecar metadata file
+```
+
+The sidecar metadata file "DSC0001.jpg.yaml" can have the following content:
 
 ```yaml
 # DSC0001.jpg.yaml: ldgallery metadata sidecar file for DSC0001.jpg.
@@ -51,29 +74,29 @@ tags:
   - tower
 ```
 
-## Step 4: compiling the gallery
+## Step 3: compiling the gallery
 
 The gallery can now be compiled by running the following command in a terminal with the right path to the gallery directory created during the previous steps:
 
 ```sh
-ldgallery --with-viewer --input-dir <source gallery path>
+ldgallery \
+  --with-viewer \
+  --input-dir ./monument-gallery-source \
+  --output-dir ./monument-gallery-output
 ```
 
-If the compiler was installed manually through the extraction of a pre-built archive, it might be necessary to specify the full path of the installation:
+If the compiler was installed manually through the extraction of a pre-built archive,
+it might be necessary to specify the full path of the installation:
 
 ```sh
-<installation path>/ldgallery --with-viewer=<installation path>/viewer --input-dir <source gallery path>
+<installation path>/ldgallery \
+  --with-viewer=<installation path>/viewer \
+  --input-dir ./monument-gallery-source \
+  --output-dir ./monument-gallery-output
 ```
 
-Running the command above produces a directory named "out" within the input gallery directory, which contains the compiled gallery and a web viewer, ready to be deployed on some web server.
-
-## Step 5: deploying the gallery
-
-The content of the "out" directory generated at the previous step can now simply be uploaded to some web host, for example with an FTP client like FileZilla or through rsync/SSH with the following command:
-
-```sh
-rsync -Prz <source gallery path>/out/* user@webhost:publication_path/
-```
+Running the command above produces a directory named "monument-gallery-output" in the current directory,
+which contains the compiled gallery and a web viewer ready to be copied to some web server.
 
 The target web host doesn't need to run any additional software besides a web server correctly configured to serve flat static files.
 
@@ -82,18 +105,20 @@ The target web host doesn't need to run any additional software besides a web se
 
 ## Version control
 
-Some standard version-control software such as Git or Mercurial can easily be used to keep track of the evolutions of the gallery directory, thanks to the text-based format used for the sidecar metadata files.
+Some standard version-control software such as Git or Mercurial can easily be used to keep track of the evolutions of the gallery directory,
+thanks to the text-based format used for the sidecar metadata files.
 
 ## Automated compilation and deployment
 
-The compilation and upload commands can be combined in a Makefile or made part of a script for faster and more convenient deployments.
+The gallery can quickly be deployed by using a command such as `rsync`.
 
+The compilation and upload commands can be combined in a Makefile or made part of a script for faster and more convenient deployments.
 Such scripted procedure can then further be automated through Continuous Integration hooks.
 
 
 # SEE ALSO
 
-Related manual pages: __ldgallery__(1), __ldgallery-viewer__(7)
+Related manual pages: __ldgallery__(1), __ldgallery-viewer__(7).
 
 The ldgallery source code is available on <https://ldgallery.pacien.org>.