[ 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.
    
                                  #######
