Html2Slideshow (GTK2/Linux)

Howto

For an explanation of what Html2Slideshow is, please read the text of the Html2Slideshow-Homepage on http://www.uplawski.de/html2slideshow/html2slideshow_en.html.
(German version: http://www.uplawski.de/html2slideshow/).

In the document, you are currently reading, I describe, how the graphical Ruby/GTK2-surface for the Html2Slideshow-program is used. Orange-shaded thumbnails in the text below, are links to larger versions of screenshots.
If you want to use Html2Slideshow on the command-line of a Unix-shell or in the Windows-command-interpreter (DOS), instead, the argument -h or --help will print the following usage-information:

The GUI in general

You need the Ruby-Gnome2 bindings (download from Sourceforge). Without them, you will not be able to use HTML2Slideshow over the graphical user interface and have to stick with the command-line.

If you are tied to Windows™ you depend on the command-line, anyway. But believe me, that is not a bad choice and you do not need to know more than those options, above.

The generator and its GUI exist, thus, well separately from each other to allow different uses of the program. While html2slideshow.rb is the main Ruby-script, that can be used on the command-line, html2slideshowGui.rb contains the definition of the GTK-dialog, explained below.

You may know already how to start a Ruby-application, but just for completeness, do it like this:

$>ruby html2slideshowGui.rb

Some options are only accessible from the GUI:

• In the GUI, you can choose different file-formats to include in your slideshows, while the console-program will only integrate JPEGs.
• Your slide shows may offer two additional vertical sizes for the display of images. While the console program will set these two values to fixed 500 and 300 pixels, you can enter your preferred numbers in the GUI.
• The console-program logs protocol-messages to the screen, if an argument -d or --debug was given. You can redirect this output into a file of your choice. In the GUI-version, the log-file can be specified as an option and the first log-messages will be created only after such a file had been named.

These mentioned features are explained further below.

The user-interface consists of a selection of tab-cards, but for the most general task of creating slideshow-files from original (X)HTML-sources, the first tab, labelled General Options offers all the functionality you need.

General Options

in French

in German

Language-setting

I have included an easy way to adapt the GUI to languages other than English. The current release contains reliable translations to German and French. I will explain first, how you enable these two language-versions, then how you can enable the program to use additional languages.

Switching languages

Usually, you want the messages, captions and other text which appears on the surface, to be written in the language, that your operating system is already configured to use. Unfortunately, this setting is found at different places, depending on your current operating system. Under Linux Html2Slideshow is able to find the system-wide setting in the environment-variable LANG and will use it by default. So, if you are using Linux and want the program to speak to you in either German or French, no changes should be necessary.

Should you want to actively change the language of Html2Slideshow and know, that the program supports the new language, there is yet another, easy way to enforce that change. Go to the folder, where Html2Slideshow resides and create a new text-file LANG (without file-extension), if it does not accidentally exist already. The contents of the file is one single line with the two-letter country-code for the new setting. Initially, apart from 'en', only 'fr' or 'de' make sense. But you are free to write the code in capital letters, too.

Adding languages

All translations reside in one text-file, that you find in the program-folder. The file is named "translations". Here is an examplary section of its contents.

Success:

de: Erledigt

fr: Finis

XX Options:

de: XX Optionen

fr: Options XX

current log-file shall be XX:

de: Aktuelles Logfile XX

fr: Fichier log sera XX

Image types:

de: Bildformate

fr: Formats graphiques

selected types are XX:

de: ausgewählte Formate sind XX

fr: Formats choisis sont XX

Each block starts with the English version of a text to display, followed by a colon. Each translation of this text starts in a new line and is prepended with the two-letter country-code and a colon.

XX is a wildcard, which allows a text to be parameterized by the program. The position of this wildcard may vary in a translation but it should stay intact.

When you add your own translation or modify the existing text, please keep it free of special characters, especially colons (other than those at the end of the english original or the language-codes), because these control the program-behavior and your text would be clipped at their position.

Special characters in the translation

Lower down in the translations-file, you find two sections which need further explanation.

The first contains text, which will be dynamically set or changed on the generated slideshow-pages. The JavaScript-routines behind this functionality cannot handle any special characters, like e.g. French accents (like in é). Instead, in this section, the escape-sequence of each such character must be used. The JavaScript-function unescape() will see to making them palatable to the browser.

The very last paragraph in the file contains static text for display on the slideshow-pages. The special characters there need to be masked as the typical named entities in HTML-syntax, like é for é.

When you are done and have added a new language-code and translation to all text-blocks in the file, do not forget to change the file LANG in the program directory, if you are using Windows or if the language is not pre-set in the environment-variable LANG.

Keyboard accelerators

Push-, check- and radiobutons in Html2Slideshow can be activated by the keyboard shortcut, indicated by an underlined character. To allow the translation of those button-labels, that contain such a shortcut, they must be honored in the upper section of the translations-file. You will thus find that some text-lines contain an underscore-character _. The accelerator is the next one, following this underscore. The translation of the english label _Back is thus _Retour in French, which automatically replaces the shortcut Alt+B by Alt+R. Please note, that the accelerator does not have to be the first character in a label.

General options

When you start the program, this is what you see, at first:

I will now explain each element from top left to bottom right:

Source-directory

This will be a folder (directory) on your hard-disk, where either image-files or (X)HTML-source files are located. You may type the full path to this directory in the text-field or choose a path from the file-system, after you clicked on the button to the right of it.

with sub-directories

(Click on the image to see a checkbox)
When this option is visible, you can check it in order to include sub-directories in the search for image-files. This means also, that currently, the images for the slide show will not be collected from the HTML-source of a web-page, but file-names on your hard-disk.
You can change that in the generator options (see below), and the checkbox together with its label will then disappear again.

Button

This button opens a file-dialog. You can specify the folder from the file-system, where either the images for your slideshow or the HTML source-files, referencing those images, will later be found.

Slideshow-Directory

Initially, this text field is disabled and cannot be altered. Only after you have either entered a source folder or chose one from the file-dialog, you can specify a sub-directory where you want the resulting slideshow-files be saved. A default folder slideshow is entered automatically, but can be modified. The field can even be cleared, in case that you want the source-folder to contain the slideshow-files, as well. Otherwise, the sub-folder will be created, if it does not already exist, when you click the Start-button (see below).
The main dialog after the source-folder has been entered (here, manually via the keyboard):

Button Start

Click this button any time, to create a new set of slideshow-files from the HTML-files in the source-folder.
Provided, that all works well, that there have really been either readable HTML-files or images in that folder and the target-folder could be created and/or written to, you will be informed by HTML2Slideshow.

Should something go wrong, likewise, the message will be a different one

Button Quit

Does, what it sais. With the Quit-button you exit the program and save the current configuration in a file html2slideshow.cfg, so that your current settings can be restored in the next session.

Button About

This button displays the copyright-information and links to the Html2Slideshow-homepage and a version of the GNU-GPL

Generator options

In this tab, you can further control the program behavior to some extent. For the time being, three option sets are available, others may follow, should I find time and enthusiasm:

Image-source

By default, the program will use all the image-files of suitable format, which it finds inside the source-folder. But you can select the second option to make it read the path to those images from HTML-files, instead. A HTML-file may reference an image like this:
<a href="/sub_folder/my_photo.jpg"><img src="thumb.jpg"/></a>
Html2Slideshow will only use the URL to the linked file and ignores, if there is an additional thumbnail shown on the page.
In the title-field, you can give the resulting slide show a name, either, when you collect the images from a directory (and its sub-directories) or, when you consolidate the linked pictures from several HTML-files. You can leave it empty to have the slide-show named like the source-directory. Where you let the program create 1 individual slide show per original HTML-source, the <title/>-tag from each HTML-file is just copied and in consequence, this input-field is then not even displayed.

Image types

Choosing image-types, you can create slideshows from PNG, GIF, JNG or JPEG2000 image-files. By clicking the respective check-box, you configure Html2Sliedshow to look for a selection of file-extensions, e.g. *.jpg, *.jpeg, *.JPG, *.JPEG in case of jpg, which is also the default.

Debug-log

The debug-option is used to write log-messages to a file for later consultation. As a default, a file html2slideshow.log in the current user's home-folder is used, but you can name a different file, after you activate the option by a click on the checkbox. The file will be created, if it does not exist and additional contents is appended, otherwise. As long as the checkbox is not activated, though, no log will be written. Be careful to choose a file, that is not needed for other purposes and none that would be destroyed, when text is added to its end!

Slide show options

The options, which you find in this tab card, influence the appearance and function of the generated slide shows, rather than that of the generator.

In version 0.6, the card appears for the first time, and offers still only one option set.

Height of the image at display

In each of the two input fields, named large and small, you should enter a number, indicating an alternative vertical display-size in pixels for the images in the running slide shows. On the generated HTML-page, three small buttons serve to switch between the original, the alternative large and the small size.
Should you omit this setting, defaults apply (500 and 300). Please take into account, that your image-files will never be modified by HTML2Slideshow. The scaling-function will just change the height-attribute, and the option does not have any influence on the loading speed.

Howto

To open the HTML-page, which you are currently reading, offline in a web-browser of your choice, you can click the Howto-card.

Web-Browser

You are asked for the command, which opens the browser. Either choose the executable browser-file from the file-system, type the path to the executable or, if the latter is already in the path for executable files on your system, just the name of the browser:

Afterwards, Accept will either open the page in your browser or a failure-message is displayed. In that case, close the message-dialog and alter the browser-command.

Example

I am using my own site at http://www.uplawski.de/Provence as an example. The idea for my first C++-version of Html2Slideshow did also arise during the creation of those pages.

The local directory with all the inside pages, at first looks like in the screenshot to the right.

What I want, is a slideshow-file for each of those html-files, should they contain references to photos. Html2Slideshow will create those files and spares me the trouble to copy JavaScript and CSS-code in the process.

First, I make sure, that the options for my slide show project are correctly set, in the options:

In the general options, I enter the path to the source-folder:

Because I want to use the photos referenced in the HTML-source of my web-pages, I have to choose the option "Image-source: files linked in HTML", as explained above.

Next, I just click the Start-button and a moment later, all is done. You can, though, use the options-tab to alter the program-behavior, prior triggering the generator.

To the right, you see part of the result, as the new sub-folder slideshow has been added below .../Provence/pages.

Inside that folder, I find the new slideshow-files along with the CSS- and JavaScript-files, that they will use:

Ω