docs: document new features and options

2 files changed, 62 insertions, 22 deletions

diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md
index 2fbddc5..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,8 +68,8 @@ Available options are:
 
 A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-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 repsective directories themselves, without any prefix.
+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:
 
@@ -84,7 +85,7 @@ An example input gallery directory structure could be as follows:
 │   ├── song.ogg
 │   ├── song.ogg.yaml
 │   └── song.ogg_thumbnail.jpg -- a thumbnail for song.ogg
-└── gallery.yaml -888------------ gallery settings file
+└── gallery.yaml ---------------- gallery settings file
 ```
 
 
@@ -93,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.
 
@@ -101,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.
@@ -121,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:
 
 galleryTitle
 : Title of the gallery.
@@ -129,7 +131,7 @@ galleryTitle
 
 includedDirectories[]
 : Glob patterns of directory names to include in the gallery.
-  Defaults to ["*"] (matches all directory names).
+  Defaults to ["\*"] (matches all directory names).
 
 excludedDirectories[]
 : Glob patterns of directory names to exclude from the gallery.
@@ -137,7 +139,7 @@ excludedDirectories[]
 
 includedFiles[]
 : Glob patterns of file names to include in the gallery.
-  Defaults to ["*"] (matches all file names).
+  Defaults to ["\*"] (matches all file names).
 
 excludedFiles[]
 : Glob patterns of file names to exclude from the gallery.
@@ -146,7 +148,7 @@ excludedFiles[]
 includedTags[]
 : Glob patterns of tags to include in the gallery.
   Items with no tags can be matched with the empty pattern.
-  Defaults to ["*"] (matches all tags, includes untagged items).
+  Defaults to ["\*"] (matches all tags, includes untagged items).
 
 excludedTags[]
 : Glob patterns of tags to exclude from the gallery.
@@ -178,7 +180,7 @@ pictureMaxResolution.height
 
 # SEE ALSO
 
-Related manual pages: __ldgallery-quickstart__(7), __ldgallery-viewer__(7)
+Related manual pages: __ldgallery-quickstart__(7), __ldgallery-viewer__(7).
 
 The ldgallery source code is available on <https://ldgallery.pacien.org>.
 
diff --git a/viewer/ldgallery-viewer.7.md b/viewer/ldgallery-viewer.7.md
index 41f5003..9ac1512 100644
--- a/viewer/ldgallery-viewer.7.md
+++ b/viewer/ldgallery-viewer.7.md
@@ -2,7 +2,7 @@
 pagetitle: Viewer user manual - ldgallery
 title: LDGALLERY-VIEWER(7) ldgallery
 author: Pacien TRAN-GIRARD, Guillaume FOUET
-date: 2020-04-30 (v1.0)
+date: 2020-09-19 (v2.0)
 ---
 
 
@@ -24,12 +24,23 @@ Its responsiveness allows it to be used from either a desktop browser or some mo
 The viewer's user interface is split into a main item view and a side search panel, which can be opened by using the appropriate button in the toolbar at the top-left corner.
 
 The main view displays the gallery's directories and items as a thumbnail grid.
+The order in which items are displayed can be chosen from the sort menu at the top-left corner.
 
 The side panel allows the user to interactively enter filtering queries to search through the gallery's content.
 This panel features a list of relevant tags, grouped by categories, that can be used to build the search query.
 
-Picture items can be opened and visualised within the application.
-Other types of elements are either downloaded or displayed in the same window depending on the user's web browser supported media types.
+The information panel at the bottom of the sidebar displays various metadata about the currently viewed item.
+Those include the title, date and description of the file or directory.
+
+Items of the following formats can be opened and visualised within the web application:
+
+* Pictures (Bitmap, JPEG, PNG, TIFF, HDR, GIF)
+* Videos (OGV, WebM, Matroska, MPEG-4)
+* Audio files (WAV, Opus, FLAC, MP3, MPEG-4)
+* Plain text files (`.txt`)
+* PDFs
+
+Formats which are not listed above or which are not supported by the user's web browser are offered for download instead of being directly displayed in the same window.
 
 
 # SEARCH QUERIES
@@ -46,17 +57,44 @@ The following modifiers can be used in queries as prefixes of tags:
 `-`
 : Exclude all items having the associated tag, independently of simple tag restrictions and inclusions.
 
-Autocompletion suggestions are shown as filters are being typed in the query field.
+Auto-completion suggestions are shown as filters are being typed in the query field.
 In the case of disambiguated tags, both the category and the tag components are allowed to be partially entered, allowing "loc:fra" to expand into "location:france" for example.
 
 
 # VIEWER CONFIGURATION
 
-The viewer itself can be configured through a JSON file named "config.json" and placed in the web viewer's directory.
+The viewer itself can be configured through a JSON file named __config.json__ and placed in the web viewer's directory.
+
+Viewer configuration options are:
 
 galleryRoot
 : Absolute or relative path to the root of the gallery to display.
 
+galleryIndex
+: Optional index file to use under the value specified for "galleryRoot".
+  Defaults to "index.json".
+
+initialItemSort
+: Order in which gallery items are originally to be displayed.
+  Possible values are "title_asc", "date_asc", "date_desc".
+  Defaults to "title_asc".
+  Titles are sorted using a human-friendly _natural sort order_ which treats multi-digit numbers atomically.
+
+<!-- https://github.com/pacien/ldgallery/issues/27