compiler: flatten gallery config

GitHub: closes #129
author: pacien 2020-02-22 14:53:03 +0100
committer: pacien 2020-02-23 22:49:16 +0100
commit: e42f4e864bac21ed3b19d1869df2cdd4f8c3433c (patch)
tree: 1d9a22c75da88581f904c91d6492c746932c6927 /ldgallery.1.md
parent: ce0b7ec230703d239b3d77e09352c0b1d515d8f5 (diff)
download: ldgallery-e42f4e864bac21ed3b19d1869df2cdd4f8c3433c.tar.gz
1 files changed, 0 insertions, 175 deletions
diff --git a/ldgallery.1.md b/ldgallery.1.md
deleted file mode 100644
index e891345..0000000
--- a/ldgallery.1.md
+++ /dev/null
@@ -1,175 +0,0 @@
---
-pagetitle: User manual - ldgallery
-title: LDGALLERY(1) ldgallery user manual
-author: Pacien TRAN-GIRARD, Guillaume FOUET
-date: 2020-02-15 (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.
-  Must be distinct from the source directory.
-  Defaults to ./out.
-g, \--gallery-config _FILE_
-: Gallery configuration file.
-  Defaults to $input-dir/gallery.yaml.
-r, \--rebuild-all
-: Invalidate cache and recompile everything.
-c, \--clean-output
-: Remove unnecessary files from the output directory.
-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 "_directory", with any image file extension, inside of directories.
-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
-│   ├── DSC0002.jpg
-│   ├── DSC0002.jpg.yaml
-│   ├── DSC0003.jpg
-│   └── DSC0003.jpg.yaml
-└── gallery.yaml -------- gallery settings file
-```
-# METADATA SIDECAR
-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.
-When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below.
-title
-: Title of the item.
-  Defaults to the name of the file or directory.
-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.
-description
-: Description for the item.
-tags
-: List of tags for the item.
-  Tag groups can be defined using prefixes separated by "." (dot).
-  Tags specified in a directory metadata sidecar are applied to all items within that directory.
-# GALLERY CONFIGURATION
-The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory.
-compiler.includedDirectories[]
-: Glob patterns of directory names to include in the gallery.
-  Defaults to ["*"] (matches all directory names).
-compiler.excludedDirectories[]
-: Glob patterns of directory names to exclude from the gallery.
-  Defaults to [] (none).
-compiler.includedFiles[]
-: Glob patterns of file names to include in the gallery.
-  Defaults to ["*"] (matches all file names).
-compiler.excludedFiles[]
-: Glob patterns of file names to exclude from the gallery.
-  Defaults to [] (none).
-compiler.tagsFromDirectories.fromParents
-: Automatically generate tags from the name of parent directories,
-  looking up in the hierarchy as far as indicated by this parameter.
-  Defaults to 0 (do not generate tags from parent directories).
-compiler.tagsFromDirectories.prefix
-: Prefix to use for tags automatically generated from the parent directories' names.
-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, 300 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.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[].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>.
author	pacien	2020-02-22 14:53:03 +0100
committer	pacien	2020-02-23 22:49:16 +0100
commit	e42f4e864bac21ed3b19d1869df2cdd4f8c3433c (patch)
tree	1d9a22c75da88581f904c91d6492c746932c6927 /ldgallery.1.md
parent	ce0b7ec230703d239b3d77e09352c0b1d515d8f5 (diff)
download	ldgallery-e42f4e864bac21ed3b19d1869df2cdd4f8c3433c.tar.gz

diff --git a/ldgallery.1.md b/ldgallery.1.md deleted file mode 100644 index e891345..0000000 --- a/ldgallery.1.md +++ /dev/null
@@ -1,175 +0,0 @@
1	---
2	pagetitle: User manual - ldgallery
3	title: LDGALLERY(1) ldgallery user manual
4	author: Pacien TRAN-GIRARD, Guillaume FOUET
5	date: 2020-02-15 (v0.1.0.0-SNAPSHOT)
6	---
7
8
9	# NAME
10
11	ldgallery - a static web gallery generator with tags
12
13
14	# DESCRIPTION
15
16	ldgallery is a static gallery generator which turns a collection of tagged pictures into a searchable web gallery.
17
18	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.
19
20
21	# COMMAND
22
23	ldgallery [\--input-dir _./_] [\--output-dir _./out_] [\--with-viewer]
24
25	Available options are:
26
27	-i, \--input-dir _DIR_
28	: Gallery source directory.
29	Defaults to the current directory.
30
31	-o, \--output-dir _DIR_
32	: Generated gallery output path.
33	Must be distinct from the source directory.
34	Defaults to ./out.
35
36	-g, \--gallery-config _FILE_
37	: Gallery configuration file.
38	Defaults to $input-dir/gallery.yaml.
39
40	-r, \--rebuild-all
41	: Invalidate cache and recompile everything.
42
43	-c, \--clean-output
44	: Remove unnecessary files from the output directory.
45
46	-w, \--with-viewer
47	: Include the static web viewer in the output.
48
49	-h, \--help
50	: Display help message.
51
52	\--version
53	: Print version information.
54
55	\--numeric-version
56	: Print just the version number.
57
58
59	# INPUT GALLERY STRUCTURE
60
61	A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories.
62
63	Directory thumbnails can be set by placing a picture file named "_directory", with any image file extension, inside of directories.
64
65	An example input gallery directory structure could be as follows:
66
67	```
68	./example-gallery
69	├── DSC0001.jpg --------- a picture
70	├── DSC0001.jpg.yaml ---- its associated sidecar metadata file
71	├── Some directory ------ a directory grouping gallery items
72	│ ├── _directory.jpg -- a thumbnail for its parent directory
73	│ ├── _directory.yaml - directory sidecar metadata file
74	│ ├── DSC0002.jpg
75	│ ├── DSC0002.jpg.yaml
76	│ ├── DSC0003.jpg
77	│ └── DSC0003.jpg.yaml
78	└── gallery.yaml -------- gallery settings file
79	```
80
81
82	# METADATA SIDECAR
83
84	File metadata are read from sidecar files of the same name, with the ".yaml" extension appended.
85	Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored.
86
87	Directory metadata are read from sidecar files named "_directory.yaml" located within the directory.
88
89	When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below.
90
91	title
92	: Title of the item.
93	Defaults to the name of the file or directory.
94
95	datetime
96	: ISO 8601 zoned date and time.
97	Defaults to the last modification time of the file itself,
98	or the most recent modification date of a directory's items.
99
100	description
101	: Description for the item.
102
103	tags
104	: List of tags for the item.
105	Tag groups can be defined using prefixes separated by "." (dot).
106	Tags specified in a directory metadata sidecar are applied to all items within that directory.
107
108
109	# GALLERY CONFIGURATION
110
111	The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory.
112
113	compiler.includedDirectories[]
114	: Glob patterns of directory names to include in the gallery.
115	Defaults to ["*"] (matches all directory names).
116
117	compiler.excludedDirectories[]
118	: Glob patterns of directory names to exclude from the gallery.
119	Defaults to [] (none).
120
121	compiler.includedFiles[]
122	: Glob patterns of file names to include in the gallery.
123	Defaults to ["*"] (matches all file names).
124
125	compiler.excludedFiles[]
126	: Glob patterns of file names to exclude from the gallery.
127	Defaults to [] (none).
128
129	compiler.tagsFromDirectories.fromParents
130	: Automatically generate tags from the name of parent directories,
131	looking up in the hierarchy as far as indicated by this parameter.
132	Defaults to 0 (do not generate tags from parent directories).
133
134	compiler.tagsFromDirectories.prefix
135	: Prefix to use for tags automatically generated from the parent directories' names.
136
137	compiler.thumbnailMaxResolution.width
138	: Maximum width in pixels of the item thumbnails, 400 by default.
139
140	compiler.thumbnailMaxResolution.height
141	: Maximum height in pixels of the item thumbnails, 300 by default.
142
143	compiler.pictureMaxResolution.width
144	: Maximum width in pixels of the picture items, unlimited by default.
145
146	compiler.pictureMaxResolution.height
147	: Maximum height in pixels of the picture items, unlimited by default.
148
149	viewer.defaultSearchQuery [TODO]
150	: Default search query string.
151
152	viewer.defaultSortOrder [TODO]
153	: Default sort order ("alphanumeric", "reverse-alphanumeric", "date", "reverse-date").
154	Defaults to "date".
155
156	viewer.tagGroups[].tag [TODO]
157	: Tag prefix defining the tag group.
158
159	viewer.tagGroups[].colour [TODO]
160	: Colour associated to the tag group.
161
162	viewer.hiddenTags [TODO]
163	: List of tags to hide by default.
164	Items bearing one of those tags will not be displayed until they are being explicitly searched for.
165
166
167	# SEE ALSO
168
169	The ldgallery source code is available on <https://ldgallery.pacien.org>.
170
171	Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET.
172
173	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.
174
175	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>.