| Copyright © 2011 , Kurt Nørmark | |
This is the reference manual of the LAML Photo Show tool. This tool allows you to create a set of HTML files embedded in a directory with photos (jpg files). The HTML files that surround the images provides for smooth navigation, and it provides nice overviews of your pictures, all made by HTML files which can be shown in any Internet browser. Some help to photo management is also provided. This tool is based on XML-in-LAML.
A few features of this tool depend on MzScheme. Some of the more advanced features depend on ImageMagick. In order (in order to make the MzScheme system procedure available) to initiate ImageMatick from MzScheme put (require (lib "process.ss")) into your .laml file.
Seen from the context of LAML, the LAML Photo Show facility serves as a simple example of my personal use of LAML within the area of batch photo management.
| lower-caption | Defines the default lower caption of a photo page. |
| photo | Defines the characteristics of each presented photo in the show. |
| photo-list | The list of photos in the show. |
| photo-show | The top level element which holds a number of attributes that affect the photo show of all pictures in a film. |
| photos-in-current-directory | Automatically forms a photo list of the photos in the current directory. |
| title-of-show | Determines the title (caption) of the current film |
| upper-caption | Defines the default upper caption of a photo page. |
   1 Organization of photos | |||
A LAML photo show is a directory of films. Each film is a directory itself. Films cannot be nested into each other; Thus the films obey a flat organization within the top-level photo show directory. There may, however, be subdirs of the photo show directory with other photo shows directories (recursive orgnization). As of now, no linking is provided to these. The directory corresponding to a film contains a flat list of jpg files, with arbitrary names. To use the LAML photo show generator you should put a LAML file side-by-side with the photos, which describes the properties of the photo show, as related to the current film. This reference manual documents how this LAML is made. To make things easy, use the Emacs command M-x make-laml-photo-show (found in 'Tools>LAML>Make new photo show...') for this. Thus, the typical directory and file organization is like the following: process-all-films.laml index.html Film1 1.jpg 2.jpg 3.jpg make-show.laml index.html html 1.html ... internal film-description-entry.lsp photo-ast.lsp photo-list Film2 1.jpg 2.jpg 3.jpg index.html make-show.laml html 1.html ... internal film-description-entry.lsp photo-ast.lsp photo-list Film3 4.jpg 5.jpg 6.jpg index.html make-show.laml html 1.html ... internal film-description-entry.lsp photo-ast.lsp photo-list You are supposed to make to top level directory and the film directories. The directory names are arbitrary. The jpg files are created by the software that transfers photos from your digital camera. You write the make-show.laml files with your text editor - Emacs, for instance. The name of this file is arbitrary, but you should use the laml extension. The LAML photo show generator makes the remaining files and directories. Notice the file process-all-films.laml in the root which, when processed, regenerates the photo shows for all (already once processed) films; This laml file is made automatically the first to you process one of the films. If you delete it a new process-all-films.laml will appear the next time you have processed a film. You can use the LAML photo show generator to make collections of photos from different directories, without copying any photo. To do so, make a film directory without jpg files, and address individual photos in arbitrary films from there. LAML makes it easy to do so, because you can copy the necessary photo clauses from your browser into the text editor. The names of the photos are linked to the appropriate photo clauses. If some existing film is not supposed to make it into the index, place a file named 'exclude' side by side with the jpg files. | |||
 2 The Top Level | |||
