From 5367781f0c7fd1ce274492ba91895fef9d44dab3 Mon Sep 17 00:00:00 2001 From: pacien Date: Sun, 5 Jan 2020 10:43:48 +0100 Subject: add manual --- .gitignore | 1 + compiler/app/Main.hs | 10 ++-- compiler/readme.md | 10 +++- example/gallery.yaml | 2 +- ldgallery.1.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++ readme.md | 17 +++++-- viewer/README.md | 26 ---------- viewer/readme.md | 26 ++++++++++ 8 files changed, 196 insertions(+), 37 deletions(-) create mode 100644 .gitignore create mode 100644 ldgallery.1.md delete mode 100644 viewer/README.md create mode 100644 viewer/readme.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f7e585b --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*.1 diff --git a/compiler/app/Main.hs b/compiler/app/Main.hs index 24d8aad..319e984 100644 --- a/compiler/app/Main.hs +++ b/compiler/app/Main.hs @@ -41,29 +41,29 @@ data Options = Options options = Options { inputDir = "./" &= typDir - &= explicit &= name "i" &= name "input-dir" + &= explicit &= help "Gallery source directory (default=./)" , outputDir = "./out" &= typDir - &= explicit &= name "o" &= name "output-dir" + &= explicit &= help "Generated gallery output path (default=./out)" , rebuilAll = False - &= explicit &= name "r" &= name "rebuild-all" + &= explicit &= help "Invalidate cache and recompile everything" , withViewer = False - &= explicit &= name "w" &= name "with-viewer" + &= explicit &= help "Include the static web viewer in the output" } - &= summary ("ldgallery v" ++ (showVersion version) ++ " - a static gallery generator with tags") + &= summary ("ldgallery v" ++ (showVersion version) ++ " - a static web gallery generator with tags") &= program "ldgallery" &= help "Compile a gallery" &= helpArg [explicit, name "h", name "help"] diff --git a/compiler/readme.md b/compiler/readme.md index 5ffe924..e18b026 100644 --- a/compiler/readme.md +++ b/compiler/readme.md @@ -1,8 +1,9 @@ # ldgallery-compiler + ## Build -Building this project requires the [stack] tool. +Building the _ldgallery compiler_ requires the [stack] tool. [stack]: https://haskellstack.org/ @@ -10,5 +11,10 @@ Within the project's directory, use * `stack setup` to setup the development environment and compiler. * `stack build` to compile the project. -* or `stack build --fast --file-watch --pedantic` to automatically compile on file change. +* or `stack build --fast --file-watch` to automatically compile on file change. * `stack exec ldgallery-compiler-exe -- --help` to run the compiled program (and displaying its help text for instance). + + +### Embedded viewer + +In order to allow the `ldgallery` command line tool to generate a full gallery which includes the _viewer_, a compiled version of the web app must be placed under `./data/viewer`. The `--with-viewer` flag will otherwise not be functional. diff --git a/example/gallery.yaml b/example/gallery.yaml index fb25161..53e1448 100644 --- a/example/gallery.yaml +++ b/example/gallery.yaml @@ -3,7 +3,7 @@ compiler: ignoreFiles: .*\.md implicitDirectoryTag: false # default - thumbnailResolution: + thumbnailMaxResolution: width: 400 # default height: 400 # default 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 . diff --git a/readme.md b/readme.md index 7bfcbc0..e7a3902 100644 --- a/readme.md +++ b/readme.md @@ -1,7 +1,7 @@ ldgallery ========= -A static generator which turns a collection of tagged pictures into a searchable web gallery. +A static gallery generator which turns a collection of tagged pictures into a searchable web gallery. The complete list of features, the user manual, demo and download links can be found on the project's website: https://ldgallery.pacien.org. @@ -9,12 +9,23 @@ The complete list of features, the user manual, demo and download links can be f Build ----- -TODO +* Compile the web _viewer_ as detailed in `./viewer/readme.md`. +* Copy/link the compiled _viewer_ to the _ldgallery compiler_ data directory. +* Compile the _ldgallery compiler_ as detailed in `./compiler/readme.md`. + + +The man page can be generated using [Pandoc]: + +``` +pandoc --standalone --to man ldgallery.1.md --output=ldgallery.1 +``` + +[Pandoc]: https://pandoc.org/ License ------- -Copyright (C) 2019 Pacien TRAN-GIRARD and Guillaume FOUET. +Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET. _ldgallery_ is distributed under the terms of the GNU Affero General Public License v3.0, as detailed in `license.md`. diff --git a/viewer/README.md b/viewer/README.md deleted file mode 100644 index 864dcc6..0000000 --- a/viewer/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# ldgallery-viewer - -If you get errors with optionals and coalesce, enable the Vetur global preference: useWorkspaceDependencies - -## Project setup -``` -npm install -``` - -### Compiles and hot-reloads for development -``` -npm run serve -``` - -### Compiles and minifies for production -``` -npm run build -``` - -### Lints and fixes files -``` -npm run lint -``` - -### Customize configuration -See [Configuration Reference](https://cli.vuejs.org/config/). diff --git a/viewer/readme.md b/viewer/readme.md new file mode 100644 index 0000000..864dcc6 --- /dev/null +++ b/viewer/readme.md @@ -0,0 +1,26 @@ +# ldgallery-viewer + +If you get errors with optionals and coalesce, enable the Vetur global preference: useWorkspaceDependencies + +## Project setup +``` +npm install +``` + +### Compiles and hot-reloads for development +``` +npm run serve +``` + +### Compiles and minifies for production +``` +npm run build +``` + +### Lints and fixes files +``` +npm run lint +``` + +### Customize configuration +See [Configuration Reference](https://cli.vuejs.org/config/). -- cgit v1.2.3