[ howto.txt - Wed Apr  9 14:49:00 2003 - the georoster plugin - /mtr ]


0.  configuration options:

    # automatically open GeoRoster window
    set georoster::options(automatic) 1

    # show cities on map (none, markers, or all)
    set georoster::options(showcities) all

    # file defining city names & locations, localized for XX
    set georoster::options(citiesfile) .../earth.XX

    # file defining ISO 3166 country codes
    set georoster::options(3166file) iso3166

    # default country to use, if unspecified in vCard
    set georoster::options(default_country) us

    # file defining region/locality names & locations, for country XX
    set georoster::options(coords,XX) .../XX.coords

    # file containing gif to use as background for map
    set georoster::options(mapfile) .../bwmap2.gif

    # procedures to map from x/y to lo/la, and back again
    proc georoster::lo {x  y}
    proc georoster::la {x  y}
    proc georoster::x  {lo la}
    proc georoster::y  {lo la}

    # hook to locate a given jid:

    proc XX {jid update} {
        if {$success} {
            eval $update [list $la $lo]
            return stop
        }
    }

    hook::add georoster:locate_hook [namespace current]::XX


1.  how it works (manual mode)

    you are free to drag-and-drop entries from your roster to arbitrary
    locations on the GeoRoster window.

    click on "Store" to save those values.


2.  how it works (automatic mode)

        set georoster::options(check_vcard) 1

    whenever someone on your roster updates their presence, tkabber with
    fetch their vCard.

    if the vCard contains lat/long coordinates, those values are used
    directly.

    otherwise, tkabber tries to figure out the country associated with
    the user using:

        - country information from the vCard, if present
        - country information from the jid (e.g., fred@example.XX),
          if it's a 3166 code
        - country information from the vCard email address, if present
        - otherwise, the georoster::options(default_country) is used

    now, there's a switch statement that knows how to find someone,
    based on the addressing information in the vCard (locality, region,
    pcode) for a given country code.

    at present, there's only one case in the switch, for "us" -- it does
    an HTTP lookup at www.census.gov.

        if you know of a similar service for other countries, please
        contribute code!

    if there isn't a lookup routine, or if the routine fails, then a
    coordinates file for the country code is consulted. this file maps
    region/locality information to coordinates.

        if you know of coordinate information for a given country code,
        please contribute to the relevant the coordinates file.

    finally, if there isn't a match based on the vCard, then the
    georoster:locate_hook is invoked.


3.  coordinates files

    a coordinates file contains two parts. the first part does
    normalization of region names, and the second part maps
    region/locality name pairs to coordinates.

    the file itself consists of tab-separated fields, containing
    lower-case strings

    take a look at .../us.coords for an example.

                                  #######
