From e42f4e864bac21ed3b19d1869df2cdd4f8c3433c Mon Sep 17 00:00:00 2001 From: pacien Date: Sat, 22 Feb 2020 14:53:03 +0100 Subject: compiler: flatten gallery config GitHub: closes #129 --- compiler/ldgallery.1.md | 154 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 compiler/ldgallery.1.md (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md new file mode 100644 index 0000000..5524409 --- /dev/null +++ b/compiler/ldgallery.1.md @@ -0,0 +1,154 @@ +--- +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. + +includedDirectories[] +: Glob patterns of directory names to include in the gallery. Defaults to ["*"] (matches all directory names). + +excludedDirectories[] +: Glob patterns of directory names to exclude from the gallery. Defaults to [] (none). + +includedFiles[] +: Glob patterns of file names to include in the gallery. Defaults to ["*"] (matches all file names). + +excludedFiles[] +: Glob patterns of file names to exclude from the gallery. Defaults to [] (none). + +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). + +tagsFromDirectories.prefix +: Prefix to use for tags automatically generated from the parent directories' names. + +thumbnailMaxResolution.width +: Maximum width in pixels of the item thumbnails, 400 by default. + +thumbnailMaxResolution.height +: Maximum height in pixels of the item thumbnails, 300 by default. + +pictureMaxResolution.width +: Maximum width in pixels of the picture items, unlimited by default. + +pictureMaxResolution.height +: Maximum height in pixels of the picture items, unlimited by default. + + +# 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 74e4a83ac7511086f45d2fa9880b7ae5728020bd Mon Sep 17 00:00:00 2001 From: pacien Date: Tue, 25 Feb 2020 20:19:54 +0100 Subject: compiler: add cli arg for output gallery index GitHub: closes #143 --- compiler/ldgallery.1.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 5524409..fd0355b 100644 --- a/compiler/ldgallery.1.md +++ b/compiler/ldgallery.1.md @@ -33,6 +33,10 @@ Available options are: Must be distinct from the source directory. Defaults to ./out. +-x, \--output-index _FILE_ +: Generated gallery index output path. + Defaults to $output-dir/index.json. + -g, \--gallery-config _FILE_ : Gallery configuration file. Defaults to $input-dir/gallery.yaml. @@ -45,6 +49,7 @@ Available options are: -w, \--with-viewer : Include the static web viewer in the output. + The compiled gallery itself is then placed in $output-dir/gallery. -h, \--help : Display help message. -- cgit v1.2.3 From d862c99d6ee74f25261c00fcfee3a6e551501f16 Mon Sep 17 00:00:00 2001 From: pacien Date: Thu, 27 Feb 2020 14:26:12 +0100 Subject: compiler: clarify dependent path documentation --- compiler/ldgallery.1.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index fd0355b..4c9c6c8 100644 --- a/compiler/ldgallery.1.md +++ b/compiler/ldgallery.1.md @@ -35,11 +35,11 @@ Available options are: -x, \--output-index _FILE_ : Generated gallery index output path. - Defaults to $output-dir/index.json. + Defaults to \/index.json. -g, \--gallery-config _FILE_ : Gallery configuration file. - Defaults to $input-dir/gallery.yaml. + Defaults to \/gallery.yaml. -r, \--rebuild-all : Invalidate cache and recompile everything. @@ -49,7 +49,7 @@ Available options are: -w, \--with-viewer : Include the static web viewer in the output. - The compiled gallery itself is then placed in $output-dir/gallery. + The compiled gallery itself is then placed in <\output-dir\>/gallery. -h, \--help : Display help message. -- cgit v1.2.3 From b468dcbf3343ea251703078ec89d3215116fc2f6 Mon Sep 17 00:00:00 2001 From: pacien Date: Tue, 25 Feb 2020 19:25:16 +0100 Subject: compiler: re-introduce gallery title --- compiler/ldgallery.1.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 4c9c6c8..3e20562 100644 --- a/compiler/ldgallery.1.md +++ b/compiler/ldgallery.1.md @@ -115,6 +115,9 @@ tags The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory. +galleryTitle +: Title of the gallery. Defaults to "ldgallery". + includedDirectories[] : Glob patterns of directory names to include in the gallery. Defaults to ["*"] (matches all directory names). -- cgit v1.2.3 From 4f1315cb9ff4a3dd78b90352bb517861bf2d59b7 Mon Sep 17 00:00:00 2001 From: pacien Date: Thu, 27 Feb 2020 17:13:58 +0100 Subject: compiler: allow explicit dist path for viewer deployment --- compiler/ldgallery.1.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 3e20562..7d1dd77 100644 --- a/compiler/ldgallery.1.md +++ b/compiler/ldgallery.1.md @@ -47,9 +47,9 @@ Available options are: -c, \--clean-output : Remove unnecessary files from the output directory. --w, \--with-viewer -: Include the static web viewer in the output. - The compiled gallery itself is then placed in <\output-dir\>/gallery. +-w, \--with-viewer[=_DIR_] +: Deploy either the bundled or the given static web viewer to the output directory. + The compiled gallery itself is then placed in \/gallery. -h, \--help : Display help message. -- cgit v1.2.3 From 8f041b9f13b4c043acc7720aa4c082583b52ffe1 Mon Sep 17 00:00:00 2001 From: pacien Date: Thu, 27 Feb 2020 20:08:24 +0100 Subject: docs: document viewer GitHub: closes #128 --- compiler/ldgallery.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 7d1dd77..1d42eff 100644 --- a/compiler/ldgallery.1.md +++ b/compiler/ldgallery.1.md @@ -1,6 +1,6 @@ --- -pagetitle: User manual - ldgallery -title: LDGALLERY(1) ldgallery user manual +pagetitle: Compiler user manual - ldgallery +title: LDGALLERY(1) ldgallery author: Pacien TRAN-GIRARD, Guillaume FOUET date: 2020-02-15 (v0.1.0.0-SNAPSHOT) --- -- cgit v1.2.3 From c7fa5bd40d0e5c9ea50190a90a0ccfee8ad96c25 Mon Sep 17 00:00:00 2001 From: pacien Date: Thu, 27 Feb 2020 21:05:51 +0100 Subject: viewer: use colon as tag separator instead of dot For consistency with the query language and allowing the use of the very common dot in tags. This also introduces a migration script. GitHub: closes #164 --- compiler/ldgallery.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 1d42eff..59a5b30 100644 --- a/compiler/ldgallery.1.md +++ b/compiler/ldgallery.1.md @@ -107,7 +107,7 @@ description tags : List of tags for the item. - Tag groups can be defined using prefixes separated by "." (dot). + Tag groups can be defined using prefixes separated by ":" (colon). Tags specified in a directory metadata sidecar are applied to all items within that directory. -- cgit v1.2.3 From f09e9d9fa29284bd9ae872efe5ba1d526e349011 Mon Sep 17 00:00:00 2001 From: pacien Date: Wed, 26 Feb 2020 22:13:00 +0100 Subject: compiler: add tag inclusion and exclusion globs GitHub: closes #30 --- compiler/ldgallery.1.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 59a5b30..3c52f9d 100644 --- a/compiler/ldgallery.1.md +++ b/compiler/ldgallery.1.md @@ -130,10 +130,19 @@ includedFiles[] excludedFiles[] : Glob patterns of file names to exclude from the gallery. Defaults to [] (none). +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). + +excludedTags[] +: Glob patterns of tags to exclude from the gallery. + Defaults to [] (none). + 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). + Defaults to 0 (does not generate tags from parent directories). tagsFromDirectories.prefix : Prefix to use for tags automatically generated from the parent directories' names. -- cgit v1.2.3 From 54790c6c73d7c51ff22cf5e9722b141cdc0249df Mon Sep 17 00:00:00 2001 From: pacien Date: Sat, 29 Feb 2020 16:39:55 +0100 Subject: compiler: add tagCategories setting to gallery.yaml --- compiler/ldgallery.1.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 3c52f9d..4f9935b 100644 --- a/compiler/ldgallery.1.md +++ b/compiler/ldgallery.1.md @@ -107,7 +107,7 @@ description tags : List of tags for the item. - Tag groups can be defined using prefixes separated by ":" (colon). + Tag categories can be defined using prefixes separated by ":" (colon). Tags specified in a directory metadata sidecar are applied to all items within that directory. @@ -139,6 +139,10 @@ excludedTags[] : Glob patterns of tags to exclude from the gallery. Defaults to [] (none). +tagCategories[] +: Top-level tag categories. + Defaults to [] (none). + tagsFromDirectories.fromParents : Automatically generate tags from the name of parent directories, looking up in the hierarchy as far as indicated by this parameter. -- cgit v1.2.3 From 69cd09b4eba999447527819401ff9e23bfa1134e Mon Sep 17 00:00:00 2001 From: pacien Date: Fri, 17 Apr 2020 20:21:47 +0200 Subject: docs: prepare docs for release commenting out references to not yet fully implemented features --- compiler/ldgallery.1.md | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 4f9935b..29f0cf3 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-02-15 (v0.1.0.0-SNAPSHOT) +date: 2020-04-17 (v1.0-SNAPSHOT) --- @@ -15,7 +15,9 @@ ldgallery - a static web gallery generator with tags 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. +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 @@ -97,13 +99,17 @@ title : Title of the item. Defaults to the name of the file or directory. + + tags : List of tags for the item. @@ -116,19 +122,24 @@ tags The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory. galleryTitle -: Title of the gallery. Defaults to "ldgallery". +: Title of the gallery. + Defaults to "ldgallery". includedDirectories[] -: Glob patterns of directory names to include in the gallery. Defaults to ["*"] (matches all directory names). +: Glob patterns of directory names to include in the gallery. + Defaults to ["*"] (matches all directory names). excludedDirectories[] -: Glob patterns of directory names to exclude from the gallery. Defaults to [] (none). +: Glob patterns of directory names to exclude from the gallery. + Defaults to [] (none). includedFiles[] -: Glob patterns of file names to include in the gallery. Defaults to ["*"] (matches all file names). +: Glob patterns of file names to include in the gallery. + Defaults to ["*"] (matches all file names). excludedFiles[] -: Glob patterns of file names to exclude from the gallery. Defaults to [] (none). +: Glob patterns of file names to exclude from the gallery. + Defaults to [] (none). includedTags[] : Glob patterns of tags to include in the gallery. @@ -144,8 +155,7 @@ tagCategories[] Defaults to [] (none). tagsFromDirectories.fromParents -: Automatically generate tags from the name of parent directories, - looking up in the hierarchy as far as indicated by this parameter. +: Automatically generate tags from the name of parent directories, looking up in the hierarchy as far as indicated by this parameter. Defaults to 0 (does not generate tags from parent directories). tagsFromDirectories.prefix @@ -172,4 +182,5 @@ 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 . +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 3d8d7cbc7a0ded1c9355ae6309c533ba959ca1e8 Mon Sep 17 00:00:00 2001 From: pacien Date: Fri, 1 May 2020 00:52:53 +0200 Subject: compiler: set version number for first release --- compiler/ldgallery.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 29f0cf3..5a07b7f 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-17 (v1.0-SNAPSHOT) +date: 2020-04-30 (v1.0) --- -- cgit v1.2.3 From 0c355f42dbe71d755fb898b146bac41dd5bdefd8 Mon Sep 17 00:00:00 2001 From: pacien Date: Fri, 1 May 2020 23:00:45 +0200 Subject: doc: add quickstart guide GitHub: closes #206 --- compiler/ldgallery.1.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'compiler/ldgallery.1.md') diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md index 5a07b7f..a60a3b1 100644 --- a/compiler/ldgallery.1.md +++ b/compiler/ldgallery.1.md @@ -176,8 +176,13 @@ pictureMaxResolution.height # SEE ALSO +Related manual pages: __ldgallery-quickstart__(7), __ldgallery-viewer__(7) + The ldgallery source code is available on . + +# LICENSE + 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. -- cgit v1.2.3