add manual

7 files changed, 170 insertions, 11 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..f7e585b
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+*.1
diff --git a/compiler/app/Main.hs b/compiler/app/Main.hs
index 24d8aad..319e984 100644
--- a/compiler/app/Main.hs
+++ b/compiler/app/Main.hs
@@ -41,29 +41,29 @@ data Options = Options
 options = Options
   { inputDir = "./"
       &= typDir
-      &= explicit
       &= name "i"
       &= name "input-dir"
+      &= explicit
       &= help "Gallery source directory (default=./)"
   , outputDir = "./out"
       &= typDir
-      &= explicit
       &= name "o"
       &= name "output-dir"
+      &= explicit
       &= help "Generated gallery output path (default=./out)"
   , rebuilAll = False
-      &= explicit
       &= name "r"
       &= name "rebuild-all"
+      &= explicit
       &= help "Invalidate cache and recompile everything"
   , withViewer = False
-      &= explicit
       &= name "w"
       &= name "with-viewer"
+      &= explicit
       &= help "Include the static web viewer in the output"
   }
 
-  &= summary ("ldgallery v" ++ (showVersion version) ++ " - a static 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"]
diff --git a/compiler/readme.md b/compiler/readme.md
index 5ffe924..e18b026 100644
--- a/compiler/readme.md
+++ b/compiler/readme.md
@@ -1,8 +1,9 @@
 # ldgallery-compiler
 
+
 ## Build
 
-Building this project requires the [stack] tool.
+Building the _ldgallery compiler_ requires the [stack] tool.
 
 [stack]: https://haskellstack.org/
 
@@ -10,5 +11,10 @@ Within the project's directory, use
 
 * `stack setup` to setup the development environment and compiler.
 * `stack build` to compile the project.
-* or `stack build --fast --file-watch --pedantic` to automatically compile on file change.
+* or `stack build --fast --file-watch` to automatically compile on file change.
 * `stack exec ldgallery-compiler-exe -- --help` to run the compiled program (and displaying its help text for instance).
+
+
+### Embedded viewer
+
+In order to allow the `ldgallery` command line tool to generate a full gallery which includes the _viewer_, a compiled version of the web app must be placed under `./data/viewer`.  The `--with-viewer` flag will otherwise not be functional.
diff --git a/example/gallery.yaml b/example/gallery.yaml
index fb25161..53e1448 100644
--- a/example/gallery.yaml
+++ b/example/gallery.yaml
@@ -3,7 +3,7 @@ compiler:
   ignoreFiles: .*\.md
   implicitDirectoryTag: false # default
 
-  thumbnailResolution:
+  thumbnailMaxResolution:
     width: 400  # default
     height: 400 # default
 
diff --git a/ldgallery.1.md b/ldgallery.1.md
new file mode 100644
index 0000000..99d6ccb
--- /dev/null
+++ b/ldgallery.1.md
@@ -0,0 +1,141 @@
+% LDGALLERY(1) ldgallery user manual
+% Pacien TRAN-GIRARD, Guillaume FOUET
+% 2020-01-05 (v0.1.0.0-SNAPSHOT)
+
+
+# NAME
+
+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.
+
+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.  This client-side web application does not require any special software on the server's side.
+
+
+# COMMAND
+
+ldgallery [\--input-dir=_./_] [\--output-dir=_./out_] [\--with-viewer]
+
+Available options are:
+
+-i, \--input-dir=_DIR_
+: Gallery source directory.  Defaults to the current directory.
+
+-o, \--output-dir=_DIR_
+: Generated gallery output path.  Defaults to ./out.
+
+-r, \--rebuild-all
+: Invalidate cache and recompile everything.
+
+-w, \--with-viewer
+: Include the static web viewer in the output.
+
+-h, \--help
+: Display help message.
+
+\--version
+: Print version information.
+
+\--numeric-version
+: Print just the version number.
+
+
+# INPUT GALLERY STRUCTURE
+
+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 "thumbnail", with any image file extension, inside of it.
+
+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
+│   ├── thumbnail.jpg --- a thumbnail for its parent directory
+│   ├── DSC0002.jpg
+│   ├── DSC0002.jpg.yaml
+│   ├── DSC0003.jpg
+│   └── DSC0003.jpg.yaml
+└── gallery.yaml -------- gallery settings file
+```
+
+
+# ITEM METADATA SIDECAR
+
+Item metadata are read from sidecar files of the same name, with the ".yaml" extension appended.
+When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below.
+Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored.
+
+title
+: Title of the item.  Defaults to the name of the file.
+
+date
+: ISO 8601-formatted date and time.
+
+description
+: Description for the item.
+
+tags
+: List of tags for the item.  Tag groups can be defined using prefixes separated by "." (dot).
+
+
+# GALLERY CONFIGURATION
+
+The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory.
+
+compiler.galleryName
+: Name of the gallery.  Defaults to "Gallery".
+
+compiler.ignoreFiles
+: Regular expression matching the name of files to ignore.
+
+compiler.implicitDirectoryTag
+: Whether to implicitely tag items with the name of their immediate parent directory. 
+
+compiler.thumbnailMaxResolution.width
+: Maximum width in pixels of the item thumbnails, 400 by default.
+
+compiler.thumbnailMaxResolution.height
+: Maximum height in pixels of the item thumbnails, 400 by default.
+
+compiler.pictureMaxResolution.width
+: Maximum width in pixels of the picture items, unlimited by default.
+
+compiler.pictureMaxResolution.height
+: Maximum height in pixels of the picture items, unlimited by default.
+
+viewer.defaultSearchMode [TODO]
+: Default search view mode ("highlight" or "filter").  Defaults to "filter".
+
+viewer.defaultSearchQuery [TODO]
+: Default search query string.
+
+viewer.defaultSortOrder [TODO]
+: Default sort order ("alphanumeric", "reverse-alphanumeric", "date", "reverse-date").  Defaults to "date".
+
+viewer.tagGroups[].tag [TODO]
+: Tag prefix defining the tag group.
+
+viewer.tagGroups[].order [TODO]
+: Order in which to display tag groups.
+
+viewer.tagGroups[].colour [TODO]
+: Colour associated to the tag group.
+
+viewer.hiddenTags [TODO]
+: List of tags to hide by default.  Items bearing one of those tags will not be displayed until they are being explicitly searched for.
+
+
+# SEE ALSO
+
+The ldgallery source code is available on <https://ldgallery.pacien.org>.
+
+Copyright (C) 2019-2020  Pacien TRAN-GIRARD and Guillaume FOUET.
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details <https://www.gnu.org/licenses/agpl-3.0.html>.
diff --git a/readme.md b/readme.md
index 7bfcbc0..e7a3902 100644
--- a/readme.md
+++ b/readme.md
@@ -1,7 +1,7 @@
 ldgallery
 =========
 
-A static generator which turns a collection of tagged pictures into a searchable web gallery.
+A static gallery generator which turns a collection of