From 5367781f0c7fd1ce274492ba91895fef9d44dab3 Mon Sep 17 00:00:00 2001 From: pacien Date: Sun, 5 Jan 2020 10:43:48 +0100 Subject: add manual --- ldgallery.1.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 ldgallery.1.md (limited to 'ldgallery.1.md') 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 . + +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 . -- cgit v1.2.3 From 2ad60869c2e8d0846672ccb18b2de99c9cf33671 Mon Sep 17 00:00:00 2001 From: pacien Date: Sun, 5 Jan 2020 19:24:50 +0100 Subject: compiler: add option to add tags from n parent directories GitHub: closes #15 --- ldgallery.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'ldgallery.1.md') diff --git a/ldgallery.1.md b/ldgallery.1.md index 99d6ccb..ec685c6 100644 --- a/ldgallery.1.md +++ b/ldgallery.1.md @@ -93,8 +93,8 @@ compiler.galleryName 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.tagsFromDirectories +: How far to look at parent directories to add implicit tags. Defaults to 0. compiler.thumbnailMaxResolution.width : Maximum width in pixels of the item thumbnails, 400 by default. -- cgit v1.2.3 From 1e3a0e39cb6cdc86a6ba6b570c72c44931cf1c3b Mon Sep 17 00:00:00 2001 From: pacien Date: Sun, 5 Jan 2020 20:40:41 +0100 Subject: compiler: replace file filter with inclusino and exclusion glob lists GitHub: closes #16 --- ldgallery.1.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'ldgallery.1.md') diff --git a/ldgallery.1.md b/ldgallery.1.md index ec685c6..abaeb16 100644 --- a/ldgallery.1.md +++ b/ldgallery.1.md @@ -90,8 +90,11 @@ The gallery settings reside in a file named "gallery.yaml" located at the root o compiler.galleryName : Name of the gallery. Defaults to "Gallery". -compiler.ignoreFiles -: Regular expression matching the name of files to ignore. +compiler.includeFiles[] +: Glob patterns of file names to include in the gallery. Defaults to ["*"] (matches all file names). + +compiler.excludeFiles[] +: Glob patterns of file names to exclude from the gallery. Defaults to [] (none). compiler.tagsFromDirectories : How far to look at parent directories to add implicit tags. Defaults to 0. -- cgit v1.2.3 From c5892200c648eb5d43278a126c5ae7bc91138796 Mon Sep 17 00:00:00 2001 From: pacien Date: Mon, 6 Jan 2020 00:07:17 +0100 Subject: compiler: document default date value --- ldgallery.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'ldgallery.1.md') diff --git a/ldgallery.1.md b/ldgallery.1.md index abaeb16..cfe24d7 100644 --- a/ldgallery.1.md +++ b/ldgallery.1.md @@ -74,7 +74,7 @@ title : Title of the item. Defaults to the name of the file. date -: ISO 8601-formatted date and time. +: ISO 8601-formatted date and time. Defaults to the last modification time of the file. description : Description for the item. -- cgit v1.2.3 From 03d39102ba55cda7cbe80fcdeb9b250caaa70bd0 Mon Sep 17 00:00:00 2001 From: pacien Date: Mon, 6 Jan 2020 10:28:27 +0100 Subject: compiler: properly reject invalid dates in sidecar files GitHub: closes #31 --- ldgallery.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'ldgallery.1.md') diff --git a/ldgallery.1.md b/ldgallery.1.md index cfe24d7..7163c8e 100644 --- a/ldgallery.1.md +++ b/ldgallery.1.md @@ -74,7 +74,7 @@ title : Title of the item. Defaults to the name of the file. date -: ISO 8601-formatted date and time. Defaults to the last modification time of the file. +: ISO 8601 zoned date and time. Defaults to the last modification time of the file. description : Description for the item. -- cgit v1.2.3 From f1ffff03ad6bf86c32c3af90393bd53ca21ad4db Mon Sep 17 00:00:00 2001 From: pacien Date: Mon, 6 Jan 2020 11:05:18 +0100 Subject: compiler: rename date field to more explicit datetime --- ldgallery.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'ldgallery.1.md') diff --git a/ldgallery.1.md b/ldgallery.1.md index 7163c8e..d217367 100644 --- a/ldgallery.1.md +++ b/ldgallery.1.md @@ -73,7 +73,7 @@ Metadata contained within item files themselves (e.g. Exif fields for pictures) title : Title of the item. Defaults to the name of the file. -date +datetime : ISO 8601 zoned date and time. Defaults to the last modification time of the file. description -- cgit v1.2.3 From 8471122afc244d57ad3acdcf5d8413831baf87a8 Mon Sep 17 00:00:00 2001 From: pacien Date: Wed, 8 Jan 2020 08:35:11 +0100 Subject: manual: normalise header --- ldgallery.1.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'ldgallery.1.md') diff --git a/ldgallery.1.md b/ldgallery.1.md index d217367..981dda7 100644 --- a/ldgallery.1.md +++ b/ldgallery.1.md @@ -1,6 +1,9 @@ -% LDGALLERY(1) ldgallery user manual -% Pacien TRAN-GIRARD, Guillaume FOUET -% 2020-01-05 (v0.1.0.0-SNAPSHOT) +--- +pagetitle: User manual - ldgallery +title: LDGALLERY(1) ldgallery user manual +author: Pacien TRAN-GIRARD, Guillaume FOUET +date: 2020-01-05 (v0.1.0.0-SNAPSHOT) +--- # NAME -- cgit v1.2.3