MapUtils '.loc' file format documentation
=========================================
This document describes format version 4.1.

GENERAL FORMAT DESCRIPTION
--------------------------
A properly formatted loc-file MUST start with line:

# MapUtils LOC file (version 4.0)

Processing software MAY check against the version number to see if they
are compatible with the format. Any backwards-incompatible changes
will result in change of the major version digit.

Rest of the format is as follows:

 * Character set used is ISO-8859-1.

 * Location record starts with a number describing the X-coordinate.

 * Records can span multiple lines (line can be continued by ending
   with a slash character '\').

 * Records end with a linefeed (\n) character (unless continued with '\')

 * Empty lines (this includes lines with whitespace only) are IGNORED.

 * Lines where the first non-whitespace character is a hash (#), are
   considered comments and are thus IGNORED. Processing software MAY
   preserve and add comments, if wished. Comment lines CAN NOT be
   continued with the above mentioned line continuation method.

 * String-type fields can contain ESCAPED sequences (escape character
   is slash '\'), which MUST be parsed into literals.
   Example: foo\;bar would be parsed to "foo;bar"


Each record is divided to fields 8 fields via semicolons (;). Fields MAY
contain extra whitespace padding on both sides (left and right), which
SHOULD be trimmed by the parser. Each record consists of following fields:

       X;Y;flags;location name(s);creator(s);timestamp;URL;freeform


The fields are as follows: (REQ = field is required, OPT = field can be
left empty)

 * [REQ] X (horizontal) and Y (vertical) coordinates of the location
   with origo (1,1) being in upper left corner of the map. The coodinate
   pair MUST be unique in the context of the LOC file.

 * [REQ] Flags: Contains information about the marker's type, etc:
   First (non-whitespace) character MUST be a number [0-3], which describes
   the alignment of the marker's label. Rest of the flags are OPTIONAL, and
   may comprise of following:

   Marker types:
     '?' = Scenic
     '%' = Shrine scenic
     'C' = Player city
     'c' = Major city

   Location types:
     'S' = Raceshrine
     'G' = Guild
     'P' = Player guild/secret society
     'M' = Special monster
     'T' = Guild-related Trainer
     'F' = Regional Fort

   Special flags:
     '-' = Location is "invisible". Practically means that some operations
           of mkloc utility ignore this marker. In generated maps the marker
           itself MUST be placed, but label MUST NOT be drawn.
     '!' = Location is CLOSED.
     'I' = Location is "instanced", e.g. usually personal for each player.

 * [REQ] Location name(s): The first name acts as UNIQUE identifier, but
   there are exceptions: locations marked with invisible flag (-) may
   share the same location identifier. Additional alternative names can
   be specified, separated by pipe character ('|').
   Example: ;Sharnacle Forest|@Sharnacle|Monsoon area;

   Each subfield (including the first unique identifier), MAY be prefixed
   with ONE of the following flag characters:

     '@' = Original, in-game name of the area. Typically output of 'whereami'
           command in flower BatMUD.

 * [OPT] Creators: Contains comma-separated list of wizard names involved in
   creating or maintaining the area or otherwise related to the location.
   Example: ;@Darol,!Durand,%Dazzt;

   Each subfield, MAY be prefixed with ONE of the following flag characters:

     '@' = Original creator/coder of the area.
     '!' = Converter or recoder of the area.
     '%' = Maintainer (sometimes analogous to recoder, though.)
     '&' = Expander (added new things, but not original creator.)

 * [OPT] Timestamp: MAY be left empty, otherwise a timestamp of when the area
   was added in the game. Formatted as 'dd.mm.yyyy', MUST be zero-padded.
   The value MAY be prefixed with one of the following signifying accuracy:

     nothing = Default accuracy
     '?' = Timestamp is "guesstimated". Basically an educated "guess"
           possibly based on some evidence.
     '!' = Timestamp is "known", e.g. as accurate as it can be.
     '#' = Timestamp is "approximate", e.g. may be off by some.

   Examples: 21.03.2008; ?02.12.1996

 * [OPT] URL: Properly encoded URL-link pointing to related web-page.

 * [OPT] Freeform: Any location-related data. Ends in linefeed as it is the
   last field.


CHANGES FROM v4.0
-----------------

 * Location added field can now have a timestamp accuracy prefix character.


CHANGES FROM v3.x
-----------------

 * Origin (origo) is now (1,1), compared to previous (0,0). This means
   that coordinates < 1 are illegal and that the data files have been
   adjusted +1,+1. This change was made to match BatMUD's internal
   coordinates, as shown by 'whereami' command.
 * Location name field can now have special flag prefixes on each
   subfield to indicate original (in-game) area name, etc.
 * Creator/coder name field can now have special flag prefixes on each
   subfield to indicate original coder, maintainer or recoder.
 * Certain new flags were added.


CHANGES FROM v2.x
-----------------

 * Records are no longer line-based, but can span multiple lines.
   A new record can only start after a newline, though.
 * String fields can have escaped sequences inside them.
 * Name field can now contain optional alternative names,
   separated by pipe ('|'). First name, is still used as the
   primary "key", however.