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

12 files changed, 528 insertions, 332 deletions

diff --git a/compiler/app/Main.hs b/compiler/app/Main.hs
index 48e5644..e71e0db 100644
--- a/compiler/app/Main.hs
+++ b/compiler/app/Main.hs
@@ -21,6 +21,7 @@ module Main where
 import GHC.Generics (Generic)
 import Paths_ldgallery_compiler (version, getDataFileName)
 import Control.Monad (when)
+import Data.Functor ((<&>))
 import Data.Maybe (isJust)
 import Data.Version (showVersion)
 import Data.Aeson (ToJSON)
@@ -32,7 +33,7 @@ import Compiler
 import Files (readDirectory, copyTo, remove)
 
 
-data ViewerConfig = ViewerConfig
+newtype ViewerConfig = ViewerConfig
   { galleryRoot :: String
   } deriving (Generic, Show, ToJSON)
 
@@ -42,7 +43,7 @@ data Options = Options
   , outputDir :: FilePath
   , outputIndex :: FilePath
   , galleryConfig :: FilePath
-  , rebuilAll :: Bool
+  , rebuildAll :: Bool
   , cleanOutput :: Bool
   , withViewer :: Maybe FilePath
   } deriving (Show, Data, Typeable)
@@ -73,7 +74,7 @@ options = Options
       &= name "gallery-config"
       &= explicit
       &= help "Gallery configuration file (default=<input-dir>/gallery.yaml)"
-  , rebuilAll = False
+  , rebuildAll = False
       &= name "r"
       &= name "rebuild-all"
       &= explicit
@@ -92,7 +93,7 @@ options = Options
       &= help "Deploy either the bundled or the given static web viewer to the output directory"
   }
 
-  &= summary ("ldgallery v" ++ (showVersion version) ++ " - a static web gallery generator with tags")
+  &= summary ("ldgallery v" ++ showVersion version ++ " - a static web gallery generator with tags")
   &= program "ldgallery"
   &= help "Compile a gallery"
   &= helpArg [explicit, name "h", name "help"]
@@ -130,7 +131,7 @@ main =
             (galleryOutputDir opts)
             (outputIndex opts)
             [outputDir opts]
-            (rebuilAll opts)
+            (rebuildAll opts)
             (cleanOutput opts)
       where
         checkDistinctPaths :: FilePath -> FilePath -> IO ()
@@ -146,7 +147,7 @@ main =
 
     deployViewer :: FilePath -> Options -> IO ()
     deployViewer distPath Options{outputDir, cleanOutput} =
-      (when cleanOutput $ cleanViewerDir outputDir)
+      when cleanOutput (cleanViewerDir outputDir)
       >> copyViewer distPath outputDir
       >> writeJSON (outputDir </> "config.json") viewerConfig
 
@@ -154,8 +155,8 @@ main =
         cleanViewerDir :: FilePath -> IO ()
         cleanViewerDir target =
           listDirectory target
-          >>= return . filter (/= gallerySubdir)
-          >>= mapM_ remove . map (target </>)
+          <&> filter (/= gallerySubdir)
+          >>= mapM_ (remove . (target </>))
 
         copyViewer :: FilePath -> FilePath -> IO ()
         copyViewer dist target =
diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md
index a60a3b1..eda6cc2 100644
--- a/compiler/ldgallery.1.md
+++ b/compiler/ldgallery.1.md
@@ -2,7 +2,7 @@
 pagetitle: Compiler user manual - ldgallery
 title: LDGALLERY(1) ldgallery
 author: Pacien TRAN-GIRARD, Guillaume FOUET
-date: 2020-04-30 (v1.0)
+date: 2020-09-19 (v2.0)
 ---
 
 
@@ -13,7 +13,7 @@ ldgallery - a static web gallery generator with tags
 
 # DESCRIPTION
 
-ldgallery is a static gallery generator which turns a collection of tagged pictures into a searchable web gallery.
+ldgallery is a static gallery generator which turns a collection of tagged media files into a searchable web gallery.
 
 The ldgallery compiler program processes pictures and aggregates metadata from plain text sidecar files to generate an indexed version of the gallery.
 It can optionally output a static web viewer along, which allows the content to be presented and searched through from a JavaScript-enabled web browser.
@@ -45,6 +45,7 @@ Available options are:
 
 -r, \--rebuild-all
 : Invalidate cache and recompile everything.
+  By default, the compiler skips items which haven't changed based on their modification time.
 
 -c, \--clean-output
 : Remove unnecessary files from the output directory.
@@ -67,22 +68,24 @@ Available options are:
 
 A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories.
 
-Directory thumbnails can be set by placing a picture file named "_directory", with any image file extension, inside of directories.
+Thumbnails can be associated to items by suffixing their name with "\_thumbnail", followed by an image file extension.
+Directory thumbnails can be placed within their respective directories themselves, without any prefix.
 
 An example input gallery directory structure could be as follows:
 
 ```
 ./example-gallery
-├── DSC0001.jpg --------- a picture
-├── DSC0001.jpg.yaml ---- its associated sidecar metadata file
-├── Some directory ------ a directory grouping gallery items
-│   ├── _directory.jpg -- a thumbnail for its parent directory
-│   ├── _directory.yaml - directory sidecar metadata file
+├── DSC0001.jpg ----------------- a picture
+├── DSC0001.jpg.yaml ------------ its associated sidecar metadata file
+├── Some directory -------------- a directory grouping gallery items
+│   ├── _directory.yaml --------- directory sidecar metadata file
+│   ├── _thumbnail.jpg ---------- a thumbnail for its parent directory
 │   ├── DSC0002.jpg
 │   ├── DSC0002.jpg.yaml
-│   ├── DSC0003.jpg
-│   └── DSC0003.jpg.yaml
-└── gallery.yaml -------- gallery settings file
+│   ├── song.ogg
+│   ├── song.ogg.yaml
+│   └── song.ogg_thumbnail.jpg -- a thumbnail for song.ogg
+└── gallery.yaml ---------------- gallery settings file
 ```
 
 
@@ -91,7 +94,7 @@ An example input gallery directory structure could be as follows:
 File metadata are read from sidecar files of the same name, with the ".yaml" extension appended.
 Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored.
 
-Directory metadata are read from sidecar files named "_directory.yaml" located within the directory.
+Directory metadata are read from sidecar files named "\_directory.yaml" located within the directory.
 
 When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below.
 
@@ -99,17 +102,16 @@ title
 : Title of the item.
   Defaults to the name of the file or directory.
 
-<!-- not used in the viewer yet --
 datetime
 : ISO 8601 zoned date and time.
   Defaults to the last modification time of the file itself,
   or the most recent modification date of a directory's items.
--->
 
-<!-- not used in the viewer yet --
 description
-: Description for the item.
--->
+: Optional description for the item.
+  Rich text formatting is possible through the use of the [GitHub Flavoured Markdown syntax][GFM].
+
+  [GFM]: https://github.github.com/gfm/
 
 tags
 : List of tags for the item.
@@ -119,7 +121,9 @@ tags
 
 # GALLERY CONFIGURATION
 
-The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory.
+The gallery settings reside in a file named __gallery.yaml__ located at the root of the gallery's source directory.
+
+Gallery configurations options are: