diff options
-rw-r--r-- | .gitignore | 1 | ||||
-rw-r--r-- | compiler/app/Main.hs | 10 | ||||
-rw-r--r-- | compiler/readme.md | 10 | ||||
-rw-r--r-- | example/gallery.yaml | 2 | ||||
-rw-r--r-- | ldgallery.1.md | 141 | ||||
-rw-r--r-- | readme.md | 17 | ||||
-rw-r--r-- | viewer/readme.md (renamed from viewer/README.md) | 0 |
7 files changed, 170 insertions, 11 deletions
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 | |||
41 | options = Options | 41 | options = Options |
42 | { inputDir = "./" | 42 | { inputDir = "./" |
43 | &= typDir | 43 | &= typDir |
44 | &= explicit | ||
45 | &= name "i" | 44 | &= name "i" |
46 | &= name "input-dir" | 45 | &= name "input-dir" |
46 | &= explicit | ||
47 | &= help "Gallery source directory (default=./)" | 47 | &= help "Gallery source directory (default=./)" |
48 | , outputDir = "./out" | 48 | , outputDir = "./out" |
49 | &= typDir | 49 | &= typDir |
50 | &= explicit | ||
51 | &= name "o" | 50 | &= name "o" |
52 | &= name "output-dir" | 51 | &= name "output-dir" |
52 | &= explicit | ||
53 | &= help "Generated gallery output path (default=./out)" | 53 | &= help "Generated gallery output path (default=./out)" |
54 | , rebuilAll = False | 54 | , rebuilAll = False |
55 | &= explicit | ||
56 | &= name "r" | 55 | &= name "r" |
57 | &= name "rebuild-all" | 56 | &= name "rebuild-all" |
57 | &= explicit | ||
58 | &= help "Invalidate cache and recompile everything" | 58 | &= help "Invalidate cache and recompile everything" |
59 | , withViewer = False | 59 | , withViewer = False |
60 | &= explicit | ||
61 | &= name "w" | 60 | &= name "w" |
62 | &= name "with-viewer" | 61 | &= name "with-viewer" |
62 | &= explicit | ||
63 | &= help "Include the static web viewer in the output" | 63 | &= help "Include the static web viewer in the output" |
64 | } | 64 | } |
65 | 65 | ||
66 | &= summary ("ldgallery v" ++ (showVersion version) ++ " - a static gallery generator with tags") | 66 | &= summary ("ldgallery v" ++ (showVersion version) ++ " - a static web gallery generator with tags") |
67 | &= program "ldgallery" | 67 | &= program "ldgallery" |
68 | &= help "Compile a gallery" | 68 | &= help "Compile a gallery" |
69 | &= helpArg [explicit, name "h", name "help"] | 69 | &= 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 @@ | |||
1 | # ldgallery-compiler | 1 | # ldgallery-compiler |
2 | 2 | ||
3 | |||
3 | ## Build | 4 | ## Build |
4 | 5 | ||
5 | Building this project requires the [stack] tool. | 6 | Building the _ldgallery compiler_ requires the [stack] tool. |
6 | 7 | ||
7 | [stack]: https://haskellstack.org/ | 8 | [stack]: https://haskellstack.org/ |
8 | 9 | ||
@@ -10,5 +11,10 @@ Within the project's directory, use | |||
10 | 11 | ||
11 | * `stack setup` to setup the development environment and compiler. | 12 | * `stack setup` to setup the development environment and compiler. |
12 | * `stack build` to compile the project. | 13 | * `stack build` to compile the project. |
13 | * or `stack build --fast --file-watch --pedantic` to automatically compile on file change. | 14 | * or `stack build --fast --file-watch` to automatically compile on file change. |
14 | * `stack exec ldgallery-compiler-exe -- --help` to run the compiled program (and displaying its help text for instance). | 15 | * `stack exec ldgallery-compiler-exe -- --help` to run the compiled program (and displaying its help text for instance). |
16 | |||
17 | |||
18 | ### Embedded viewer | ||
19 | |||
20 | 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: | |||
3 | ignoreFiles: .*\.md | 3 | ignoreFiles: .*\.md |
4 | implicitDirectoryTag: false # default | 4 | implicitDirectoryTag: false # default |
5 | 5 | ||
6 | thumbnailResolution: | 6 | thumbnailMaxResolution: |
7 | width: 400 # default | 7 | width: 400 # default |
8 | height: 400 # default | 8 | height: 400 # default |
9 | 9 | ||
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 @@ | |||
1 | % LDGALLERY(1) ldgallery user manual | ||
2 | % Pacien TRAN-GIRARD, Guillaume FOUET | ||
3 | % 2020-01-05 (v0.1.0.0-SNAPSHOT) | ||
4 | |||
5 | |||
6 | # NAME | ||
7 | |||
8 | ldgallery - a static web gallery generator with tags | ||
9 | |||
10 | |||
11 | # DESCRIPTION | ||
12 | |||
13 | ldgallery is a static gallery generator which turns a collection of tagged pictures into a searchable web gallery. | ||
14 | |||
15 | 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. | ||
16 | |||
17 | |||
18 | # COMMAND | ||
19 | |||
20 | ldgallery [\--input-dir=_./_] [\--output-dir=_./out_] [\--with-viewer] | ||
21 | |||
22 | Available options are: | ||
23 | |||
24 | -i, \--input-dir=_DIR_ | ||
25 | : Gallery source directory. Defaults to the current directory. | ||
26 | |||
27 | -o, \--output-dir=_DIR_ | ||
28 | : Generated gallery output path. Defaults to ./out. | ||
29 | |||
30 | -r, \--rebuild-all | ||
31 | : Invalidate cache and recompile everything. | ||
32 | |||
33 | -w, \--with-viewer | ||
34 | : Include the static web viewer in the output. | ||
35 | |||
36 | -h, \--help | ||
37 | : Display help message. | ||
38 | |||
39 | \--version | ||
40 | : Print version information. | ||
41 | |||
42 | \--numeric-version | ||
43 | : Print just the version number. | ||
44 | |||
45 | |||
46 | # INPUT GALLERY STRUCTURE | ||
47 | |||
48 | A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories. | ||
49 | Directory thumbnails can be set by placing a picture file named "thumbnail", with any image file extension, inside of it. | ||
50 | |||
51 | An example input gallery directory structure could be as follows: | ||
52 | |||
53 | ``` | ||
54 | ./example-gallery | ||
55 | ├── DSC0001.jpg --------- a picture | ||
56 | ├── DSC0001.jpg.yaml ---- its associated sidecar metadata file | ||
57 | ├── Some directory ------ a directory grouping gallery items | ||
58 | │ ├── thumbnail.jpg --- a thumbnail for its parent directory | ||
59 | │ ├── DSC0002.jpg | ||
60 | │ ├── DSC0002.jpg.yaml | ||
61 | │ ├── DSC0003.jpg | ||
62 | │ └── DSC0003.jpg.yaml | ||
63 | └── gallery.yaml -------- gallery settings file | ||
64 | ``` | ||
65 | |||
66 | |||
67 | # ITEM METADATA SIDECAR | ||
68 | |||
69 | Item metadata are read from sidecar files of the same name, with the ".yaml" extension appended. | ||
70 | When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below. | ||
71 | Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored. | ||
72 | |||
73 | title | ||
74 | : Title of the item. Defaults to the name of the file. | ||
75 | |||
76 | date | ||
77 | : ISO 8601-formatted date and time. | ||
78 | |||
79 | description | ||
80 | : Description for the item. | ||
81 | |||
82 | tags | ||
83 | : List of tags for the item. Tag groups can be defined using prefixes separated by "." (dot). | ||
84 | |||
85 | |||
86 | # GALLERY CONFIGURATION | ||
87 | |||
88 | The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory. | ||
89 | |||
90 | compiler.galleryName | ||
91 | : Name of the gallery. Defaults to "Gallery". | ||
92 | |||
93 | compiler.ignoreFiles | ||
94 | : Regular expression matching the name of files to ignore. | ||
95 | |||
96 | compiler.implicitDirectoryTag | ||
97 | : Whether to implicitely tag items with the name of their immediate parent directory. | ||
98 | |||
99 | compiler.thumbnailMaxResolution.width | ||
100 | : Maximum width in pixels of the item thumbnails, 400 by default. | ||
101 | |||
102 | compiler.thumbnailMaxResolution.height | ||
103 | : Maximum height in pixels of the item thumbnails, 400 by default. | ||
104 | |||
105 | compiler.pictureMaxResolution.width | ||
106 | : Maximum width in pixels of the picture items, unlimited by default. | ||
107 | |||
108 | compiler.pictureMaxResolution.height | ||
109 | : Maximum height in pixels of the picture items, unlimited by default. | ||
110 | |||
111 | viewer.defaultSearchMode [TODO] | ||
112 | : Default search view mode ("highlight" or "filter"). Defaults to "filter". | ||
113 | |||
114 | viewer.defaultSearchQuery [TODO] | ||
115 | : Default search query string. | ||
116 | |||
117 | viewer.defaultSortOrder [TODO] | ||
118 | : Default sort order ("alphanumeric", "reverse-alphanumeric", "date", "reverse-date"). Defaults to "date". | ||
119 | |||
120 | viewer.tagGroups[].tag [TODO] | ||
121 | : Tag prefix defining the tag group. | ||
122 | |||
123 | viewer.tagGroups[].order [TODO] | ||
124 | : Order in which to display tag groups. | ||
125 | |||
126 | viewer.tagGroups[].colour [TODO] | ||
127 | : Colour associated to the tag group. | ||
128 | |||
129 | viewer.hiddenTags [TODO] | ||
130 | : List of tags to hide by default. Items bearing one of those tags will not be displayed until they are being explicitly searched for. | ||
131 | |||
132 | |||
133 | # SEE ALSO | ||
134 | |||
135 | The ldgallery source code is available on <https://ldgallery.pacien.org>. | ||
136 | |||
137 | Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET. | ||
138 | |||
139 | 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. | ||
140 | |||
141 | 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>. | ||
@@ -1,7 +1,7 @@ | |||
1 | ldgallery | 1 | ldgallery |
2 | ========= | 2 | ========= |
3 | 3 | ||
4 | A static generator which turns a collection of tagged pictures into a searchable web gallery. | 4 | A static gallery generator which turns a collection of tagged pictures into a searchable web gallery. |