RoadHog: Compiling

This page tells you what the RoadHog Compiler does once you have prepared all the input data.

Calling the Compiler

Call the compiler using this syntax:
java org.remote.roadhog.Compiler [option]... [file]...
where option is

and file is any XML file containig input. Again, you have to make sure that the maps and vertices required are defined before the edges and journeys that use them.

Compiler output

The compiler will potentially create a huge amount of data and take forever to do it. When I compile my "On the Road in Western Scotland" stuff, the compiler will generate over 32,000 files (over 600 MB total) and work for about ten hours.

The following is a detailed list of the compiler's output (filenames are relative to the destination directory specified).

File Name(s) Contents Remarks
The map segments. <mid> is the map ID, <siz> is the size code (usually one of the letters t, s, m, l, h for tiny, small, medium, large, huge), <r> and <c> are the row and column number.
Unless in -f mode, the original map image is only read into memory and scaled if at least one of the files does not exist already.
not -x
The map segments with red dots painted into them.<x> and <y> are the dot co-ordiantes relative to the map origin; if a dot, because of its radius, is visible on two or even four map segments, there will be two or four files with the same x and y values.
One dot file is generated for every photo in every journey processed, unless multiple photos share the same dot position.
not -x
img/<jid>/<siz>/<n>.jpg The photos for each journey. <jid> is the journey id, <siz> the size code, and <n> is the zero-padded sequential number of the photo. not -x;
not -m
The control files for each journey. <jid> is the journey id, and <siz> is the size code. These are small text files that are read by the CGI script and describe the journey and possible onward connections; otherwise the CGI would have to access the XML files and that would be too time consuming. not -x
Index files that are used by the search CGI script to find co-ordinates and place names. not -x
not -m
The "place files" with details about every vertex that has a <description> tag. <vid> is the vertex id; the jpg images are generated if the vertex also has <illustration> tags, and <n> then is the sequence number of the illustration.
The HTML files are generated using a built-in layout that anyone using the compiler will probably have to change in the source code.
not -m
The "showcase" page with is associated images; the data is taken from any <showcaseitem> objects found in the input. I haven't described that anywhere but it is straightforward; just selected images with pointers to journeys.
The HTML file is generated using a built-in layout that anyone using the compiler will probably have to change in the source code.
not -m
journeys.html The journey listing (contains pointers to all journey segments, ordered by vertex names).
The file is generated using a built-in layout that anyone using the compiler will probably have to change in the source code.
not -m
The index page, which will definitely have to be changed in style and contents, and the two pictures for it. They will have to be averaged using an external program (like convert index1.gif index2.gif -average index.gif) to create the clickable map for the index page. These images are only generated if there is a map object with the map id "minimap" among the input files which will be used as the source image. not -m

Unless run in "force" mode (-f), the compiler will not re-generate files that already exist; however, this rule only applies to files that are rather time-consuming to create. The output files in the "ctrl" directory and all HTML output are generated in any case. The compiler will also create all directories it requires.

Size Codes

Both map segments and photos are created in different size classes. The size classes to be used are defined in the Compiler and may be changed in the source; for test runs, it may be advisable to generate the "tiny" category only, for example.

Back to the index

  Frederik Ramm, 2001-05-26