aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.travis.yml2
-rw-r--r--compiler/ldgallery.1.md5
-rw-r--r--ldgallery-quickstart.7.md108
-rw-r--r--readme.md1
-rw-r--r--viewer/ldgallery-viewer.7.md5
5 files changed, 121 insertions, 0 deletions
diff --git a/.travis.yml b/.travis.yml
index 6bf6f29..40798fe 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -54,6 +54,7 @@ jobs:
54 - stack build --no-terminal 54 - stack build --no-terminal
55 - stack install --local-bin-path ../dist/ 55 - stack install --local-bin-path ../dist/
56 - cd .. 56 - cd ..
57 - pandoc --standalone --to man ldgallery-quickstart.7.md --output dist/ldgallery-quickstart.7
57 - pandoc --standalone --to man compiler/ldgallery.1.md --output dist/ldgallery.1 58 - pandoc --standalone --to man compiler/ldgallery.1.md --output dist/ldgallery.1
58 - pandoc --standalone --to man viewer/ldgallery-viewer.7.md --output dist/ldgallery-viewer.7 59 - pandoc --standalone --to man viewer/ldgallery-viewer.7.md --output dist/ldgallery-viewer.7
59 - cp changelog.md license.md dist/ 60 - cp changelog.md license.md dist/
@@ -117,6 +118,7 @@ jobs:
117 - stack build --no-terminal 118 - stack build --no-terminal
118 - stack install --local-bin-path ../dist/ 119 - stack install --local-bin-path ../dist/
119 - cd .. 120 - cd ..
121 - cp ldgallery-quickstart.7.md dist/ldgallery-quickstart.7.md
120 - cp viewer/ldgallery-viewer.7.md dist/ldgallery-viewer.7.md 122 - cp viewer/ldgallery-viewer.7.md dist/ldgallery-viewer.7.md
121 - cp compiler/ldgallery.1.md dist/ldgallery.1.md 123 - cp compiler/ldgallery.1.md dist/ldgallery.1.md
122 - cp changelog.md license.md dist/ 124 - cp changelog.md license.md dist/
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
176 176
177# SEE ALSO 177# SEE ALSO
178 178
179Related manual pages: __ldgallery-quickstart__(7), __ldgallery-viewer__(7)
180
179The ldgallery source code is available on <https://ldgallery.pacien.org>. 181The ldgallery source code is available on <https://ldgallery.pacien.org>.
180 182
183
184# LICENSE
185
181Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET. 186Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET.
182 187
183This 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. 188This 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.
diff --git a/ldgallery-quickstart.7.md b/ldgallery-quickstart.7.md
new file mode 100644
index 0000000..2154d20
--- /dev/null
+++ b/ldgallery-quickstart.7.md
@@ -0,0 +1,108 @@
1---
2pagetitle: Quickstart guide - ldgallery
3title: LDGALLERY-QUICKSTART(7) ldgallery
4author: Pacien TRAN-GIRARD, Guillaume FOUET
5date: 2020-05-01 (v1.0)
6---
7
8# ABOUT
9
10This document is a step-by-step guide showing how to create, compile and deploy a new gallery with _ldgallery_.
11
12
13# QUICKSTART GUIDE
14
15## Step 1: setting up the compiler
16
17The _ldgallery_ compiler's job is to transform a directory containing pictures and other types of items, alongside additional metadata to associate to those, into a gallery that can be viewed in a web browser.
18
19This compiler program is typically installed and runs on the computer of the gallery's owner.
20
21It can be installed through a package manager (package name "ldgallery") or manually by extracting a prebuilt archive available on the project's website <https://ldgallery.pacien.org>.
22
23## Step 2: initialising the gallery
24
25A minimal gallery can be initialised by creating a directory containing a gallery configuration file named "gallery.yaml" with the following content:
26
27```yaml
28# gallery.yaml: ldgallery example gallery configuration file.
29# See ldgallery(1) for a list of available configuration keys.
30
31galleryTile: Monuments of the World
32
33tagCategories:
34 - city
35```
36
37## Step 3: adding items
38
39A new item, say a picture file named "DSC0001.jpg", can now be added to the directory created at the previous step.
40
41Optionally, some metadata such as a title and some tags can be associated by creating a file named "DSC0001.jpg.yaml" at the same location, with the following content:
42
43```yaml
44# DSC0001.jpg.yaml: ldgallery metadata sidecar file for DSC0001.jpg.
45# See ldgallery(1) for a list of available keys.
46
47title: The Eiffel Tower
48
49tags:
50 - city:Paris
51 - tower
52```
53
54## Step 4: compiling the gallery
55
56The gallery can now be compiled by running the following command in a terminal with the right path to the gallery directory created during the previous steps:
57
58```sh
59ldgallery --with-viewer --input-dir <source gallery path>
60```
61
62If the compiler was installed manually through the extraction of a pre-built archive, it might be necessary to specify the full path of the installation:
63
64```sh
65<installation path>/ldgallery --with-viewer=<installation path>/viewer --input-dir <source gallery path>
66```
67
68Running the command above produces a directory named "out" within the input gallery directory, which contains the compiled gallery and a web viewer, ready to be deployed on some web server.
69
70## Step 5: deploying the gallery
71
72The content of the "out" directory generated at the previous step can now simply be uploaded to some web host, for example with an FTP client like FileZilla or through rsync/SSH with the following command:
73
74```sh
75rsync -Prz <source gallery path>/out/* user@webhost:publication_path/
76```
77
78The target web host doesn't need to run any additional software besides a web server correctly configured to serve flat static files.
79
80
81# TIPS
82
83## Version control
84
85Some standard version-control software such as Git or Mercurial can easily be used to keep track of the evolutions of the gallery directory, thanks to the text-based format used for the sidecar metadata files.
86
87## Automated compilation and deployment
88
89The compilation and upload commands can be combined in a Makefile or made part of a script for faster and more convenient deployments.
90
91Such scripted procedure can then further be automated through Continuous Integration hooks.
92
93
94# SEE ALSO
95
96Related manual pages: __ldgallery__(1), __ldgallery-viewer__(7)
97
98The ldgallery source code is available on <https://ldgallery.pacien.org>.
99
100
101# LICENSE
102
103Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET.
104
105This 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.
106
107This 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.
108See the GNU Affero General Public License for more details <https://www.gnu.org/licenses/agpl-3.0.html>.
diff --git a/readme.md b/readme.md
index dc370a2..2b648ae 100644
--- a/readme.md
+++ b/readme.md
@@ -17,6 +17,7 @@ Build
17The man pages can be generated using [Pandoc]: 17The man pages can be generated using [Pandoc]:
18 18
19``` 19```
20pandoc --standalone --to man ldgallery-quickstart.7.md --output ldgallery-quickstart.7
20pandoc --standalone --to man compiler/ldgallery.1.md --output ldgallery.1 21pandoc --standalone --to man compiler/ldgallery.1.md --output ldgallery.1
21pandoc --standalone --to man viewer/ldgallery-viewer.7.md --output ldgallery-viewer.7 22pandoc --standalone --to man viewer/ldgallery-viewer.7.md --output ldgallery-viewer.7
22``` 23```
diff --git a/viewer/ldgallery-viewer.7.md b/viewer/ldgallery-viewer.7.md
index 6f572fe..41f5003 100644
--- a/viewer/ldgallery-viewer.7.md
+++ b/viewer/ldgallery-viewer.7.md
@@ -68,8 +68,13 @@ An example of such manifest and an associated icon are available in the example
68 68
69# SEE ALSO 69# SEE ALSO
70 70
71Related manual pages: __ldgallery__(1), __ldgallery-quickstart__(7)
72
71The ldgallery source code is available on <https://ldgallery.pacien.org>. 73The ldgallery source code is available on <https://ldgallery.pacien.org>.
72 74
75
76# LICENSE
77
73Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET. 78Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET.
74 79
75This 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. 80This 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.