\documentclass[12pt]{article}

\usepackage{a4, epsfig, times, fancyhdr}
%\usepackage[T1]{fontenc}

\nonstopmode

\hbadness=2000
\vbadness=2500
\clubpenalty9000
\widowpenalty9000
\tolerance=9999
\textheight=24cm
\footskip=3\baselineskip
\lefthyphenmin=3
\parindent=0pt
\parskip=0.5\baselineskip
\hyphenation{ }

\pagestyle{fancy}
\renewcommand{\headrulewidth}{1pt}
\lhead{\scriptsize V \number\year -\number\month -\number\day}
\chead{}
%\rhead{}
\rhead{\thepage}
\lfoot{}
\cfoot{}
\rfoot{}

\renewcommand{\topfraction}{1.0}
\renewcommand{\bottomfraction}{1.0}
\renewcommand{\dbltopfraction}{1.0}
\renewcommand{\textfraction}{0.0}
\renewcommand{\floatpagefraction}{.5}


\newcommand{\gpsbabel}{{\sc gpsbabel}}
\newcommand{\bsl}{$\backslash$}



\begin{document}


{\center
\Large \bfseries The \gpsbabel\ Manual\\[5mm]
Version 0.0.2\\[10mm]

{\rm \normalsize Principal developer:}\\
\large Robert Lipe\\[2mm]
robertlipe@usa.net\\
}

\tableofcontents

\newpage

\section{What \gpsbabel\ is}

{\bfseries \gpsbabel\ is a conversion utility for a large and still increasing number of GPS related formats that represent waypoints, track points and route points.}

There are simply too many and annoyingly different file formats to hold waypoint, route and track related information in various programs used by computers. Even though there are some promising attempts to create format standards, e.g. GPX as an XML variant, to carry all data types, there are too many programs that don't understand them yet and too much existing data that are in alternate formats.

\gpsbabel\ is based on an extensible foundation	so that it is quite easy to add new formats.  Most file formats implemented so far have taken less than 200 lines of reasonable ISO C code, so they can	be stamped out pretty trivially. If you would like to contribute new features, see appendix~\ref{HowToContribute}

\gpsbabel\ is designed for simple command line invocation for all supported platforms. For users not familiar with the command line (read: many Windows users) there is a mouse pitchforker's GUI interface to ease its use (see section~\ref{GUI}). A full fathoming of \gpsbabel 's features will need some command line familiarity, though.

\gpsbabel\ is released under the GNU general public license. For further details, see appendix~\ref{GPL}.


\subsubsection*{What \gpsbabel\ is not:}

\gpsbabel\ is not intended to {\em create} any GPS related data, like waypoints or tracks. It does not support uploads or downloads of maps.



\section{General usage: the command line interface}

On every supported operating system platform \gpsbabel\ basically is a command line program. This kind of invocation, providing the utmost freedom of including runtime options, creates the best possible flexibility. Unfortunately, that can
sometimes lead to unwieldy command lines.

To use this program, just tell it
\begin{itemize}
\item  what kind of data you want to read, 
\item where to read it from,
\item what format you want to be written,
\item and what file or device to write it to.
\end{itemize}

For example%
\footnote{In our examples we frequently split the respective command lines into several real lines to create a better readability. If a command line ends in a "\bsl " (being the usual continuation character of an input line), this means for actual usage that the command itself extends into the next given line.}

{\tt \small
\begin{tabbing}
gpsbabel~\= -i geo ... \kill
gpsbabel \> -i geo -f /tmp/infile.loc \+ \bsl \\
						-o gpx -F outfile.gpx
\end{tabbing}
}

tells it to read the file ~{\tt infile.loc}~ in the ~{\tt /tmp}~ directory%
\footnote{Directory delimiters are always given in the Unix-ish variant, i.e.: "/" is used where Windows users would enter a "\bsl" or similar.} in the {\sc geocaching.com} format and create a new file named ~{\tt outfile.gpx}~ in GPX format, to be placed in the present working directory.

The next command will read waypoint data from a Magellan unit attached to the first
serial port and write them as a geocaching loc file.  The first command is the Linux variant, the second command does the same for windows.

{\tt \small
gpsbabel -i magellan -f /dev/ttyS0 -o geo -F mag.loc

gpsbabel -i magellan -f com1 -o geo -F mag.loc
}	

\bigskip

{\tt \small gpsbabel -?} will always show you the supported file types.

\bigskip

People less familiar with the command line will find a GUI interface helpful. A first one, for Windows, is described in section~\ref{GUI}.



\section{Modes of operation: waypoints, routes, tracks}

There are three basic entities of GPS data that are of interest for a general conversion utility: waypoints, routes, and tracks.

\begin{description}

