With therion you can insert comments in the survey files and have them added to the output map, or generate their list as HTML or text files.

Attributes are name-value pairs. Different objects can have the same attribute (same name) with different values. Attributes are specified with the attr command, followed by the attribute name and value. The name cannot be the empty string, and cannot start with underscore '_' (the names beginning with underscore are reserved for internal use). To get the value of an attribute in Metapost code use the variable "ATTR_name" where "name" is the name you gave to the attribute.

The attribute value can be a number, either integer or real, or a string. For example,

  survey s10 -title "..." -attr cave "cave name"
  ...

Another example,

  point 120 343 label -text "first label" -attr display 1
  point 541  18 label -text "second label" -attr display 2
  point 956 283 label -text "third label" 

This allows to distinguish labels by the value of their attribute "display", or by not having this attribute, as in the case of the third label above. Accordingly the labels could be drawn in different ways, by overriding the MetaPost code that draws label point [S. Mudrak, 2007],

  code metapost
  vardef p_label@#( expr txt, pos, rot, mode ) =
    if ATTR_display > 0:
      if (mode = 1) or (mode = 7): 
        interim labeloffset := (u/8) 
      fi;
      lab:=thelabel@#(txt, pos);
      if mode > 1: 
        pickup PenD
      fi;
      if mode = 1:
        pickup pencircle scaled (u/6);
        drawdot(pos);
        process_label(pos,0);
      elseif mode = 2: process_uplabel;
      elseif mode = 3: process_downlabel;
      elseif mode = 4: process_updownlabel;
      elseif mode = 5: process_circledlabel;
      elseif mode = 6: process_boxedlabel;
      elseif mode = 7: process_label( pos, rot );  % station name
      elseif mode = 8: process_filledlabel( pos, rot );
      else: process_label( pos, rot );
      fi;
    fi;
  enddef;
  endcode

Continuation are associated with a description (comment or text).

Continuation comments can be inserted with the station command of the centerline block. For example,

  station 3 "tough climb" continuation attr height 20
  station 1 "entrance" entrance attr "name" "middle cave"
  station 4 "need to survey" continuation explored 20 

Here 3 is the station name. it is followed by the comment, the continuation flag and optional custom attributes (option attr). The station 1 has flag entrance and a name attribute with value "middle cave". More attributes can be inserted. The explored flag is used to specify the length of explored passageways at the continuation. The continuation informations are exported as table (either plain text, HTML formatted, or dbf) with the export continuation-list command. With the -filter off options all continuations, including those without comment, are exported to the list. Currently, it is not possible to use more sophisticated filters (e.g. projection) [2009.01.23].

For the scraps there is the continuation point command. The comment is specified with the -text option and the custom attributes with the -attr option. The continuation point is shown with a question mark in the output map.

To display with a question mark also the continuation stations you must add the layout option symbol-show point continuation-station.

To display the associated comment (and attributes) you need to redefine the continuation symbol. The following is taken from the distribution samples (the comment of the continuation point is stored in the text attribute),

  code metapost
    def p_continuation(expr pos,theta,sc,al) =

      % draw question mark above station:
      % rotation=0, scaling=1, offset=(0,2)
      %
      p_continuation_UIS(pos, 0.0, 1.0, (0, 2) );

      % if text attribute is set
      if known ATTR_text:
        % set labeling color to red
        push_label_fill_color(1.0, 0.0, 0.0);

        % draw filled label with text below station
        p_label.bot(ATTR__text, pos shifted (0,-0.5u), 0.0, 8);

        % restore original labeling color
        pop_label_fill_color;
      fi;
    enddef;
  endcode

The list of continuations can be exported as HTML, text, xBase databases, or KML file. The export command is

  export continuation-list -o output_file

The format is automatically selected from the output file extension ("txt", "html", "htm", "dbf", "kml"). Otherwise it can be specified with the option -fmt followed by the format name ("html" for HTML, "text" or "txt" for text, "kml" for KML and "dbf" for xBase db). If no output is specified the list is exported as plain text file with name table.txt. To export the continuation list in KML format you must have defined the coordinate system (command cs) and specified the coordinates of one station, at least (command fix).

Each record of the table contains comment, the explored length, the survey name and the station name. To tell therion to put also the custom attributes on the output table you add the option -attr on (or -attributes on) to the export command. For example, export continuation-list -o table.txt -attr on. The command -attr off tells therion not to put the custom attributes.

The output table has a record for each continuation point (in the scraps, provided its -text option has been set, and one for each continuation station (in the centerline) with a comment. With the export option -filter off, all continuation points and stations are listed whether they have a comment or not. For example, with the above three continuations in the centerline, and the two continuation points (in a scrap)

point 301.0 358.0 continuation -attr code "E0" -text "explored" -attr length "28"
point 299.0 147.0 continuation -attr code "D2" -text "to climb" -attr height "+20"

the output table is ("Survey" is the title of the survey)

Code	Comment	Explored	Survey	Station	length	height
E0	explored	#N/A	Survey	4	28	#N/A
D2	to climb	#N/A	Survey	3	#N/A	20
D+	20 m climb, tough	#N/A	Survey	3	#N/A	#N/A
E	need to survey	20	Survey	4	#N/A	#N/A

The last two columns are the attributes columns. Where a data is missing there is "#N/A". The first two records refer to the two continuation points. The station column is filled with the closest station. The last two records refer to the station continuations. Attributes are corrently not implemented for stations.

Similarly to the continuation-list export, the export survey-list command generates the table of the surveys of the project. Each record contains the survey title, its lenght and depth, and its id (full name).

The export cave-list command generates the table of caves. It is useful for a cave system with many caves. The caves are denoted by their entrances: these can be specified with the survey command entrance followed by the station name, for example "entrance 1@survey_01", or by the entrance flag of the centerline command station, for example "station 1 comment entrance" (if there is no comment use two double quotes for it). The option -surveys can be either "on" (default) or "off". When it's "on" a hierarchical display of the surveys is produced. The option -location, which can also be either "on" or "off" (default), controls the output of the locations of the caves. The option -attr, that too can be on (default) or off, specifies whether to export the cave attributes as well.

For each cave there are given the length (including also shots with flag approximate, but excluding duplicate, surface and explored), the depth, the explored length, and the entrance altitude. With -location on, the coordinates of the entrances are also listed.

The cave list can be exported as plain text file, as HTML, as KML, or as DBF file. The format is specified by the -format option, or the name of the output (option -output or

The export of the bounding box produces a text file with the geografical coordinates of the upper-right and lower-left corners of the rectangular area that contains the cave. You must have specified a coordinate system for the cave data.

Attributes and continuation export
KML continuation list