source: project/release/3/sigma/trunk/sigma-eggdoc.scm @ 12413

Last change on this file since 12413 was 12413, checked in by Ivan Raikov, 12 years ago

Updated for version 1.15.

File size: 9.2 KB
Line 
1;;
2;;
3;; sigma documentation for the Chicken Scheme module system.
4;;
5;;
6;; Version $Revision$
7;;
8;;
9;;
10;; This program is free software: you can redistribute it and/or
11;; modify it under the terms of the GNU General Public License as
12;; published by the Free Software Foundation, either version 3 of the
13;; License, or (at your option) any later version.
14;;
15;; This program is distributed in the hope that it will be useful, but
16;; WITHOUT ANY WARRANTY; without even the implied warranty of
17;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18;; General Public License for more details.
19;;
20;; A full copy of the GPL license can be found at
21;; <http://www.gnu.org/licenses/>.
22;;
23;;
24
25
26(use eggdoc)
27
28(define doc
29  `((eggdoc:begin
30
31     (name "sigma")
32
33     (description "Image gallery generator.")
34
35     (author (url "http://chicken.wiki.br/ivan raikov" "Ivan Raikov"))
36
37     (history
38      (version "1.15" "Added some error checking for temporary directory creation")
39      (version "1.14" "Another bug fix in directory path escaping")
40      (version "1.12" "Bug fix in directory path escaping")
41      (version "1.11" "Bug fix to prevent recursive descent into target album dir")
42      (version "1.10" "Eliminated use of fmt-num")
43      (version "1.9" "Bug fix in image-size")
44      (version "1.8" "Bug fix in use of fmt library")
45      (version "1.7" "Added support for CD image generation")
46      (version "1.6" "Bug fix in the highlights index generation")
47      (version "1.5" "Documentation updates")
48      (version "1.4" "Added support for highlights functionality")
49      (version "1.3" "Bug fix in image directory reading")
50      (version "1.2" "Added commands interface")
51      (version "1.1" "Bug fix in the meta file; ability to specify captions for subfolders")
52      (version "1.0" "Initial release"))
53
54     (requires (url "args.html" "args")
55               (url "sxml-transforms.html" "sxml-transforms")
56               (url "doctype.html" "doctype")
57               (url "utf8.html" "utf8")
58               (url "uri.html" "uri")
59               (url "fmt.html" "fmt"))
60
61     (usage "sigma [options...] [commands...]")
62     (download "sigma.egg")
63
64      (documentation
65
66       (p (tt "sigma") " is a simple program for creating a Web gallery
67 of images with a single command. It is based on the igal program by
68 Eric Pop and generates a set of HTML 4.0+CSS-compliant static slides.
69 The appearance of the image gallery can be altered by modifying the
70 default CSS file, as well as the slide template and index page
71 template files that appear in the image directory. Unlike igal, the
72 templates are written as S-expressions, and follow the conventions of
73 SXML.")
74
75       (p (tt "sigma") " also checks for the existence of a $HOME/.sigma
76 directory where users can store their own templates, overriding the
77 site-wide /usr/share/sigma. ")
78
79
80      (p (tt "sigma") " relies on the ImageMagick package, and if
81sorting by image date is desired, it can use the " (tt "exif") "
82program to extract EXIF date information from JPEG files.  The " (tt "convert") 
83" command from the ImageMagick package is required to process image
84files and the " (tt "identify") " command enables " (tt "sigma") " to
85include size information in the HTML it generates and to determine
86whether large images need to be rescaled. ")
87
88      (p "If the -c option is used, " (tt "sigma") " creates a " (tt ".captions")
89" file, which contains captions to be inserted under each slide. "
90"The captions must be in S-expression format and may include SXML tags. "
91"Each caption entry can be in one of two forms: "
92(ol 
93 (li (tt "(fname caption [option1 option2 ...])")
94     (p "The first element is the image file name, and the second element is the caption. "
95        "The file name and the caption are required. They can be followed by any number of "
96        "options keywords. The only option keyword currently recognized is " (tt "hl") 
97        ", which  indicates that the slide should be included on the optional highlights page. "))
98 (li  (tt "(subdir name caption) ")
99      (p "Entries of this form  be used to specify captions for subfolders. ")))
100
101"To add any comments to this file or to exclude any images from the slide "
102"show, add a semicolon the beginning of their respective lines. "
103"You may also change the order of images in your slide show at this time. ")
104
105      (subsection "Commands"
106          (p
107           (symbol-table
108            (describe "gallery"   "Create an image gallery (default if no command given)")
109            (describe "thumbs"    "Create image thumbnails (implicit when gallery is also given)")
110            (describe "sort"      "Sort images by EXIF date or file creation date")
111            (describe "cdimage"   "Create a CD image containing the image slides")
112            (describe "clean"     "Clean generated files"))))
113
114      (subsection "Options"
115          (p
116               (symbol-table
117                (describe "-a"                 "write image sizes under thumbnails on index page")
118                (describe "-c"                 "first generate and then use captions")
119                (describe "-C"                 "like -c, but preserve file names as captions")
120                (describe "-d DIR"             "operate on files in directory DIR (default: .)")
121                (describe "-f"                 "force thumbnail regeneration and scaled slides")
122                (describe "-g TITLE"           "gallery title (default: Default Gallery Title)")
123                (describe "-k"                 "use the image captions for the HTML slide titles")
124                (describe "-R"                 "recursively descend subdirectories")
125                (describe "-t DIR"             ("place gallery files in directory DIR "
126                                                "(will be created if it doesn't exist)"))
127                (describe "-u"                 "write captions under thumbnails on index page")
128                (describe "-U"                 "write slide names under thumbnails on index page")
129                (describe "-x"                 "omit the image count from the captions")
130                (describe "-y N"               "scale all thumbnails to the same height  (default: 75)")
131                (describe "--ad"               "like -a, but write only the image dimensions")
132                (describe "--as"               "like -a, but write only the file size (in kbytes)")
133                (describe "--author=AUTHOR"    "specify author name (default: $USER)")
134                (describe "--con=OPTS"         ("options to pass to " (tt "convert")))
135                (describe "--cd-dir=DIR"       "directory for CD image output (default: $HOME/tmp)")
136                (describe "--cd-file=DIR"      "name of CD image file if --gcd is not specified (default: Photos)")
137                (describe "--gcd=TITLE"        "like -g, but also sets CD image file name")
138                (describe "--hls"              "creates a highlights page")
139                (describe "--hls-main"         "creates a highlights page as the main page")
140                (describe "--html-ext=SUFFIX"  "suffix of output HTML files (default: html)")
141                (describe "--html-index=NAME"  "name (without suffix) of the main thumbnail index file (default: index)")
142                (describe "--html-hindex=NAME" "name (without suffix) of the highlights index file (default: hindex)")
143                (describe "--in"               "use image file names for the HTML slide files")
144                (describe "--top"              "create index pages for directories that only contain subfolders")
145                (describe "--tp=PREFIX"        "sets the thumbnail image prefix (default: .thumb_)")
146                (describe "--sp=PREFIX"        "sets the slide image prefix (default: .slide_)")
147                (describe "--up"               "create Up links even in top-level image galleries")
148                (describe "--verbose=LEVEL"    "set verbose mode (0: quiet; 1: info; 2: debug)")
149                (describe "--www"              "makes all SIGMA files world-readable")
150                (describe "--xy=N"             "scale thumbnails to N pixels in their longer dimension")
151                (describe "--yslide=N"         "scale slides to the given maximum height")
152                (describe "-h, --help"         "print help"))))
153
154       (subsection "Files"
155               (symbol-table
156                (describe "/usr/share/sigma/index-template.scm"
157                          "The default index template file.")
158                (describe "/usr/share/sigma/slide-template.scm"
159                          "The default slide template file.")
160                (describe "/usr/share/sigma/sigma.css"
161                          "The default style sheet."))
162
163               (p (tt "sigma") " also checks for the existence of a "
164 (tt "$HOME/.sigma") " directory where the user can store their own
165 templates, overriding the site-wide " (tt "/usr/share/sigma") ". ")))
166
167     (examples (pre #<<EOF
168
169  ## Creates an image gallery using the image files 
170  ## found in the current directory and its subdirectories;
171  ## uses directory album to write the HTML files and slides;
172  ## writes image sizes and captions under the thumbnails on the index pages;
173  ## creates and reads .captions file; resizes the slide images to a maximum
174  ## height of 500 pixels
175
176  sigma -a -c -u -R --yslide=500 -t album 
177
178
179EOF
180))
181
182     (license
183      "Copyright 2007-2008 Ivan Raikov.
184
185Based on the igal program by Eric Pop. 
186ISO 9660 image creation code based on code by Walter C. Pelissero.
187
188This program is free software: you can redistribute it and/or modify
189it under the terms of the GNU General Public License as published by
190the Free Software Foundation, either version 3 of the License, or (at
191your option) any later version.
192
193This program is distributed in the hope that it will be useful, but
194WITHOUT ANY WARRANTY; without even the implied warranty of
195MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
196General Public License for more details.
197
198A full copy of the GPL license can be found at
199<http://www.gnu.org/licenses/>."))))
200
201(if (eggdoc->html doc) (void))
Note: See TracBrowser for help on using the repository browser.