\item[Waypoints] describe isolated and unrelated points in space each. Each is specified by its position (latitude, longitude, height above sea level), a "short" name (that is usually displayed to describe it on the receiver), a comment (or "long" name; an extended text associated to the waypoint), an icon (to display it on a receiver's map display page), and several less important featurs (like time of creation, display options, ...) that even vary between the different receivers.\\
Transferring waypoints is \gpsbabel 's {\bfseries default mode of operation}. It may as well be invoked by entering a {\tt -w} as {\em first} command line argument.\\
Optionally, you may specify {\tt -s} as a command line switch.  This causes the program to ignore any "short" names that may be present in the source data format and synthesize one from the long name.  This is particularly useful if you're writing to a target format that 
supports more elaborated short names but the source data was written in a very simple style.  I use this for writing data from geocaching.com to my Magellan so my waypoints have "real" names instead of the 'GC1234' ones that are optimized for NMEA-only 
receivers.

\item[Routes] are ordered sets of waypoints that describe a path to follow. Since most contemporary GPS receivers have very limited possible set sizes (typically 30 or 50), but support multiple routes to be administered in parallel, the usual way to handle them is to work on a set of routes at the same time. Read: a set of sets is handled.\\
Treatment of routes is only implemented for a part of \gpsbabel 's formats. Details are given in the respective section on the various format types. To invoke route treatment, {\bfseries enter {\tt -r} as {\em first} command line argument}.

\item[Tracks] are lists of waypoints with position and creation time information only. They are sampled in larger quantities when traveling. They are intended to describe the traveled path as exactly as possible (if so desired). Track logging memory of the receivers usually can gather 1000 to 10000 individual points.\\
Treatment of track data is only implemented for a part of \gpsbabel 's formats. Details are given in the respective section on the various format types. To invoke track treatment, {\bfseries enter {\tt -t} as {\em first} command line argument}.

\end{description}



\section{Supported input and output formats}

This section describes the supported file or transmission protocol formats in detail. Please remember that the capabilities of the various receiver types are quite different, so transfers from one receiver to another, or from a general file format to a receiver, might go wrong: you cannot deliver more waypoints, route or track points than the target is able to swallow. This kind of error cannot be handled by \gpsbabel .



\subsection{Tabular overview on formats}

\begin{tabular}{|l|cc|cc|cc|}
\hline
							&	\multicolumn{2}{c}{Waypoints}	&	\multicolumn{2}{c}{Tracks}	&	\multicolumn{2}{c|}{Routes} \\
File format 	& Read 	& Write									& Read & Write								& Read & Write\\
\hline
\hline
Cetus										& yes		& yes		&				&				&				& 			\\
CoPilot Flight Planner	& yes		& yes\footnote{Magnetic declination is not written.}
																				&				&				&				& 			\\
CSV											& yes		& yes		&				&				&				& 			\\
Delorme S\&A						& yes		& yes		&				&				&				& 			\\
Delorme TopoUSA/XMap Conduit 
												& yes		& yes		&				&				&				& 			\\
~~~~~(XMap)							& & & & & & \\
Delorme HandHeld 				& yes		& yes		&				&				&				& 			\\
~~~~~Street Atlas USA (XMapWpt) & & & & & & \\
Garmin serial						& yes		& yes		&	yes		&				&				& 			\\      
GEO											& yes		& yes		&				&				&				& 			\\
Geocaching DB						& yes		& yes		&				&				&	---		& ---		\\
GPSDrive								& yes		& yes		&				&				&				& 			\\
GPSman									& yes		& yes		&				&				&				& 			\\
GPSPilot								& yes		& yes		&				&				&				& 			\\
gpsutil									& yes		& yes		&				&				&				& 			\\
GPX											& yes		& yes		&	yes		&	yes		&	yes		& yes		\\
Holux										& yes		& yes		&				&				&				& 			\\
Magellan serial					& yes		& yes		&	yes		&	yes		&	yes		& yes		\\
Magellan SD card				& yes		& yes		&	yes		&	yes		&	yes		& yes		\\
Magellan Navigator Companion
      									& yes		& yes		&				&				&				& 			\\
Mapsend									& yes		& yes		&	yes		&	yes		&	yes		& yes		\\
Mapsource								& yes		& yes		&				&				&				& 			\\
Maptech Exchange Format (MXF)
												& yes		& yes		&				&				&				& 			\\
Navitrack DNA						& yes		& yes		&				&				&				& 			\\
OziExplorer							& yes		& yes		&				&				&				& 			\\
PCX5										& yes		& yes		&				&				&				& 			\\
PocketStreets 2002 Pushpin
      									& yes		& yes		&				&				&				& 			\\
Tiger										& yes		& yes		&				&				&				& 			\\
TopoMapPro							& yes		& yes		&				&				&				& 			\\
Topo by National Geographic
      									& yes		& yes		&				&				&				& 			\\
XCSV										& yes		& yes		&				&				&				& 			\\
\hline
\end{tabular}

In this table ``---'' means: not applicable since format will by definition not 
support a respective type of data.


\subsection{CETUS}

	Cetus GPS (http://www.cetusgps.dk/) is a program for Palm/OS.  
	Working with Ron Parker and Kjeld Jensen, we can now read and write
	files for that program.   It hasn't been exhaustively tested, but 
	has seemed fine on every input and output we've tried.



\subsection{CoPilot Flight Planner for Palm OS}

        This code is mostly intended to convert CoPilot databases into
        other formats.  I don't think you should use this to write
        CoPilot databases, although the code is there, mostly because
        GPSBabel doesn't convert magnetic declination values.

        Questions, bug reports, etc, to ptomblin at xcski.com


	http://xcski.com/~ptomblin/CoPilot/
	http://navaid.com/CoPilot/



\subsection{Delorme S\&A}

	There are a billion variants of Comma Separated Value data.  This
	is the one that makes Delorme S\&A Deluxe 9 happy.



\subsection{Delorme TopoUSA/XMap Conduit (XMap)}

	Delorme TopoUSA/XMap Conduit is a CSV variant.  It's just like S\&A with the addition of a 
	completely pointless line at the beginning and end of the file.   
	This is the format used to hot-sync to XMap from withing TopoUSA.
	Done with help of Dan Edwards.



\subsection{Delorme XMapHandHeld Street Atlas USA (XMapWpt)}

	Delorme XMapHandHeld Street Atlas USA is CSV variant.  This is the format used by XmapHH SA USA on
	(at least) PocketPC O/S.  This XMap is not to be confused
	with the XMap mentioned above. Contributed to gpsbabel by
	Alex Mottram.

Delorme XMap Handheld .WPT for PocketPC is a bit of a kludge.  This 
document covers XMap Handheld Street Atlas USA edition.

XMap on the PocketPC stores it's waypoints in individual .wpt files.
For example, waypoints generated by XMap on the PocketPC are stored
by default in the "My Documents" folder using the sequential names
"XMap1.wpt", "XMap2.wpt", ad nauseum.  Needless to say, not very
efficient.

As writing multiple waypoint files is outside of the scope of gpsbabel,
gpsbabel chooses to write one big file, one waypoint per line.  
Extracting lines from this file is left as an exercise for the end user.  
A simple perl script to handle this conversion is included at the end 
of this README.

It should also be noted that READING multiple files is indeed possible,
but if you have more than a few points, it can be a task.  For example:

gpsbabel -i xmapwpt -f Xmap1.wpt -f Xmap2.wpt -o mapsend -F mapsend.wpt

will read the two Xmap .wpt files and write one mapsend file.  This
is fine for a small handful of points, but could be quite cumbersome
for folks like me who have 100+ waypoints loaded into XMap.  For *nix
folks, something as simple as:

cat *.wpt > /tmp/foo.wpt
gpsbabel -i xmapwpt -f foo.wpt -o mapsend -F mapsend.wpt 

will do the trick just fine.  

\scriptsize
\begin{verbatim}
############ BEGIN SCRIPT 
#!/full/path/to/perl
$INPUTFILE = @ARGV[0];
$TARGETDIR = @ARGV[1];
$FILENAME  = @ARGV[2];

if (! $FILENAME) {
    print "Usage: xmap_split.pl INPUT_FILE OUTPUT_DIRECTORY FILENAME_BASE\n";
    print " (i.e. xmapl_split.pl points.wpt /tmp/points GPSB)\n";
    print " (created GPSB0001-GPSBXXXX in /tmp/points/ from points.wpt)\n";
    exit;
}

open (INFILE, $INPUTFILE) || die "Cannot open $INPUTFILE for read!\n";

while (<INFILE>) {
    $lc++;
    $filename = sprintf("%s/Gpsb%04d.wpt", $TARGETDIR, $lc);

    open (OUTFILE, ">$filename") || die "Cannot open $filename for write!\n";

    print OUTFILE $_;

    close(OUTFILE);
}

exit;

########### END SCRIPT
\end{verbatim}
\normalsize


\subsection{GARMIN serial}

	Waypoint serial upload and download works reliably under both
	POSIX and Windows.   I tested it with a Vista graciously provided
	on loan by Joe Armstrong.   The communications library used, jeeps,
	claims to support most models of Garmin hardware.   Be sure the GPS 
	is set for "Garmin mode" in setup and that nothing else (gpsd, getty,
	pppd, etc.) is using the serial port.
	


\subsection{GEO}

	geocaching.com spits up geocaching.loc files that are XML-ish but
	not quite GPX.   Because it's so close to GPX, this format is very
	well supported.



\subsection{Geocaching DB}

	This is a PDA file format.    It was tested against version 2
	of GeocachingDB and a development snapshot of version 3.  
	Information on the file format came from Dougs Brat and Ron Parker.
	A particularly handy way to use GPSBabel on these files is to use
	GPSBabel to read a GPX file with Groundspeak  (geocaching.com) 
	extensions and let it write you a GeocachingDB file that contains
	the cache names, difficulty, terrain, and such.

	http://vip.hyperusa.com/~dougs/geocachingdb/geocachingdb.htm



\subsection{GPSDRIVE}
  
        GpsDrive way.txt file format. A space seperated format file. Tested
        against GpsDrive v 1.30 found @ http://www.kraftvoll.at/software.
        Contributed by Alan Curry.



\subsection{GPSMAN}

	GPS Manager can read and write formats that this converter doesn't
	understand.  The default formats (WGS84, DDD) work reliably.



\subsection{GPSPILOT}

	The file format for GPSPILOT (http://www.gpspilot.com) was provided
	by Ron Parker.  The output from this module has been tested with 
        GPSPilot Tracker v5.05sx, but it is based on reverse-engineering
        so it may not work with all versions of all GPSPilot products.
	It had read-only support for Airport, Navaid, City and Landmark 
	files but will read and write Point files.



\subsection{GPSUTIL}

	GPSUtil has a simple file format of this program that runs on POSIX-
	compliant OSes like UNIX and Linux.   Reads and writes of this format
	are reliable.   (I've also contributed to this program.)  It's 	
	available at http://www.cs.uakron.edu/~hennings/gpsutil/.



\subsection{GPX}

	This is the most capable and expressive of all the file formats
	supplied.    It is described at http://www.topografix.com/gpx.asp
	and is supported by EasyGPS, ExpertGPS, and man other programs
	described at http://www.topografix.com/gpx\_resources.asp



\subsection{HOLUX}

        The Holuxgm-100 (e-fox) gps receiver uses standard compact
        flash cards.  File formats were provided by Holux-Taiwan
        http://www.holux.com.tw to the author.  The code was tested
        against version 2.27E1; other versions and receivers may
        work but have not been explictly tested.  Anyone with
        information on other Holux receivers is encouraged to contact
        jochen@bauerbahn.net.

        When copying the .wpo file to a flash card, the file must be
        named "tempwprt.wpo" as the receiver will ignore all other
        files.

        Comparing the waypoints of a .wpo files against other formats
        like .gpx you may notice a small difference in the latitude
        and longitude values.  The reason is the low resolution of
        the coordinates in the wpo file format.  In a .wpo file the
        reolution is 1/10"; in gpx for example it is 1/100".  A a practical
	matter, this loss is only about 1.7meters (5 feet).


        The generated waypoint failes can also be used by MapShow
        version 1.14.  This program is free of charge from the Holux web
        site.

        This format was contributed by Jochen Becker.



\subsection{MAGELLAN (serial and SD card formats)}
\label{MagellanSerial}

\begin{description}

\item[Description:] This protocol supports serial uploads and downloads for the majority of the Magellan units. It has been tested to work reliably with the 315, 330, Meridian, and SportTrak family. In fact, it should work on any modern Magellan unit.\\
Since the contents of the serial interface data transfer is the same that is written to or read from SD cards in the Meridian series, this kind of transfer is automatically supported as well.\\
\gpsbabel\ can also read and write the files that are written to or read from the SD flash memory cards in the Meridian models. Simply specify a file instead of a serial port.\\
%
{\small As of this writing, there is still a lot of "scribbling" in the 
source for functionality that isn't hooked up to the rest of the
program.    Communication errors are handled.}

\item[Applicability:] Waypoints, tracks, routes

\item[Additional invocation options:]~\\
{\bfseries baud}: Baud rate settings may be 1200, 2400, 4800, 9600, 19200 for serial line connections and must match receiver settings. Default value is 4800.\\
{\bfseries noack}: Specifying "noack" turns handshake mode off. Without handshaking transfer of data is sped up significantly but {\em might} lead to overlooked transmission faults. Those have never been experienced during any testing, though. Default setting is "handshake on".\\
{\bfseries deficon}: It is possible to specify a default icon to be displayed for every transmitted waypoint. Please refer to appendix~\ref{MagellanDefIcons} for a list of those.

\item[Usage example:] Read waypoint data from a Magellan receiver via the first serial line interface (Linux/Unix nomenclature given; for Windows replace "/dev/ttyS0" by "com1" etc.) with increased speed, but without handshaking, and write it to a Magellan formatted file.\\[-8mm]
{\tt \small
\begin{tabbing}
gpsbabel~\= -i ... \kill
gpsbabel \> -i magellan,noack,baud=9600 -f /dev/ttyS0 \bsl \+ \\
						-o magellan -F outfile.mag
\end{tabbing}
}

\end{description}




\subsection{Magellan Navigator Companion (MAGNAV)}

Magellan NAV Companion for Palm/OS is not really designed for this 
sort of use, but its file format is supported and with a little bit
of patience you can both read and write NAV Companion waypoints.

This conversion is based on partially
incomplete reverse-engineering of the record format, so it may not
work with all versions of NAV Companion.  It has been tested with 
version 2.10.

Translating NAV Companion waypoints to another format is as easy
as with any other format.  Just find the Companion\_Waypoints database
in your palm backup directory and use it as the input file. 

When translating waypoints back to NAV Companion, though, you need 
to jump through some hoops:  

First, you must merge any waypoints that already exist in the database 
in your Palm Backup directory with the ones you are adding; failure to 
do so will result in only the new points being available in NAV Companion, 
even if you give the new database a different name (it will overwrite 
the old database, even in your backup directory.  That's a feature of 
PalmOS, not of NAV Companion.)  

To merge the databases, use a command line like the following:

gpsbabel -i magnav -f Companion\_Waypoints.PDB -i geo -f geocaching.loc -o magnav -F merged.pdb

Second, you must use the installer to install your new PDB file.  Don't
make the mistake of copying it over the existing Companion\_Waypoints.PDB
file; the one on the handheld will overwrite it rather than merging with
it.

Finally, because NAV Companion is not designed to work with desktop 
applications, you must tell NAV Companion that its waypoints database 
has changed out from under it.  One way to do this is to go to the 
waypoints screen and attempt to scroll; that will force it to reread 
the database and fix the record pointers that it keeps on the heap.


	
\subsection{MAPSEND}

	Magellan was smart enough to document their file format to make
	creating software like this possible.



\subsection{MAPSOURCE}

        Garmin Mapsource format appears compatible with the various
        members of that product family.  Icon mapping is oriented toward
        versions above 4.07.  Altitude, proximity, and depth are not
        supported.

        Information on the Garmin Mapsource format was provided by Ian
        Cowley.  The code was implemented by Robert Lipe.



\subsection{Maptech Exchange Format (MXF)}

        Maptech Exchange Format - Another CSV format file.  This format
        complies with (at least) Maptech Terrain Navigator, Terrain
        Professional, Take a Hike, and ExpertGPS import/export MFX.
        Contributed by Alex Mottram.



\subsection{Navitrak DNA}

	Navitrak DNA marker format - Another CSV format file.
	This is the format that is compatible with the DNA Desktop
	import/export command.  Reading the binary Markers.jwp 
	format directly off the data card is not supported yet.
	Contributed by Tim Zickus.



\subsection{OZI}

        OziExplorer Waypoint Format - Another CSV format file.  Tested
        against OziExplorer v 3.90.3a / Shareware.  Contributed by Alex
        Mottram.



\subsection{PCX5}

	Garmin documents only PCX5, an older format limited to the lame NMEA
	six-character waypoint names that's treated as a second-class citizien
	in current versions of MapSource.  Use file->import to read these 
	files.   Anyone with information on the *.mps file format that is
	now preferred is encouraged to contact me with the details or better
	yet, a module that implements it.   I spent time trying to reverse-
	engineer a couple of *.mps files then I remembered that I don't own
	a Garmin and wasn't that inspired.



\subsection{Pocket Streets Pushpin (PSP)}

	Microsoft's PocketStreets 2002 Pushpin (.PSP) format is not yet 
	completely documented.  THE .PSP MODULE DOES NOT WORK WITH MS 
	STREETS \& TRIPS 2002 .EST FILES.  To create .PSP files from 
        Streets \& Trips 2002, you will need to have PocketStreets support 
	installed.  Please note that MS Streets \& Trips only *EXPORTS* 
	.PSP files. It does not import them.  MS Streets \& Trips 2002 
	only imports CSV files.  To use .PSP files, simply copy them 
	over to the same folder on the mobile device as the map (.MPS), 
	and open PocketStreets.  It should also be noted that in the case 
	a pushpin is outside of the exported map area, the pin will be 
	"grayed-out" and unused in PocketStreets.  This is a good thing 
	as it allows us to create one big .PSP file that covers multiple 
	.MPS files.  Unfortunately, you need one .PSP file for every 
	.MPS file. :(

Q: Why should I use gpsbabel/psp to make pushpins when Streets \& Trips (S\&T)
   already does that for me?

A: gpsbabel/psp has the advantage of being able to create pushpins WITHOUT
   creating the associated map file and the need to "import" the waypoint
   data into S\&T.  Through a series of scripts, you can create a dozen
   or so PSP files in a few seconds as opposed to a few weeks using the
   S\&T interface.  The maps are not going to change between sessions, 
   only the pins will.  Why waste all that time creating maps when all you
   really want are updated pins? As an aside, gpsbabel/psp creates points 
   WITH THE PROPER coordinates where S\&T does not in some areas of the U.S. 
   (Nashville, TN for instance).


Q: I keep getting a blank (32 byte) PSP file?

A: There are either no points to write, or you have botched the command
   line for gpsbabel.  gpsbabel is sensitive to UPPER and lower case 
   on the command line.  A simple command line to create PSP files
   looks like this:

   gpsbabel -i geo -f geocaching.loc -o psp -F NewOrleans.psp

   Note the use of "-f" for INPUT files and "-F" for OUTPUT files.
    

Q: I've created a PSP file, now what do I do with it?

A: To use pushpins in Pocketstreets, you need to have both a map and a
   pushpin file.  These two files must exist in the same folder and have
   exactly the same base name as the map.  For example, the pins that 
   correspond to the map "NewOrleans.mps" should be named "NewOrleans.psp".  


Q: I don't have a map?  What do I do now?

A: Create one using the "Export map to Pocketstreets" option in S\&T.  You
   can also pick up some major city maps on the web from the MS Pocketstreets
   website if you are interested in seeing how it works.


Q: I have .EST files, not .PSP files.  What's up with that?

A: In order to make PSP files, you need to use the "Export map to 
   Pocketstreets" function in S\&T.  .EST files are for use in S\&T, not 
   Pocketstreets.


Q: The .PSP files differ when I use gpsbabel/psp versus Pocketstreets to 
   create them.  What's up?

A: Pocketstreets makes corrections to the S\&T waypoint data upon initial 
   loading. gpsbabel/psp writes PSP files with these corrections already made.
   Ask MS.


Q: Does gpsbabel/psp work with (Autoroute, Mappoint, etc..) .PSP files?

A: As of this writing, I haven't seen any so I can't be sure.  If they 
   follow the same layout as S\&T 2002, I'd imagine so.


Q: Does gpsbabel/psp work with (S\&T 2001, S\&T 2002, etc...) files?

A: MS the file layout between S\&T 2001 and S\&T 2002.  The gpsbabel psp
   module is known to work fine with S\&T 2002 and 2003.


Q: Does gpsbabel/psp work with (insert your country/location here) maps?

A: If it doesn't, feel free to email the PSP files to me at:
   geo\_alexm at cox-internet.com.  I only had USA based data to work 
   with while figuring out the file layout.  Please include as much 
   information about the points as possible (lat/long, name, etc..)
   and do it in English.  I don't read or speak any other languages
   fluently.


Q: What do you mean S\&T writes points with the wrong coordinates?

A: At some point in the "Export map to Pocketstreets" function in S\&T,
   it goofs the lat/long data.  Points in Nashville tended to shift
   1.4 miles WEST of their original location.  I'm not a geometry buff,
   but I'd imagine they have a reference point for generating coordinates
   that's wrong in (at least) that area.


Q: I have 800 waypoints that cover a dozen or so Pocketstreets maps.  
   Do I need to to split my points up into smaller chunks to match the 
   area covered by the maps?

A: No.  Pocketstreets will "ignore" points that are outside of the map
   area.  Points that are not on the current map will be "grayed out"
   in pushpin explorer in Pocketsreets.  This is the reason the PSP 
   module was written for gpsbabel in the first place.


Q: Where can I find documentation for the layout of PSP files?

A: Just about everything I know about the PSP file format is documented 
   in the source.  To the best of my knowledge, there is no documentation 
   (and for good reason, I've come to discover). 


Q: I have some other problem, what do I do?

A: Email me at geo\_alexm at cox-internet.com and I'll see if I can 
   work it out.



\subsection{TIGER}

	The U.S. Census Bureau proives online mapping facilities.  This
	format is described at: http://tiger.census.gov/instruct.html.



\subsection{TopoMapPro}

        TopoMapPro Places File.  Reads and writes places files for use
        in TopoMapPro (http://www.topomappro.com).  As this file type
        can store links other than web links, anything that is not a
        http url will be discarded.  Note that this does not do datum
        conversions, so if your input file does not have WGS84/NZGD2000
        data, your output file won't either.
        Colour of waypoint icons defaults to red.



\subsection{National Geographic Topo! (TPG)}

	National Geographic Topo! Waypoint Format.  This filter 
	reads and writes .TPG files created by various editions of NG Topo! 
	This filter will *not* work with the newer combined .TPO files.  
	Contributed by Alex Mottram.



\subsection{XCSV}

XCSV is an open-ended "Whatever Separated Values" parser / writer
designed to work with user-supplied "style" files.  It should handle 
at least a few thousand of the billion CSV variants available.  
By itself, it doesn't comply to any format, however *most* CSV 
variants can be described as a "style" and fine-tuned by the end 
user.  For more information on it's use, please see README.style 
in the style/ sub-directory of gpsbabel.  For an example of using 
the XCSV module within your C program, look at the ozi.c, mxf.c, and
xmapwpt.c sources in the gpsbabel directory.  This module was 
contributed to gpsbabel by Alex Mottram.

Additional Options:
style	-	**REQUIRED** Path to XCSV style file.

snlen	-	Maximum length of synthesized shortnames. 
snwhite	-	Switch defining whether or not to allow whitespace
		in synthesized shortnames. 
		(0 = NO WHITESPACE, 1 = WHITESPACE OK).
snupper	-	Switch defining whether or not to force uppercase 
		in shortnames. (0 = LEAVE AS IS, 1 = UPPERCASE ALL).
	
NOTE:	sn* options require use of the '-s' command line option.

Example Usage:
{\tt \small
\begin{tabbing}
gpsbabel~\= -i geo -f 1.loc -f 2.loc \kill
gpsbabel \> -i gpsbabel -s -i gpx -f infile.gpx \bsl \+ \\
						-o xcsv,style=my.style,snlen=8 -F outfile
\end{tabbing}
}
{\tt \small
\begin{tabbing}
gpsbabel~\= -i geo -f 1.loc -f 2.loc \kill
gpsbabel \> -i xcsv,style=your.style -f infile \bsl \+ \\
						-o xcsv,style=my.style -F outfile
\end{tabbing}
}




\section{Format-independent data filtering options}

\gpsbabel\ supports data filtering.  Data filters are invoked from
the command line via the {\tt -x} option.  They are invoked in the order they appear on the command
line and can be used intermittently between several variations
of input and output functions.  It should also be noted that
filtering data from different input types can sometimes produce
undesirable results due to differences in the native data formats.



\subsection{POSITION}

The position filter is designed to remove points based on their
proximity to each other.  Distances can be passed on the command 
line by passing the distance=XXX option to the filter.  Distance
options may be expressed in feet (distance=3f) or meters 
(distance=1m).  The default is zero feet, essentially a duplicate
position.

For example:
{\tt \small
\begin{tabbing}
gpsbabel~\= -i geo -f 1.loc -f 2.loc \= \kill
gpsbabel \> -i geo -f 1.loc -f 2.loc \> \bsl \+ \\
						-x position,distance=1f  \> \bsl \\
	          -o mapsend -F 3.wpt
\end{tabbing}
}
would load two input files of the {\sc geo} type, remove multiple points that are within 1~foot of each other,
leaving just one, and finally would save a {\sc mapsend} type output file.



\subsection{RADIUS}

The radius filter is designed to include points based on their
proximity to a central point.  Distances and the central point 
are declared on the command line by passing the distance=X.XX,
lat=X.XX, and lon=X.XX options to the filter.  Distance options 
may be expressed in miles (distance=3M) or kilometers (distance=3K).
The default is zero miles.

For example:
{\tt \small
\begin{tabbing}
gpsbabel~\= -i geo -f 1.loc -f 2.loc \kill
gpsbabel \> -i geo -f 1.loc \bsl \+ \\
						-x radius,distance=1.5M,lat=30.0,lon=-90.0 \bsl \\
						-o mapsend -F 2.wpt
\end{tabbing}
}
would load a {\sc geo} input file, but include only points that lie within 1.5 miles of N\,30.000 ~W\,90.000~ into the {\sc mapsend} output file. 



\subsection{DUPLICATE}

The duplicate filter is designed to remove duplicate points based
on their shortname (traditionally a waypoint's name on the GPS
receiver), and/or their location (to a precision of 6 decimals).
This filter supports two options, "shortname" and "location".
Generally, at least one of these options is REQUIRED.

For example:
{\tt \small
\begin{tabbing}
gpsbabel~\= -i geo ... \kill
gpsbabel \>	-i gpx -f 1.gpx -f 2.gpx  \bsl \+ \\
						-x duplicate,location,shortname \bsl \\
         		-o gpx -F merged\_with\_no\_dupes.gpx
\end{tabbing}
}
would remove points that have duplicate shortnames *AND* duplicate
locations.  The result would be a GPX file that more than likely
contains only unique points and point data.



\section{GUI wrappers}
\label{GUI}

gpsbabelfront(.exe) is is a Windows front-end for GPSBabel.  It was contributed and is
maintained by Josh McKee.   It is written in Delphi. Figure~\ref{babelfrontfig1} shows a screenshot of it.

\begin{figure}[htb]
\hfil\psfig{figure=babelfront2.eps,width=0.8\textwidth}\hfil
\caption{Screenshot of the Babel frontend.}
\label{babelfrontfig1}
\end{figure}



\section{Power usage}

Argument are processed in the order they appear on the command line.
{\bfseries Input is cumulative}.  The input file type remains unchanged until a 
new -i argument is seen.  Files are read in the order they appear.  
So you could merge three input files into one output file with:
{\tt \small
\begin{tabbing}
gpsbabel~\= -i geo ... \kill
gpsbabel \> -i geo -f in-1.loc -f in-2.loc -f in-3.loc \+ \bsl \\
						-o geo -F big-out.loc
\end{tabbing}
}

You can as well {\bfseries merge files of different types}:
{\tt \small
\begin{tabbing}
gpsbabel~\= -i geo ... \kill
gpsbabel \> -i geo -f 1.loc \+ \bsl \\
						-i gpx -f 2.gpx \bsl \\
						-i pcx -f 3.pcx \bsl \\
						-o gpsutil -F big-out.gps
\end{tabbing}
}

You can {\bfseries write} the same data {\bfseries in different output formats}:
{\tt \small
\begin{tabbing}
gpsbabel~\= -i geo ... \kill
gpsbabel \> -i geo -f 1.loc \+ \bsl \\
						-o gpx -F out-1.gpx \bsl \\
						-o pcx -F out-2.wpt
\end{tabbing}
}



\section{Building it from source}

The source code should be compilable on any system with ISO C89 compilers.
It has been tested on UnixWare, OpenServer, OS/X, Linux, Solaris, and
a variety of further processors and compilers.

{\sc Libexpat} is required.   If you get errors about {\sc expat.h} being
missing, you must either edit the {\sc Makefile} to tell the compiler
where it is or install it in a sensible place.   Expat can be 
downloaded from http://expat.sourceforge.net. As part of Apache
it is very portable.



\begin{appendix}


\section{How to contribute}
\label{HowToContribute}

If you are interested in contributing to this program, here are some 
guidelines:

\begin{itemize}

\item The frontier development state can always be obtained from a publicly accessible CVS on Sourceforge: {\sc cvs.gpsbabel.sourceforge.net}. Check this CVS first before beginning your own enhancement efforts.

\item Please ensure that you are building and testing against the latest code
from the top of the CVS tree and that any code you modify is the latest
version from the CVS. Please remember: Code changes sometimes occur frequently!

\item Standards are good. ISO C and POSIX are greal preferred.

\item Reuse is OK, if doing so is not onerous.  For example, using the {\sc expat}
libraries vastly simplifies the XML parsers while increasing their
robustness plus those libraries are ubiquitous.  So I consider it OK to
require {\sc expat}.

\item Mail patches to {\bfseries robertlipe$@$usa.net} for consideration and
integration.

\item If you are creating a new target you should submit patches (use 
"cvs diff -uN" to create patches) to the following files:
	\begin{itemize}
\item Yourcode.c and/or Yourcode.h - this is the code required to do your
  conversions and any support files that your code requires.
\item vecs.c - an updated vecs.c file implementing your conversion code into
  GPSBabel.
\item Makefile - an updated Makefile telling the compiler how to build and link
  your conversion into GPSBabel
\item README - an excerpt for the README about your conversion and any  
  idiosyncrasies  it may have.
\item testo - an updated script that tests your conversion (this should produce
  no output if all is good, see the current testo script for examples)
\item YourOutput - a sample file of code produced by your function (used in testo
  and lives in a directory called "reference").
	\end{itemize}

\item Compilers complain for a reason. Code shouldn't emit warnings.

\item The entire world doesn't run just {\em $<$enter your favorite OS here$>$}. I've tested the present code on
five different OSes. If you find yourself wanting to insert compiler or
OS specific magic, please resist. We do not want to separate but to integrate.

\end{itemize}


\section{Magellan icon names}
\label{MagellanDefIcons}

The table shows the list of icon names available on a variety of Magellan receivers. The names may be used to define a default icon that will be displayed after uploading sets of waypoints to a respective receiver (see section~\ref{MagellanSerial}).

...


\section{Acknowledgements and contact addresses}



\section{Gnu general public license}
\label{GPL}

...

\end{appendix}
%============================================================
%\newpage
%\bibliographystyle{galphac}
%\bibliography{antrag}

\end{document}