aboutsummaryrefslogtreecommitdiff
path: root/compiler/ldgallery.1.md
diff options
context:
space:
mode:
authorpacien2020-05-02 04:11:24 +0200
committerpacien2020-05-02 04:11:24 +0200
commit8e3ac8fe44bebb38e1882ca7f06b8100078ad88d (patch)
treea748fa1e639cb3b5e1f24a8150e89dbb28c980cb /compiler/ldgallery.1.md
parent7042ffc06326fa8ffe70f5a59747709250166c16 (diff)
parent0e0b5b0ae44da7c1d67983dedd8f8d8d3516236f (diff)
downloadldgallery-8e3ac8fe44bebb38e1882ca7f06b8100078ad88d.tar.gz
Merge branch 'develop': release v1.0v1.0
Diffstat (limited to 'compiler/ldgallery.1.md')
-rw-r--r--compiler/ldgallery.1.md191
1 files changed, 191 insertions, 0 deletions
diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md
new file mode 100644
index 0000000..a60a3b1
--- /dev/null
+++ b/compiler/ldgallery.1.md
@@ -0,0 +1,191 @@
1---
2pagetitle: Compiler user manual - ldgallery
3title: LDGALLERY(1) ldgallery
4author: Pacien TRAN-GIRARD, Guillaume FOUET
5date: 2020-04-30 (v1.0)
6---
7
8
9# NAME
10
11ldgallery - a static web gallery generator with tags
12
13
14# DESCRIPTION
15
16ldgallery is a static gallery generator which turns a collection of tagged pictures into a searchable web gallery.
17
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.
20This client-side web application does not require any special software on the server's side.
21
22
23# COMMAND
24
25ldgallery [\--input-dir _./_] [\--output-dir _./out_] [\--with-viewer]
26
27Available options are:
28
29-i, \--input-dir _DIR_
30: Gallery source directory.
31 Defaults to the current directory.
32
33-o, \--output-dir _DIR_
34: Generated gallery output path.
35 Must be distinct from the source directory.
36 Defaults to ./out.
37
38-x, \--output-index _FILE_
39: Generated gallery index output path.
40 Defaults to \<output-dir\>/index.json.
41
42-g, \--gallery-config _FILE_
43: Gallery configuration file.
44 Defaults to \<input-dir\>/gallery.yaml.
45
46-r, \--rebuild-all
47: Invalidate cache and recompile everything.
48
49-c, \--clean-output
50: Remove unnecessary files from the output directory.
51
52-w, \--with-viewer[=_DIR_]
53: Deploy either the bundled or the given static web viewer to the output directory.
54 The compiled gallery itself is then placed in \<output-dir\>/gallery.
55
56-h, \--help
57: Display help message.
58
59\--version
60: Print version information.
61
62\--numeric-version
63: Print just the version number.
64
65
66# INPUT GALLERY STRUCTURE
67
68A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories.
69
70Directory thumbnails can be set by placing a picture file named "_directory", with any image file extension, inside of directories.
71
72An example input gallery directory structure could be as follows:
73
74```
75./example-gallery
76├── DSC0001.jpg --------- a picture
77├── DSC0001.jpg.yaml ---- its associated sidecar metadata file
78├── Some directory ------ a directory grouping gallery items
79│ ├── _directory.jpg -- a thumbnail for its parent directory
80│ ├── _directory.yaml - directory sidecar metadata file
81│ ├── DSC0002.jpg
82│ ├── DSC0002.jpg.yaml
83│ ├── DSC0003.jpg
84│ └── DSC0003.jpg.yaml
85└── gallery.yaml -------- gallery settings file
86```
87
88
89# METADATA SIDECAR
90
91File metadata are read from sidecar files of the same name, with the ".yaml" extension appended.
92Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored.
93
94Directory metadata are read from sidecar files named "_directory.yaml" located within the directory.
95
96When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below.
97
98title
99: Title of the item.
100 Defaults to the name of the file or directory.
101
102<!-- not used in the viewer yet --
103datetime
104: ISO 8601 zoned date and time.
105 Defaults to the last modification time of the file itself,
106 or the most recent modification date of a directory's items.
107-->
108
109<!-- not used in the viewer yet --
110description
111: Description for the item.
112-->
113
114tags
115: List of tags for the item.
116 Tag categories can be defined using prefixes separated by ":" (colon).
117 Tags specified in a directory metadata sidecar are applied to all items within that directory.
118
119
120# GALLERY CONFIGURATION
121
122The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory.
123
124galleryTitle
125: Title of the gallery.
126 Defaults to "ldgallery".
127
128includedDirectories[]
129: Glob patterns of directory names to include in the gallery.
130 Defaults to ["*"] (matches all directory names).
131
132excludedDirectories[]
133: Glob patterns of directory names to exclude from the gallery.
134 Defaults to [] (none).
135
136includedFiles[]
137: Glob patterns of file names to include in the gallery.
138 Defaults to ["*"] (matches all file names).
139
140excludedFiles[]
141: Glob patterns of file names to exclude from the gallery.
142 Defaults to [] (none).
143
144includedTags[]
145: Glob patterns of tags to include in the gallery.
146 Items with no tags can be matched with the empty pattern.
147 Defaults to ["*"] (matches all tags, includes untagged items).
148
149excludedTags[]
150: Glob patterns of tags to exclude from the gallery.
151 Defaults to [] (none).
152
153tagCategories[]
154: Top-level tag categories.
155 Defaults to [] (none).
156
157tagsFromDirectories.fromParents
158: Automatically generate tags from the name of parent directories, looking up in the hierarchy as far as indicated by this parameter.
159 Defaults to 0 (does not generate tags from parent directories).
160
161tagsFromDirectories.prefix
162: Prefix to use for tags automatically generated from the parent directories' names.
163
164thumbnailMaxResolution.width
165: Maximum width in pixels of the item thumbnails, 400 by default.
166
167thumbnailMaxResolution.height
168: Maximum height in pixels of the item thumbnails, 300 by default.
169
170pictureMaxResolution.width
171: Maximum width in pixels of the picture items, unlimited by default.
172
173pictureMaxResolution.height
174: Maximum height in pixels of the picture items, unlimited by default.
175
176
177# SEE ALSO
178
179Related manual pages: __ldgallery-quickstart__(7), __ldgallery-viewer__(7)
180
181The ldgallery source code is available on <https://ldgallery.pacien.org>.
182
183
184# LICENSE
185
186Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET.
187
188This 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.
189
190This 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.
191See the GNU Affero General Public License for more details <https://www.gnu.org/licenses/agpl-3.0.html>.