| In this section we document the top level photo-show element, and not least its numerous attributes. | |||
| photo-show | |||
| Description | The top level element which holds a number of attributes that affect the photo show of all pictures in a film. As constituents there is either a list of photo entries, or a directive to automatically collect the photos in the current directory. | ||
| XML content model | ( title-of-show , upper-caption , lower-caption , ( photo-list | photos-in-current-directory ) ) | ||
| XML attributes Required: * Default values: red | time * | CDATA | The time in second each picture is show in automatically progressing shows. This is a default value, which can be overwritten for each photo. |
| background-color | CDATA | The background color of photo pages. As an example "#000000" represent black, like in HTML. The LAML function rgb-color-encoding is useful to give colors. | |
| text-color | CDATA | The color of the text in photo pages. As an example "#ffffff" represent white, like in HTML. The LAML function rgb-color-encoding is useful to give colors. | |
| home-path | CDATA | The path to the directory with all the film. Should always be "../" with the current and flat organization of the films. | |
| previous-film | CDATA | The to path of the previous film. The path is relative from the current directory. The path must have a trailing '/'. Example "../Film1/". | |
| next-film | CDATA | The path to the next film. The path is relative from the current directory. The path must have a trailing '/'. Example "../Film2/". | |
| before-first | ( last-picture | previous-film | none ) | Determines what comes before the first photo in the film. last-picture means 'cyclic show'. previous-film means that a link is made to the last picture in previous-film. none means that there is nothing before the first picture. | |
| after-last | ( first-picture | next-film | stop-page | none ) | Determins what comes after the last photo in the film. first-picture means 'cyclic show'. next-film means that a link is made to the first picture of the next-film. stop-page means that the photo show ends with a stop page. none means that thre is is nothing after the last picture. | |
| transition | ( blend | none ) | The browser transition used when shifting from photo to phote during automatically progressing shows. Notice that blend only works in Internet Explorer from Microsoft. | |
| verbosity-level | CDATA ( 2 ) | A number between 0 and 2 which controls the amount of messages given by the tool. 0 is minial and 2 is maximal. | |
| language | ( danish | english ) | The language of the fixed text generated by the tool | |
| html-mode | ( raw | pp ) | The formatting of the HTML pages generated by the tool. pp means pretty printed, and it takes appr. the double amount of disk space than raw. If you never read the HTML files - and why should you - you can use raw. | |
| index-linking | ( run | stop ) | Determines the kind of linking used from a film page to the photos. run means that the links go to automatically progressing pages. stop means that the links go to pages without automatically progress. | |
| default-size | ( original | auto | explicit ) | Determines the size of the photos, as presented by the tool. original means that the photos are presented directly, without enlarging or reducing them. auto means that the photos are enlarged or reduced to make them fit with the real estate of the browser. explicit means that we should use the witdh and height are given for each photo. | |
| default-orientation | ( portrait | landscape ) | Controls the automatically enlarging or reduction, when auto is used for default-size. | |
| portrait-percentage | CDATA ( 90 ) | An image size percentage, used to affect the height of the photo. Only used for default-size auto and default-orientation portrait. An integer between 0 and 100. | |
| landscape-percentage | CDATA ( 95 ) | An image size percentage, used to affect the width of the photo. Only used for default-size auto and default-orientation landscape. An integer between 0 and 100. | |
| photo-displacement-left | CDATA ( 0 ) | A number of pixels that act as left margin of the picture. Used for horizontal displacement of the picture. Typically used to compensate for invisible scroll bar. An integer number. | |
| photo-displacement-right | CDATA ( 0 ) | A number of pixels that act as right margin of the picture. Used for horizontal displacement of the picture. An integer number. | |
| tabular-overview-dimension | CDATA ( 3 ) | An integer such as 1, 2, 3 or 4 which determines the tabular layout of the overview pages. If, for instance, 3 is given, 9 photos are shown on each overview page. | |
| photo-tabular-window-width | CDATA ( 870 ) | The width of the photo table window (pixels). Used to determine width of n x n landscape photos in an overview overview. | |
| photo-tabular-window-height | CDATA ( 740 ) | The height of the photo table window (pixels). Used to determine height of n x n landscape photos in an overview overview. | |
| copy-film | ( true | false ) | A boolean attribute that controls if the photos (the jpg files) are copied to the copy-destination directories. Useful for photo management. | |
| copy-destination | CDATA | An absolute path on the your computer which defines the target directory of photo copying. Only relevant if copy-film is true. | |
| shave-resize-and-copy | ( true | false ) | A boolean attribute that controls shaving, resizing and copying via ImageMagic. If true, first a number of pixes is shaved both at top, bottom, left, and right side. At both top and bottom shave-height pixels are removed. At both left and right side shave-width pixels are removed. Next, the photos are reshaped to resize-width x resize-height pixels. The aspect rative is not preserved. The shaved and resized pictures are copyied to the copy-destination directory. | |
| shave-width | CDATA ( 0 ) | The number of pixels to shave both at the left and right side. Does only apply if shave-resize-and-copy is true, and if copy-destination is provided. | |
| shave-height | CDATA ( 0 ) | The number of pixels to shave both at the the top and the bottom. Does only apply if shave-resize-and-copy is true, and if copy-destination is provided. | |
| resize-width | CDATA ( 0 ) | The exact width of the resize picture. Does only apply if shave-resize-and-copy is true, and if copy-destination is provided. | |
| resize-height | CDATA ( 0 ) | The exact height of the resize picture. Does only apply if shave-resize-and-copy is true, and if copy-destination is provided. | |
| camera | CDATA ( Canon-G3 ) | The name of the camera. Intended for (future) special handling of camera specific features, such as automatic rotation of pictures. | |
| image-transformation-software | ( image-magick | none ) | The kind of image transformation software interfaced to from the LAML Photoshow software. Currently we make use of ImageMagick for creation of thumbnails. If the value image-magick is used, you are supposed to have an installation of ImageMagick on your machine. See http://www.imagemagick.org/. In order for this software to be able to activate ImageMagick, the system function must be supported by your Scheme system. In PLT MzScheme the system function is supported if you use the process.ss library. For instance, put (require (lib "process.ss")) in your .laml file. | |
| make-thumbnails-of | ( all | non-existing | none ) | Controls the generation of thumbnail photos. These are small pictures that act as visual indexes. The value all means that all thumbnail photos are regenerated. The value non-existing means that only non-existing thumbnails photos are generated. The value none means that no thumbnails are generated at all. | |
| time-stamp | ( auto | from-file-system | from-jpg-file | none ) | How to access the time stamp of a photo file. from-file-system: Take it from the file's time stamp, as provided by the oprating system. from-jpg-file: Take it from the initial part of the JPG file. auto: Take it from the jpg file (if there), else take it from the file. none: Do not access the time stamp. | |
| time-stamp-presentation | ( date | weekday-date | time | date-time | weekday-date-time | none ) | How to present the accessed time stamp of a photo file. | |
| rotate | CDATA | A white-space separated sequence of rotation descriptions. A single rotation description looks like photo-file.ext:n, where n is the number of degrees to rotatethe phote. Example: "123.jpg:90" Typically used to rotate photos 90 degrees from landscape to portrait mode. | |
| title-of-show | |||
| Description | Determines the title (caption) of the current film | ||
| XML content model | (#PCDATA) | ||
| See also | enclosing element | photo-show | |
| upper-caption | |||
| Description | Defines the default upper caption of a photo page. Can be overruled by each photo element. | ||
| XML content model | (#PCDATA) | ||
| XML attributes Required: * Default values: red | size | CDATA | The size of the upper caption. A number between 1 and 6. |
| See also | enclosing elements | photo-show photo | |
| lower-caption | |||
| Description | Defines the default lower caption of a photo page. Can be overruled by each photo element. | ||
| XML content model | (#PCDATA) | ||
| XML attributes Required: * Default values: red | size | CDATA | The size of the lower caption. A number between 1 and 6. |
| See also | enclosing elements | photo-show photo | |
| photos-in-current-directory | |||
| Description | Automatically forms a photo list of the photos in the current directory. This clause can be given instead of a photo list. It means that the tool automatically makes a photo list of all the jpg files in the current directory. The sorting is done in a smart way, by taking the numeric part of the file names into account. Default properties are assigned to the photos. As an important practical observation, the tool will make a file photo-list in the internal directory, with a photo list. You can replace the (photos-in-current-directory) clause with this list, and thereby control the show in a much better way. | ||
| XML content model | EMPTY | ||
| See also | enclosing element | photo-show | |
| photo-list | |||
| Description | The list of photos in the show. Notice that the order of the photo elements in the photo-list controls the ordering of the photos in the show. | ||
| XML content model | ( photo * ) | ||
| See also | enclosing element | photo-show | |
| 3 The photo element | |||
| In this section we document the photo element, which can be used to describe each photo in the show. | |||
| photo | |||
| Description | Defines the characteristics of each presented photo in the show. Some of the attributes overrules the default attributes given in the photo-show element. | ||
| XML content model | ( upper-caption ? , lower-caption ? ) | ||
| XML attributes Required: * Default values: red | file * | CDATA | The name of a photo file, either from the current directory (current film) or from another directory (another film). In the latter case, the path attribute must address the other film. The name consist of the proper name and the file extension (jpg). For instance "1.jpg". |
| path | CDATA ( ) | The path of the photo file, as given by the file attribute. The path is relative to the current directory. It must end with a '/'. Example: "../Film3/", where .. means the parent directory. | |
| time | CDATA | The time in second this photo is show in automatically progressing shows. Overrules the time in the enclosing photo-show element. | |
| transition | ( blend | none ) | The browser transition used when shifting from this photo to the next. Notice that blend only works in Internet Explorer from Microsoft. Overrules the transition in photo-element. | |
| size | ( original | auto | explicit ) | Determines the size of this photo, as presented by the tool. original means that the photo is presented directly, without enlarging or reducing it. auto means that the photo is enlarged or reduced to make it fit with the real estate of the browser. explicit means that we should use the width and height attribute of this photo. Overrules the default value given in the enclosing photo-element. | |
| orientation | ( portrait | landscape ) | Controls the automatically enlarging or reduction, when auto is used as size for this photo. | |
| width | CDATA | The width to be used for this photo. Use the value explicit for size if you give the width. Normally you will not want to give both width and height. | |
| height | CDATA | The height to be used for this photo. Use the value explicit for size if you give the height. Normally you will not want to give both width and height. | |
| See also | enclosing element | photo-list | |
 4 Examples | |||
In this section we show examples of LAML files. The first file is similar to the file produced by the Emacs command M-x M-x make-laml-photo-show: (load (string-append laml-dir "laml.scm")) (laml-style "xml-in-laml/photo-show/photo-show") (define photo-show-title "Example") (photo-show 'language "danish" ; danish or english 'time "3" 'background-color (rgb-color-encoding black) ; color string, like "#123456" 'text-color (rgb-color-encoding white) ; color string, like "#123456" 'home-path "../" 'transition "none" ; none or blend 'tabular-overview-dimension "3" 'previous-film "../Film1/" 'before-first "previous-film" ; last-picture, previous-film, none 'next-film "../Film3/" 'after-last "next-film" ; first-picture, next-film, stop-page, none 'index-linking "stop" ; run or stop 'default-size "auto" ; original, auto, explicit 'default-orientation "landscape" ; portrait or landscape 'verbosity-level "2" ; 0, 1, 2 (title-of-show photo-show-title) (upper-caption 'size "6" photo-show-title) (lower-caption 'size "4" "") (photos-in-current-directory) ) The purpose of the next laml file is to enumerate 'the best photos' in a large collection of films and photos: (load (string-append laml-dir "laml.scm"))
(lib-load "xml-in-laml/xml-in-laml.scm")
(laml-style "xml-in-laml/photo-show/photo-show")
(photo-show
'time "8"
'language "english"
'transition "blend"
'html-mode "pp"
'home-path "../"
'tabular-overview-dimension "3"
'before-first "none"
'after-last "stop-page"
(title-of-show "My Best Photos")
(upper-caption 'size "6" "")
(lower-caption 'size "3" "")
(photo-list
(photo 'time "3" 'path "../Film34/" 'file "109_0957.JPG" 'size "auto" (upper-caption 'size "6" "") )
(photo 'time "3" 'path "../Film34/" 'file "109_0960.JPG" 'size "auto" (upper-caption 'size "6" "") )
(photo 'time "3" 'path "../Film34/" 'file "109_0968.JPG" 'size "auto" (upper-caption 'size "6" "") )
(photo 'time "3" 'path "../Film34/" 'file "109_0974.JPG" 'size "auto" (upper-caption 'size "6" "") )
(photo 'time "3" 'path "../Film34/" 'file "109_0975.JPG" 'size "auto" (upper-caption 'size "6" "") )
(photo 'time "3" 'path "../Film32/" 'file "109_0915.JPG" 'size "auto" (upper-caption 'size "6" "") )
)
)
| |||
| Mirror name: | laml-photo |
| Automatic loading of common XML-in-LAML library? | No |
| List of action elements | (photo-show) |
| Generation of named mirror functions: | Yes |
| Mirror name prefix: | None |
| Transliteration of CDATA? | Yes |
| List of elements for which transliteration does not apply: | '() |
| List of elements for which all white spacing is preserved: | '() |
| Name of HTML character transformation table: | html-char-transformation-table |
| Are default DTD attributes passed explicitly? | No |
| Are attributes only allowed to be text strings? | Yes |
| Is extended textual contents allowed? | No |
| Is white space represented by this mirror? | Yes |
| How are duplicated XML attributes handled: | 'keep-all |