Html2Slideshow

Howto

For an explanation of what Html2Slideshow is, please read the text of the Html2Slideshow-Homepage on http://www.uplawski.de/html2slideshow.html. However, the referenced page is only available in German, at the time of this writing (end of March 2009).

In the document, you are currently reading, I describe, how the graphical Shoes-surface for the Html2Slideshow-program is used. If you want to use Html2Slideshow on the command-line of a Unix-shell or in a DOS-window, instead, the argument -h or --help will print the following usage-information:

Usage: ruby html2slideshow.rb [options]
        or html2slideshow [options]

Specific options:
    -d, --debug [true|FALSE]         Switch on debug-mode. Will generate log-messages during processing
    -s, --source SOURCE DIR          Read HTML source-files from this directory
    -t, --target [TARGET DIR]        Write slideshow-files to this sub-directory
                                       (if not provided, SOURCE DIR is used)

Common options:
    -h, --help                       Show this message
        --version                    Show version

↑The GUI in general

You need Shoes. Without Shoes, you will not be able to use HTML2Slideshow over the graphical user interface and have to stick with the command-line. Get the graphics toolkit and all the background-information you may need, from the Shooes-homepage: http://shoooes.net/

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, html2slideshowDialog.rb contains the definition of the Shoes-dialog, explained below.

I believe, that you know already how to start a Shoes-application, but just for completeness, do it like this:

So far, two options are not accessible to the console-program:

• The command-line version uses a hard-coded list of JPEG-extensions: *.jpg, *.jpeg and *.jp2. Thus, your slideshow can only contain JPEGs or Jpeg2000-files, respectively. In the GUI, you can choose some more file-formats to include in your slideshows.
• The log-file, too, is hardcoded as [path to the html2slideshow-folder]/html2slideshow.log, while, in the GUI, you may name any other file, to log messages to.

Both features are explained further below.

The user-interface consists of a few different dialogs, but for the most general task of creating slideshow-files from original (X)HTML-sources, the first or main dialog offers all the functionality you need.

↑The main dialog

When you start the program, this green dialog is what you see, at first.

The simplicity of the Shoes toolkit results in some small inconveniences, but they are almost entirely restricted to the appearance of the surface. In the screenshot above, you notice a less than optimal alignment of the GUI-elements (and there is more to come...). This does anyway not impair the functionality of the program.

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

HTML-Source

This will be a folder (directory) on your hard-disk, where (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 small button to the right of it.

Button

This button opens a file-dialog. You can specify the folder from the file-system, where the HTML source-files will later be read.

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):
Should the line in the middle of the dialog become too long, it will simply wrap. Maybe try that out, before the surprise makes you assume a program-error. :-D

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 readable HTML-files in that folder and the target-folder could be created and/or written to, you will be informed by HTML2Slideshow:

That is quite a huge window for my frugal artwork and the word Done, but the same dialog is used on other occasions and I have not yet found out, how the dimension of such a window can be swiftly adapted to its current use. Let us ignore that for now, okay? Thank you. ;-)
Should something go wrong, likewise, the message will be a different one:

Please use the Back-button to return to the main-window. Do not try to close the window by use of the x-button in the window-frame. Because I need to avoid several dialogs being open at the same time, the triggering buttons will always stay disabled as long as a dialog is opened. Shoes does not allow me another way to keep track of open dialogs, should you not use the Back button. Otherwise, the program needs to be restarted, to activate all buttons again.

Button Options

This button opens yet another dialog, where you can further control the program behavior to some extent. For the time being, only two option sets are available, others may follow, should I find time and enthusiasm:
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 in the HTML-sources, e.g. *.jpg, *.jpeg, *.JPG, *.JPEG in case of jpg, which is also the default.
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!
Here, too, the Back-button will bring you back to the main dialog. All options have immediately been applied.

Button Quit

Does, what it sais. With the Quit-button you exit the program. In the current version, the configuration is lost each time, when you close the main dialog and thus leave Html2Slideshow. This means, that before you can generate the next slideshow or replace an existing one, you will have to choose your folders and options once again. This will probably change when the program is updated some time, so that your current settings can be saved and restored in the next session.
Also, in the current version and due to the non-permanent configuration, each time you click Quit in the main dialog, the confirmation dialog from the next screenshot pops up:

I plan to endow this dialog with a checkbox and allow the users to skip over the confirmation.

Button Howto

To open the HTML-page, which you are currently reading, any time in a web-browser of your choice, you can click the Howto-button in the main dialog. You are asked for the command, which opens the browser. Either 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, you can return to the previous dialog with the Back-button and alter the browser-command.

Button About

This button displays the copyright-information and short version of the GNU-GPL.

↑Keyboard shortcuts

For each button, that you see on the surface, a keyboard-shortcut exists, which can alternatively trigger the same action as the button does. A list of these shortcuts is not necessary, as each one is the combination of the Alt-key with the first letter of the button-caption. For the Howto-dialog this means, that Alt+b closes the dialog, while Alt+a should bring up the web-browser of your choice.

In addition, the shortcut Alt+q is available in each dialog to quit the application completely. Use the same shortcut again, when asked to confirm that you want to close down Html2Slideshow.

↑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.

In the main dialog of the program, I enter the path to the source-folder:
Due to the line-break in the path to the (will-be) slideshow-folder, a slider appears to the right of my dialog. This may or may not happen, depending on your display-configuration and the length of the path-entries, you choose.

Next, I just click the Start-button and a moment later, all is done. You can, though, use the options-dialog, as explained above, 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: