Suominet File Formats

6/14 2005 -- Maggie Sleziak

File Format documentation for Suominet.

SuomiNet data files are documented via a specialized XML format. Files in this format are converted via a perl script to HTML for display on the web.

All the HTML-ified XML files are accessed from the web via an image map (called pub.png) which shows the organization of file types in the /pub directory hierarchy.

The /www/suominet/fileFormats/ directory contains several file types:

1. XML files: filetype.xml (eg iguOrb.xml). These files contain descriptions in XML for a given data file type. These XML files can have the following tags:

   • data_format
     The root element for all files. Contains the 'name' attribute, plus other attributes to describe the name.
   • description
     Contains a text/html description of the data file.
2. data_format.pl
   This program converts the XML files to HTML for display on the web.
3. updateMap.pl
   This program generates the image and image map which shows a sample /pub hierarchy. These files are pub.png and pub.map.
4. pub.tar
   This file contains a sample /pub hierarchy which shows how the various file types are organized in the /pub directory. This file is used by the program updateMap.pl to generate the image and image map.

How to add and update data file documentation:

To add documentation for a new file type (say data type foobar), do the following:

1. First create a foobar.xml file like this:

   <data_format>
   
   <description>
   The 'foobar' file contains foo data in the bar format.
   More text...
   </description>
   </data_format>
   

2. Run data_format.pl on it:

   ./data_format.pl foobar.xml
   

   This will create the file foobar.html in the fileFormats area, which should now be visible from the web.

3. In case you want to add the foobar file type to the pub.png image map, try this. First untar the pub.tar file:

   tar -xvf pub.tar
   

   This will extract a directory ./pub in the fileFormats directory.
4. Now add add a foobar directory in this hierarchy:

   cd ./pub/suomiday/level1b # (say)
   mkdir foobar
   cd /www/suominet/fileFormats
   

5. Now, create a new pub.tar file:

   mv pub.tar pub.tar.bak
   tar -cvf - pub > pub.tar
   

6. Finally, update the image and image map:

   ./updateMap.pl