aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorpacien2020-09-19 06:26:19 +0200
committerpacien2020-09-19 22:45:31 +0200
commit9a90abaeff9943118022e4cb71429db147ce7188 (patch)
treea2cb8772a715fb3b8876df139ce8cc1aaa648bd6
parentd9e51ff55ef494d37c5e23ef8fb79500fa5585c5 (diff)
downloadldgallery-9a90abaeff9943118022e4cb71429db147ce7188.tar.gz
docs: document new features and options
-rw-r--r--compiler/ldgallery.1.md34
-rw-r--r--viewer/ldgallery-viewer.7.md50
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 @@
2pagetitle: Compiler user manual - ldgallery 2pagetitle: Compiler user manual - ldgallery
3title: LDGALLERY(1) ldgallery 3title: LDGALLERY(1) ldgallery
4author: Pacien TRAN-GIRARD, Guillaume FOUET 4author: Pacien TRAN-GIRARD, Guillaume FOUET
5date: 2020-04-30 (v1.0) 5date: 2020-09-19 (v2.0)
6--- 6---
7 7
8 8
@@ -13,7 +13,7 @@ ldgallery - a static web gallery generator with tags
13 13
14# DESCRIPTION 14# DESCRIPTION
15 15
16ldgallery is a static gallery generator which turns a collection of tagged pictures into a searchable web gallery. 16ldgallery is a static gallery generator which turns a collection of tagged media files into a searchable web gallery.
17 17
18The ldgallery compiler program processes pictures and aggregates metadata from plain text sidecar files to generate an indexed version of the gallery. 18The ldgallery compiler program processes pictures and aggregates metadata from plain text sidecar files to generate an indexed version of the gallery.
19It can optionally output a static web viewer along, which allows the content to be presented and searched through from a JavaScript-enabled web browser. 19It 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:
45 45
46-r, \--rebuild-all 46-r, \--rebuild-all
47: Invalidate cache and recompile everything. 47: Invalidate cache and recompile everything.
48 By default, the compiler skips items which haven't changed based on their modification time.
48 49
49-c, \--clean-output 50-c, \--clean-output
50: Remove unnecessary files from the output directory. 51: Remove unnecessary files from the output directory.
@@ -67,8 +68,8 @@ Available options are:
67 68
68A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories. 69A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories.
69 70
70Thumbnails can be associated to items by suffixing their name with "_thumbnail", followed by an image file extension. 71Thumbnails can be associated to items by suffixing their name with "\_thumbnail", followed by an image file extension.
71Directory thumbnails can be placed within their repsective directories themselves, without any prefix. 72Directory thumbnails can be placed within their respective directories themselves, without any prefix.
72 73
73An example input gallery directory structure could be as follows: 74An example input gallery directory structure could be as follows:
74 75
@@ -84,7 +85,7 @@ An example input gallery directory structure could be as follows:
84│ ├── song.ogg 85│ ├── song.ogg
85│ ├── song.ogg.yaml 86│ ├── song.ogg.yaml
86│ └── song.ogg_thumbnail.jpg -- a thumbnail for song.ogg 87│ └── song.ogg_thumbnail.jpg -- a thumbnail for song.ogg
87└── gallery.yaml -888------------ gallery settings file 88└── gallery.yaml ---------------- gallery settings file
88``` 89```
89 90
90 91
@@ -93,7 +94,7 @@ An example input gallery directory structure could be as follows:
93File metadata are read from sidecar files of the same name, with the ".yaml" extension appended. 94File metadata are read from sidecar files of the same name, with the ".yaml" extension appended.
94Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored. 95Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored.
95 96
96Directory metadata are read from sidecar files named "_directory.yaml" located within the directory. 97Directory metadata are read from sidecar files named "\_directory.yaml" located within the directory.
97 98
98When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below. 99When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below.
99 100
@@ -101,17 +102,16 @@ title
101: Title of the item. 102: Title of the item.
102 Defaults to the name of the file or directory. 103 Defaults to the name of the file or directory.
103 104
104<!-- not used in the viewer yet --
105datetime 105datetime
106: ISO 8601 zoned date and time. 106: ISO 8601 zoned date and time.
107 Defaults to the last modification time of the file itself, 107 Defaults to the last modification time of the file itself,
108 or the most recent modification date of a directory's items. 108 or the most recent modification date of a directory's items.
109-->
110 109
111<!-- not used in the viewer yet --
112description 110description
113: Description for the item. 111: Optional description for the item.
114--> 112 Rich text formatting is possible through the use of the [GitHub Flavoured Markdown syntax][GFM].
113
114 [GFM]: https://github.github.com/gfm/
115 115
116tags 116tags
117: List of tags for the item. 117: List of tags for the item.
@@ -121,7 +121,9 @@ tags
121 121
122# GALLERY CONFIGURATION 122# GALLERY CONFIGURATION
123 123
124The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory. 124The gallery settings reside in a file named __gallery.yaml__ located at the root of the gallery's source directory.
125
126Gallery configurations options are:
125 127
126galleryTitle 128galleryTitle
127: Title of the gallery. 129: Title of the gallery.
@@ -129,7 +131,7 @@ galleryTitle
129 131
130includedDirectories[] 132includedDirectories[]
131: Glob patterns of directory names to include in the gallery. 133: Glob patterns of directory names to include in the gallery.
132 Defaults to ["*"] (matches all directory names). 134 Defaults to ["\*"] (matches all directory names).
133 135
134excludedDirectories[] 136excludedDirectories[]
135: Glob patterns of directory names to exclude from the gallery. 137: Glob patterns of directory names to exclude from the gallery.
@@ -137,7 +139,7 @@ excludedDirectories[]
137 139
138includedFiles[] 140includedFiles[]
139: Glob patterns of file names to include in the gallery. 141: Glob patterns of file names to include in the gallery.
140 Defaults to ["*"] (matches all file names). 142 Defaults to ["\*"] (matches all file names).
141 143
142excludedFiles[] 144excludedFiles[]
143: Glob patterns of file names to exclude from the gallery. 145: Glob patterns of file names to exclude from the gallery.
@@ -146,7 +148,7 @@ excludedFiles[]
146includedTags[] 148includedTags[]
147: Glob patterns of tags to include in the gallery. 149: Glob patterns of tags to include in the gallery.
148 Items with no tags can be matched with the empty pattern. 150 Items with no tags can be matched with the empty pattern.
149 Defaults to ["*"] (matches all tags, includes untagged items). 151 Defaults to ["\*"] (matches all tags, includes untagged items).
150 152
151excludedTags[] 153excludedTags[]
152: Glob patterns of tags to exclude from the gallery. 154: Glob patterns of tags to exclude from the gallery.
@@ -178,7 +180,7 @@ pictureMaxResolution.height
178 180
179# SEE ALSO 181# SEE ALSO
180 182
181Related manual pages: __ldgallery-quickstart__(7), __ldgallery-viewer__(7) 183Related manual pages: __ldgallery-quickstart__(7), __ldgallery-viewer__(7).
182 184
183The ldgallery source code is available on <https://ldgallery.pacien.org>. 185The ldgallery source code is available on <https://ldgallery.pacien.org>.
184 186
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 @@
2pagetitle: Viewer user manual - ldgallery 2pagetitle: Viewer user manual - ldgallery
3title: LDGALLERY-VIEWER(7) ldgallery 3title: LDGALLERY-VIEWER(7) ldgallery
4author: Pacien TRAN-GIRARD, Guillaume FOUET 4author: Pacien TRAN-GIRARD, Guillaume FOUET
5date: 2020-04-30 (v1.0) 5date: 2020-09-19 (v2.0)
6--- 6---
7 7
8 8
@@ -24,12 +24,23 @@ Its responsiveness allows it to be used from either a desktop browser or some mo
24The 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. 24The 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.
25 25
26The main view displays the gallery's directories and items as a thumbnail grid. 26The main view displays the gallery's directories and items as a thumbnail grid.
27The order in which items are displayed can be chosen from the sort menu at the top-left corner.
27 28
28The side panel allows the user to interactively enter filtering queries to search through the gallery's content. 29The side panel allows the user to interactively enter filtering queries to search through the gallery's content.
29This panel features a list of relevant tags, grouped by categories, that can be used to build the search query. 30This panel features a list of relevant tags, grouped by categories, that can be used to build the search query.
30 31
31Picture items can be opened and visualised within the application. 32The information panel at the bottom of the sidebar displays various metadata about the currently viewed item.
32Other types of elements are either downloaded or displayed in the same window depending on the user's web browser supported media types. 33Those include the title, date and description of the file or directory.
34
35Items of the following formats can be opened and visualised within the web application:
36
37* Pictures (Bitmap, JPEG, PNG, TIFF, HDR, GIF)
38* Videos (OGV, WebM, Matroska, MPEG-4)
39* Audio files (WAV, Opus, FLAC, MP3, MPEG-4)
40* Plain text files (`.txt`)
41* PDFs
42
43Formats 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.
33 44
34 45
35# SEARCH QUERIES 46# SEARCH QUERIES
@@ -46,17 +57,44 @@ The following modifiers can be used in queries as prefixes of tags:
46`-` 57`-`
47: Exclude all items having the associated tag, independently of simple tag restrictions and inclusions. 58: Exclude all items having the associated tag, independently of simple tag restrictions and inclusions.
48 59
49Autocompletion suggestions are shown as filters are being typed in the query field. 60Auto-completion suggestions are shown as filters are being typed in the query field.
50In 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. 61In 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.
51 62
52 63
53# VIEWER CONFIGURATION 64# VIEWER CONFIGURATION
54 65
55The viewer itself can be configured through a JSON file named "config.json" and placed in the web viewer's directory. 66The viewer itself can be configured through a JSON file named __config.json__ and placed in the web viewer's directory.
67
68Viewer configuration options are:
56 69
57galleryRoot 70galleryRoot
58: Absolute or relative path to the root of the gallery to display. 71: Absolute or relative path to the root of the gallery to display.
59 72
73galleryIndex
74: Optional index file to use under the value specified for "galleryRoot".
75 Defaults to "index.json".
76
77initialItemSort
78: Order in which gallery items are originally to be displayed.
79 Possible values are "title_asc", "date_asc", "date_desc".
80 Defaults to "title_asc".
81 Titles are sorted using a human-friendly _natural sort order_ which treats multi-digit numbers atomically.
82
83<!-- https://github.com/pacien/ldgallery/issues/27