Creating guided tours

Guided tours are interactive help systems within OpenRocket. They are defined as a set of "slides", where each slide has an image (typically a screenshot) and a short amount of descriptive text. The description text can be HTML-formatted, and can also contain links to other tours.

Common files

Two common files are used in the tour loading:

datafiles/tours/tours.txt contains a list of all tour files, one per line. There are relative to the tours directory, for example "introduction/introduction.tour". Blank lines and comment lines are ignored.

datafiles/tours/style.css is a common CSS style file for all tours. This provides additional formatting for the HTML, though the formatting should be kept at a minimum.

The tours themselves are read for the files specified in the tours.txt file.

Tour files

Typically a tour will have a directory of its own, containing the tour definition files and related images.

The tour definition file is a text file in UTF-8 encoding with the following format:

#
# Any lines starting with a hash are comments.
#

# First non-blank, non-comment line in the file is the title - this cannot contain HTML
A sample tour

# The lines before the first slide are the tour description
<p>This is the tour description.
<p>It can contain multiple paragraphs using a simple HTML syntax.


# Slides are started by containing an image name withing brackets
[slide1.png]
<p>The description for the slide follows.  It can contain HTML marking such as <b>bold</b>, <i>italics</i>, <sub>subscripts</sub> or <sup>superscripts</sup>.
<p>Each paragraph within the slide should be started with an HTML paragraph element.

# Next slide, please
[slide2.jpg]
<p>Slide images can be either PNG or JPG.
<p>Slides <a href="another_tour">can even contain links</a> to other tours.

The images are read from the same directory as the tour definition file.

Localization

Tours can be localized by creating a translated version of the tour definition file. If the base definition file is "example.tour", the German translation would be put in "example_de.tour".

If localized screenshots are needed, the screenshots should be put into the tour directory, and the localized tour definition needs to point to those image files. (The localized image files are not loaded automatically - the tour definition must explicitly point to them.)

For clarity, the localized screenshots should still be named as the base file with the appropriate language code appended (e.g. main_window.png -> main_window_de.png).

Image management

The screenshots often need to be resized suitably to the dialog size, and also to reduce their size. In some cases modifications are made to the screenshots to highlight some details (example).

To preserve the original image and to make it easier to make updates later on, the source image can be saved to datafiles-src/, and automatically converted into the proper size for the slides. The script datafiles-src/tours/convert-images.sh performs the conversion automatically (but must be run separately). It can convert PNG and JPEG images (named *.png and *.jpg) and Gimp layered image files (named *.xcf.gz).

For example, the image at datafiles-src/tours/introduction/main_window_top.xcf.gz is automatically converted into datafiles/tours/introduction/main_window_top.jpg.

Images that originally are 50kB or less and have no significant modifications should be saved directly into datafiles/ to preserve the image quality.

Example

The tour definition file for the OpenRocket introduction is in SVN: datafiles/tours/introduction/introduction.tour

The full directory with the images is: datafiles/tours/introduction/

The list of all tours is: datafiles/tours/tours.txt

Tour ideas

Some ideas for guided tours:

• Introduction (DONE)
• Creating a simple rocket design
• Defining motors
• Simulating a flight
• Plotting options
• Rocket display options
• Rocket design analysis
• Automatic optimization
• Creating a multi-stage design
• Creating a clustered design