GEOLOG

Note: The file is not up-to-date. The most recent descriptions are found in the German file liesmich.html. If you have questions, contact me at geolog <at> felias-fogg.de. If there is enough interest, I can be convinced to update the English description as well.

1. What is it good for?

Geolog is a Perl script (also available as a Windows program) that you can use to generate HTML pages from Geocaching information such as Groundspeak's pocket queries in a rather flexible way by using templates. An example is my Geolog website: http://felias-fogg.de/. One particular use of Geolog is the generation of statistical summaries such as http://felias-fogg.de/stat.html. Geolog also assists you in downloading log photos of your logs and in incrementally updating log and listing information. Additionally, Geolog prepares the information so that they can be uploaded to the opencaching.de website using the Ocprop script.

2. File Structure

 When starting the program the first time, one has to specify the directory where all the cache data is going to be stored. We call this directory the main directory in what follows. By default, the main directory will have the name gcdir. After the directory has been fixed, Geolog copies a number of files and sub-diretories into the main directory:

3. Installation

3.1 Perl

If you use the Windows executable, installation reduces to unzipping the file geolog.zip.

If you want to use the script, you need of course Perl. All decent Linux/Unix distributions contain it already. For Windows, you have to download and install it first. However, this is quite painless. Just download and install ActiveState's ActivePerl. After the installation, all files ending with .pl will be considered as Perl scripts. You can start them just by clicking them. If you want to pass options and/or parameters to the script, you have to start the script in a command window.

It may happen that you encounter error messages such as 

Can't locate HTTP/Cookies.pm in @INC ...
when you start the script. This message indicates that a module is missing, in this case HTTP::Cookies. You can use the module CPAN under Unix-Perl or the program ppm for ActivePerl under Windows in order to download missing modules. More information can be found on the respective websites www.cpan.org resp. ActiveState.

3.2 Setup with the first call

Now one should start Geolog once in order to initialize everything. This is best done by opening a terminal window and change into the directory where the main directory is located (or shall be generated).

When first calling Geolog, you have to specify a number of parameters, which are then stored in the profile ~/.geolog/profile.txt or, if running under Windows, in ...Application Data\Geolog\profile.txt or something similar. Later, you can edit this file with a text editor. Instead, it is also possible to use the -e option when calling Geolog. In this case, you can go through all the questions again with default values determined by your previous answers.

4. Calling the Program

If you call the program without any options and parameters, under Windows the user is peresented an option menu. Under Unix, no option is equivalent to calling Geolog withthe option -i.

The general way to call the script is: 

geolog.pl [options] [waypoint names]
If one calls the Windows program, one has to use the exe file extension, of course: 
geolog.exe [options] [waypoint names]
With 
geolog.pl -h
you get a short help message.

In addition, you can start the program with the following options to get a special behavior:

In addition, there are the following modifiers:

5. Cache Information

If geolog finds a new cache (owned, found or not found) on the GC website, a new directory with name Cachename_Waypointname is created. In order to simplify things, critical characters such as ':', '/' etc. are replaced by '_'. In this irectory, the following files will be generated: The user can generate the following files:

6. Template Files

In order to modify the appearance of the HTML pages, one can edit the template files. The main directory gcdir contains index.tmpl. It is possible to add more template files with a .tmpl extension. All of them will be translated into .html files, whereby the rules described in the following section are applied.

Each of the sub-directories found, not-found, and hidden contains the following templates:

Additionally, one can generate alternative tables (perhaps with a different order). The templates for these tables have names index0.tmpl up to index9.tmpl. The corresponding HTML file have html file extensions. An additional template for each cache is the text.tmpl file. In the supplied templates, it is only used for hidden caches.

7. Templates

The templates contain ordinary HTML-code together with markups which get substituted by geolog. First of all, one can use global abbreviations that are defined in the file abbrev.txt and are marked by being surrounded with double #-signs. Furthermore, all attribute names and attribute values are marked by being surrounded with single #-signs.

The syntax in the abbrev.txt is as follows. Each line that contains a string surrounded with double-#'s starts a new definition. All following lines until the next empty line define the string that is abbreviated, e.g.: 

##lefticon##
gc_small.gif

##leftref##
<a href="http://www.geocaching.com/">

All strings of the form #attribute name:# are replaced by the respective attribute name. The attribute values will be substituted for strings of the form #attribute name#. Text enclosed by #attribute name?# #attribute name!# is only included, if the respective attribute value is not the empty string. Similarly, text enclosed by #-attribute name?# #-attribute name!# is only included if the respective value is the empty string. Repeating table columns are enclosed by #<# and #>#.

The attribute names result from the field names described in Section 5. Additionally, there exist the following attributes:

If you want to display attribute names or values differently, you can use the translate.txt file. If an attribute value end in .gif or .jpg, it is assumed that this is a picture file in the pics sub-directory and it will be replaced by an img-entry referring to the respective picture file. In addition, #indexhtml# will either be replaced by the empty string or by index.html depending on what the profile specifies. Furthermore, #image# will be replaced by an img-entry referring to image.jpg and #thumbnails# will be replaced by a set of img-entries to files in the cache sub-directory pics.

Finally, it is possible to specify some parameters that influence the appearance of the HTML files:

Examples for using all these constructs used in template files and how it looks like can be found on my website felias-fogg.de/.

8. Feedback

Please send praise, contributions (new template sets) and problem descriptions to fogg at gmx.de. If it is a problem description, please be as specific as possible and send the log file of any problematic run of the script.

9. License

GPL, of course!

Happy geocaching - fogg (geolog <at> felias-fogg.de)