# README
------------------------------------------------------------------------

 Please at least SKIM this document before asking questions. In fact,
 READ IT if you've never successfully set up Xastir before. PLEASE!
 READ IT! If you haven't read this file, and ask for help
 expect to be told to READ the README file first! or RTFM :)

 Contents:

 0.    Important notice
 1.    What is Xastir?
 2.    How do I get Xastir & Git usage
 3.    Quick startup
 4.    Upgrading
 5.    Identification notes
 6.    OS-specific notes
 7.    Gating weather alerts
 8.    Boring legal stuff
 9.    Mailing list
 10.   Documentation
 11.   Obtaining help

------------------------------------------------------------------------

0. NOTICE

   Please read this file carefully before trying to set up Xastir.
   This software was developed to be used by licensed amateur radio
   operators.  You are responsible for any information transmitted
   or propagated on any network.

1. WHAT IS XASTIR?

   Xastir is an open-source project to create a free X11 graphical
   APRS(tm) client. APRS(tm) use amateur radio and Internet services to
   convey GPS mapping, weather, and positional data in a graphical
   application.  It has been developed by and for amateur radio
   enthusiasts to provide real-time data in an easy to use package.

   Xastir currently runs under several flavors of Linux and BSD Unix.
   A few people are running Xastir on Solaris Unix, FreeBSD, Lindows
   and Mac OS X, but there may be small changes necessary in order to
   get Xastir to configure/compile on some systems.  There are a few
   notes below which may help in this task.  Most of the developers use
   Linux which makes it the best supported platform at the moment.

   Xastir is an open-source project: Most sources, documentation, and
   binaries are available under the GPL license, with a few modules
   available under other open-source or public domain licenses.

   More information on Xastir can be found here:

   * http://xastir.org
   * http://github.com/Xastir

   including the latest releases, Git access (lets you
   download the latest developers' code), and information on how to join
   Xastir mailing lists.  Note that you must be subscribed in order to
   post to the mailing lists.

   SmartBeaconing(tm) was invented by Tony Arnerich (KD7TA) and Steve
   Bragg (KA9MVA) for the HamHUD project.  They offer the algorithm to
   other authors as long as proper credit is given and the term
   SmartBeaconing(tm) is used.  Thanks to Tony and Steve for that
   contribution!

   -- The Xastir Group.

2. HOW TO GET XASTIR

   Xastir is currently developed at
   <http://github.com/Xastir/Xastir>
   You can get the latest version of Xastir from there.

   You might try <http://xastir.org> for help and information,
   particularly the Xastir mailing list (listed near the bottom
   of the page).

   * Git USAGE

     Obtain the *very latest* version of Xastir under development by
     using Git.

     See the file README.GIT for more details.

   * Release version tarballs

     You can get the latest packaged release source code without git
     at https://github.com/Xastir/Xastir/releases.  Be warned that packaged
     source tarballs may be quite old and not representative of the current
     state of the project.  We highly recommend not using this method unless
     you have a specific reason to stick to official releases.

3. QUICK STARTUP

   See README.Getting-Started for a relatively quick overview of how
   to build and use Xastir.

   Check the Xastir wiki (http://xastir.org) for OS-specific guidance
   for building Xastir on your system.

   WINDOWS USERS:  Please refer to the "README.CYGWIN" file for
   specific instructions.

   See the 'INSTALL' file in the Xastir source tree for detailed
   information about configure.

4. UPGRADING

   Upgrading Xastir that has been built from a recent Git clone
   is as simple as running "git pull" in the source tree and
   recompiling.

5. IDENTIFICATION NOTES

   Packet radio modes, by their very nature, typically identify
   themselves with every transmission. Xastir has a few features
   targeted to people who used Xastir in demonstrations and other
   broadcasts where Xastir itself is used over radio.

   Xastir can auto-ID via voice if Festival is compiled in and/or via a
   message splashed across the screen. It does this identification
   every 9.5 minutes if enabled. These identification modes were
   designed for broadcasting Xastir across fast-scan television (for
   events perhaps). Set the "ATV_SCREEN_ID" variable to 1 to enable the
   screen message, and "SPEAK_ID" variable to 1 to enable festival to
   speak the message. These variables are in the
   ~/.xastir/config/xastir.cnf file.

6. OS SPECIFIC NOTES

   [The OS-specific notes that were here were horribly outdated
   and not maintained.  That text has been removed.  Please
   see the Xastir wiki at http://xastir.org in the "Installation Notes"
   section for OS-specific build guidance.]

7. GATING WEATHER ALERTS, STATIONS, OBJECTS/ITEMS TO RF

   ## Gating NWS Weather Alerts to RF:

   If you wish to gate NWS weather alerts from the Internet onto RF, you'll
   need to create a text file in the users directory as
   ~/.xastir/data/nws-stations.txt
   List each NWS station that you would like to transmit via RF. Wildcards
   are implied for lengths of 3 or greater. Here's what an example file
   looks like:

       #
       # Seattle, WA
       SEANPW
       #
       # Portland, OR (any alert type)
       PDX
       #
       # Pendleton, OR
       PDTNPW
       #
       # Medford, OR
       MFRNPW
       #

   All text should start at the beginning of the line.

   Once that file is in place, you'll need to hook up to at least one
   Internet server that is feeding you the weather alerts. You'll also need
   to have at least one RF interface up and running with transmit enabled on
   that interface. Make sure that "Interfaces->Disable Transmit: All" is not
   selected.  You should now be gating NWS weather messages to RF.

   Turn on igate logging and look at that log file to view what you're
   sending out via RF. Don't forget to turn off logging or set up
   auto-rollover of the log files, else your hard drive might fill up with
   logging info. Auto-rollover of log files is typically accomplished via
   CRON.

   ## Gating Stations, Objects/Items to RF:

   The latest code also allows gating packets from specific stations to RF
   using the above method (except object/item packets).  You can also gate
   objects/items to RF by name.  The same wildcarding rules apply as listed
   above.  Callsigns or object/item names listed in this file are
   case-insensitive, so they'll match any case in received packets.

   Bob Bruninga, WB4APR, recommends gating these calls to RF:

    SCOUTS, SATERN, KIDS, REDCROSS, FOUR-H, YOUTH, GUARD, MARS, JOTA

   See his link: "Generic Callsigns for National Events" off this web page
   for his current list of recommended callsigns:

  http://www.aprs.org/aprs-jota.txt


8. BORING LEGAL STUFF

   Xastir is Copyright � by Frank Giannandrea. Xastir is
   distributed according to the GNU General Public
   License. There should be a copy of this license in the
   file COPYING. If not, write to the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA
   02139, USA.

   As of Xastir 0.4.0 all changes made by the Xastir
   development team to the Xastir source code and any related
   files are Copyright (C) 2000-2019 The Xastir Group. The source
   code will still be distributed according to the GNU General
   Public License as Frank Giannandrea did in the past.

   There is no warranty, implied or whatever. You use this
   software at your own risk, no matter what purpose you put
   it to.

   You didn't pay for it, so don't expect magic.


9. MAILING LIST

   There are currently a couple of mailing lists about Xastir.
   xastir@xastir.org is the one relevant for most users.

   The xastir@xastir.org mail-list is dedicated to Bug
   reports, technical questions, your thoughts or
   suggestions on new features being added to Xastir, things
   that should be removed or fixed, amazing problems that even
   stump the guru's, etc... are what we want to see here.  You
   must be subscribed to the list in order to post messages.

   To subscribe to the Xastir mailing list, send email to:
   xastir-request@xastir.org In the body of the message,
   put "subscribe xastir"; or go to
   http://xastir.org and click on "XASTIR MAILING LISTS" (in the
   "Resources" section near the bottom) to subscribe.

        ### DO NOT SEND FRANK EMAIL ABOUT XASTIR ###

   Frank is no longer developing the Xastir code (although
   he does put a word in every now and then) so don't bother
   e-mailing him. If you have a serious problem, email the
   Xastir mailing list and it will get to the coders.

   Please, before posting to this list, see what things are
   like, and when you do post, read over your post for
   readability, spelling, and grammar mistakes. Obviously,
   we're all human (or are we?) and we all make mistakes (heck,
   look at this document! ;).

   Open discussion and debate is integral to change and
   progress. Don't flame others over mere form (grammar and
   spelling), or even substantive issues either for that
   matter. Please read and follow the mailing list rules.

   A second mailing list, xastir-dev@xastir.org is intended for
   developer's discussion.

10. DOCUMENTATION

    We're trying to get the documentation up to date. If you
    feel that anything is missing here, or that anything should
    be added etc, please email xastir@xastir.org about it,
    thank you.

11. OBTAINING HELP

    Please read the file FAQ, and make sure you've followed any relevant
    instructions in INSTALL. If the problem still exists, feel free to
    ask on the Xastir mailing-list, as described above.


  ------------------------------------------------------------------------
APRS(tm) is a Trademark of Bob Bruninga

Copyright (C) 1999 Frank Giannandrea
Copyright (C) 2000-2019 The Xastir Group

November 2017 Update

This document offers a method of running Xastir on Windows using
the Cygwin environment.  Cygwin is a large collection of GNU and
Open Source tools which provide functionality similar to a Linux
distribution on Windows.

Microsoft now offers their own Linux solution, using an Ubuntu
Linux framework that runs under Windows.  However, you must be
running a 64 bit version of Windows 10 to use the Microsoft option.
More information may be found in the Xastir Wiki at:

http://xastir.org/index.php/HowTo:Win10

------------------------------------
Installing Xastir on Windows/Cygwin:
------------------------------------

These directions were most recently validated on Windows 10, both 32
and 64 bit, with Cygwin version 2.882.

SPACES IN FILENAMES/USERNAMES:  Cygwin specifically, and Unix boxes in
general, don't much like spaces in filenames, directories, or login
names.  Any of these may cause you headaches while playing with Cygwin.
Create a new login that doesn't have spaces and log in as that user
before installing Cygwin, and whenever you intend to run Cygwin/Xastir.
It's very likely that Xastir won't work for you if you use a login that
has spaces embedded in it.  For additional info, see this link:

   https://cygwin.com/faq/faq.html#faq.using.filename-spaces

The following steps direct you through installing Cygwin, Xastir, and
a few optional map libraries that Xastir can use.  Note that in most
of the places below where the directions state to type commands, this
must be done from within a Cygwin BASH shell, not a DOS window.
Where you are asked to edit files, it's best to use Wordpad instead
of Notepad, as Notepad doesn't do nice things to Unix-format files.

Cygwin now allows you to have Xwindows apps and Windows apps all on
the screen and visible at the same time!  The instructions here set
it up in that manner, so you can have Xastir as just another app on
your Windows desktop.

Please subscribe to the "xastir" mailing list at "http://xastir.org".
There are lots of helpful people there that can aid you in
installing/running Xastir.  You must be subscribed in order to post
messages there.

[ ] Step 1)  Install Cygwin, a free download.

[ ] Step 1a) Go to https://cygwin.com/install.html with your web browser.
Choose the 64 bit or 32 bit version as appropriate for your Windows
operating system.

This will download the Cygwin network installer program onto your
computer.  Remember where you decide to put this program.  I put
mine in my user "Downloads" folder.

Note: It will be beneficial to re-run the Cygwin network installer
from time to time in order to keep Cygwin up to date.  Each time you run
it you'll update any packages that have been changed since you last ran
it.

[ ] Step 1b)  Find the "setup-x86.exe" program (32 bit) or the
"setup-x86_64" (64 bit) program.  Make note of which version you are
using.

Open a Windows Command Prompt as the Administrator and change directory
to the directory where you just saved the setup program.

If you have setup-x86.exe (32 bit), run this command to download
and install the needed Cygwin components:

setup-x86.exe --quiet-mode --packages autoconf,automake,binutils,^
db,font-util,gcc-core,git,GraphicsMagick,gv,libcurl-devel,libdb-devel,^
libgeotiff,libgeotiff-devel,libjasper-devel,libjbig-devel,^
liblcms2-devel,libpcre-devel,libshp-devel,libtiff-devel,libwebp-devel,^
libwmf-devel,libxml2-devel,libGraphicsMagick-devel,libX11-devel,^
libXext-devel,libXm-devel,make,nano,sox,unzip,wget,xfontsel,xinit,^
xorg-x11-fonts-Type1,xorg-x11-fonts-dpi100,libbz2-devel,libproj-devel

If you have setup-x86_64.exe (64 bit), run this command to
download and install the needed Cygwin components:

setup-x86_64.exe --quiet-mode --packages autoconf,automake,binutils,^
db,font-util,gcc-core,git,GraphicsMagick,gv,libcurl-devel,libdb-devel,^
libgeotiff,libgeotiff-devel,libjasper-devel,libjbig-devel,^
liblcms2-devel,libpcre-devel,libshp-devel,libtiff-devel,libwebp-devel,^
libwmf-devel,libxml2-devel,libGraphicsMagick-devel,libX11-devel,^
libXext-devel,libXm-devel,make,nano,sox,unzip,wget,xfontsel,xinit,^
xorg-x11-fonts-Type1,xorg-x11-fonts-dpi100,libbz2-devel,libproj-devel

[ ] Step 1c) Choose a Download Site and then click Next.

[ ] Step 1d) The Select Packages screen will display.  You don't have
to actually select any, the right packages have been selected for you.
But, if you wish, you can review the selection and make changes if you
know what you are doing.  Click Next and the Resolving Dependencies
screen will display.

[ ] Step 1e)  Click Next and the packages will get downloaded and
installed.  Repeat the above if you have network difficulties, until
the install succeeds completely.


In addition to the base packages, the following packages required to
compile and run Xastir, along with their dependencies, will be installed.

[ ] autoconf
[ ] automake
[ ] binutils
[ ] db
[ ] font-util
[ ] gcc-core
[ ] git
[ ] GraphicsMagick
[ ] gv
[ ] gzip
[ ] libbz2-devel
[ ] libcurl-devel
[ ] libdb-devel
[ ] libgeotiff
[ ] libgeotiff-devel
[ ] libjasper-devel
[ ] libjbig-devel
[ ] liblcms2-devel
[ ] libpcre-devel
[ ] libproj-devel
[ ] libshp-devel
[ ] libtiff-devel
[ ] libwebp-devel
[ ] libwmf-devel
[ ] libxml2-devel
[ ] libGraphicsMagick-devel
[ ] libX11-devel
[ ] libXext-devel
[ ] libXm-devel
[ ] make
[ ] nano (a windows-style text editor, optional)
[ ] patch
[ ] sox
[ ] unzip
[ ] wget (Optional: Can use libcurl instead)
[ ] xfontsel
[ ] xinit
[ ] xorg-x11-fonts-Type1
[ ] xorg-x11-fonts-dpi100


[ ] Step 1f) You may receive a Postinstall script errors screen.
It is not necessarily an issue, but you are advised to check the
contents of /cygwin/var/log/setup.log.full or
/cygwin64/var/log/setup.log.full.  Click Next to proceed.

[ ] Step 1g)  At the end of the install it'll ask you if you wish to
create desktop icons and menu entries.  Definitely select these!  It
doesn't mean that Cygwin will start automatically each time you
reboot your computer or login (it doesn't start automatically).  It
_does_ mean that you'll have an icon to click on manually to get
things going.

This will create a Black/Green Cygwin icon on the desktop and a menu
entry so that you can start Cygwin through the menu system as well.

[ ] Step 1h) Click "Finish".  Cygwin is now installed.  One more
pop-up informs you Cygwin has been installed.  Sometimes this last
dialog gets hidden behind other windows, and it does seem to need OK
clicked to complete the installation.  Click the OK button on that
last dialog to _really_ complete the installation.  The Command
Prompt in the window will not return.  When it prints "Ending Cygwin
install" it is done.  You can press enter and the prompt will
reappear.

The Black/Green Cygwin icon will start up a BASH window, without
starting up Xwindows.  Think of it as being similar to a DOS window,
but with a lot more power.  It understands Unix commands though, not
DOS commands.

[ ] Note:  I've had the Cygwin network install fail before during
the downloading stage without informing me in any recognizable
manner.  You might want to re-do step 1 to make sure nothing
further gets downloaded/installed.  Once you get to that point, Step
1 is complete.

[ ] Step 2)  Start the X Server:

Click on the Windows menu icon or press the Windows button.  Look for
the Cygwin-X program group and click on the XWin Server.  It will create
a green "X" icon in the system tray.

Right-click on green "X" icon in the system tray.  Select Systems Tools,
and then Cygwin Terminal.

[ ] Step 3)  Test Cygwin and create startup shortcuts:

You should get a shell window that looks very much like a DOS window.
It's a BASH shell window and understands Unix commands instead of DOS
commands.

Once you've gotten to this stage, you now have Cygwin and Xwindows
installed and operational.  Next we go after Xastir itself.

[ ] Step 4)  Download Xastir sources.  Use the Cygwin Terminal window
that you just started.  Type the three lines below into the shell exactly
as shown.

  mkdir git
  cd git
  git clone http://github.com/Xastir/Xastir

The end result when it succeeds will be a new directory "~\git\Xastir\"
which contains all of the Xastir source code.  You can type "ls Xastir"
(that's lower-case LS) to see the file listing.

Side Note:  Here's the coolest thing about Git:  Once you've done
this initial source-code download, you'll never have to do the whole
Xastir download again.  You'll just go into the "git/xastir"
directory and type "git pull", which will snag just the _changes_
to the files since you last updated, and is very fast.  Compile and
install at that point and you'll be running the latest developer's
version in just a few minutes!  It's very easy to keep up with the
developers this way.

[ ] Step 5)  Configure/compile/install Xastir.  Type these commands
into the BASH shell, waiting until each one completes before typing
the next command:

    cd ~/git/Xastir
    ./bootstrap.sh
    mkdir -p build
    cd build
    ../configure
    make
    make install-strip

NOTE:  You'll probably want to run the configure step from an xterm
window with the X11 server running of course.  If you do this from a
non-X11 window then the configure test for "gv" will fail, as "gv"
requires an X11 server even when asking it for it's version number.
Without "gv" support you won't be able to print from Xastir.

Once you get through the above commands, Xastir is compiled and
installed on your system, with minimal map support.  Later sections
of this document detail adding additional map libraries in order to
give you access to the full mapping capability of Xastir.

---------------------------------------------------------------------

[ ] Step 6)  Actually run the darn thing:

Let's start from scratch to make sure it all works.  Close any
Cygwin/BASH windows you may have.

Click on the shortcut you created to start Xwindows.

From the resulting BASH window, type "xastir &".  Xastir should
start up shortly.

As built, using this documentation, the following map types are
supported.

Built-in map types:
      gnis   USGS GNIS Datapoints
       pop   USGS GNIS Datapoints w/population
       map   APRSdos Maps
       map   WinAPRS/MacAPRS/X-APRS Maps

Support for these additional map types has been compiled in:
       geo   Image Map (ImageMagick/GraphicsMagick library, many
                        formats allowed)
       geo   URL (Internet maps via libcurl library)
       geo   URL (OpenStreetMaps via libcurl library
                  Copyright OpenStreetMap and contributors, CC-BY-SA)
       shp   ESRI Shapefile Maps (Shapelib library)
       tif   USGS DRG Geotiff Topographic Maps (libgeotiff/libproj)
       xpm   X Pixmap Maps (XPM library)

The README.MAPS file has instructions for where to get maps and where
to put them under the Xastir hierarchy.

If you have any WinAPRS, DosAPRS, or PocketAPRS maps, now is a good
time to place them in the /cygwin/usr/local/share/xastir/maps folder
(or a subdirectory of it).  You can also use "*.geo" files and the
associated image files with Xastir.  You may place them in this
directory (or a subdirectory of it) as well.

FILESYSTEM PATHS (WINDOWS VS CYGWIN):

From Windows, just prefix all paths with "/cygwin" or "/cygwin64" as
appropriate.  For instance, maps go into /cgwin/usr/local/share/xastir/maps
instead of /usr/local/share/xastir/maps.  Xastir will continue to see
them as "/usr/local/share/xastir/maps" though from inside Cygwin.  It kind
of looks like a miniature Unix box from inside Cygwin.

LANGUAGE OPTIONS:

To set a new language or change the language current choice, use
this command line instead from inside an Xterm:

     xastir -l <language>

Current choices are:

    Dutch English French German Italian Portuguese Spanish
    ElmerFudd MuppetsChef OldeEnglish PigLatin PirateEnglish

This option will be stored in the users config file for the next
time Xastir is run. On new installs Xastir will default to English
until you use this command line option once.

CYGWIN vs LINUX/UNIX:

Another difference with Cygwin as opposed to Unix-like operating
systems:  You can't do the make install portion if Xastir is up and
running.  You have to kill Xastir first before you do "make install"
or "make install-strip".  Otherwise the newly compiled Xastir won't
replace the old one.

Another interesting "feature" of Cygwin/Xwindows is that some of the
modifier keys like ScrollLock/CapsLock/NumLock must be pressed while
that X-window is the active foreground window.  If not, the event
can be missed, and Xwindows can get out of sync with the actual
state of the key.  This doesn't appear to be an Xastir-specific
problem, but a Cygwin/Xwindow problem.  With just a BASH shell under
Cygwin (not involving Xwindows), the problem doesn't appear to
happen.  Just inside Xwindows on Cygwin.

When specifying serial ports to use with Xastir,

    "COM1" is called "/dev/ttyS0" in Cygwin (and Linux)
    "COM2" is called "/dev/ttyS1" in Cygwin (and Linux)

Note the capital 'S'.

OPTIONAL

Please see the INSTALL file and the Help menu in Xastir itself
for additional information not mentioned in this document.

Additional info can be found on the cygwin web-site:

    http://www.cygwin.com

or the Cygwin/XFree86 web-site:

    http://cygwin.com/xfree/


Keeping up-to-date:

Once a week or once a month, run the Cygwin network installer
program (setup-x86.exe or setup-x86_64.exe).  After it finishes,
open a Cygwin terminal window and type these commands to update the
Xastir source code:

    cd ~/git/xastir
    git pull

Every once in a while Windows will refuse to allow you to
delete/rename one of the files.  The only way I've found to get
around this problem is to reboot.  I sometimes see this when trying
to do a "git pull", and Windows won't allow one or more files to get
updated.

You can now repeat step 5 to update Xastir.

-------------------------------------------
OPTIONAL:  ADDING ADDITIONAL MAP LIBRARIES:
-------------------------------------------

These additional Xastir libraries have been tested on Cygwin:

    ImageMagick (no need to use if using GraphicsMagick)
    Festival

Anyone testing additional libraries is encouraged to share their
findings on the Xastir mailing lists (you must be subscribed in
order to post messages there).  The libraries which have _not_ been
made to work yet on Cygwin are:

    AX25
    GPSMan/gpsmanshp

The AX25 libraries will probably never work, as they are for Linux
only.  GPSMan/gpsmanshp may work on Cygwin at some point if enough
work is done to figure out and document the process.


OPTIONAL:  Install Festival support:
------------------------------------

Note: The most recent version of Festival is 2.4.  According to the
README for this version, "Do NOT use Windows with Cygwin".  With that
warning up front, here are instructions that were previously used to
make a legacy version of Festival work with Xastir.  They were not
revalidated during the November 2017 update to this document.

Allows using a synthesized voice from within Xastir for alerts,
reading messages to you, and other cool things.  Tom Russo did the
initial work on this, Henk de Groot optimized it:

1) Start BASH shell in Cygwin

2) Make ~/festival download directory and
    /usr/local/festival installation directory

3) Download festival components from festvox.org into ~/festival, in
   the Windows environment the corresponding path is:

     C:\Cygwin\home\%USERNAME%\festival

    get the following files:

     speech_tools-1.2.95-beta.tar.gz
     festival-1.95-beta.tar.gz
     festlex-CMU.tar.gz
     festlex-POSLEX.tar.gz
     festvox-kallpc16k.tar.gz

4) Build festival and company:

    cd /usr/local/festival
    tar xzf ~/festival/speech_tools-1.2.95-beta.tar.gz
    tar xzf ~/festival/festival-1.95-beta.tar.gz
    tar xzf ~/festival/festlex_CMU.tar.gz
    tar xzf ~/festival/festlex_POSLEX.tar.gz
    tar xzf ~/festival/festvox_kallpc16k.tar.gz

    cd speech_tools
    ./configure && make
    cd ../festival
    ./configure && make

   These packages are build and used where they are compiled.

5) Test festival:

    cd /usr/local/festival/festival/examples
    sh saytime

   Festival should say the time if everything went fine

6) Add /festival/festival/bin to PATH in .profile and .bashrc. For
   me both files look like this:

    .profile and .bashrc:
    -------------------
    export PATH=$PATH:/lib:/usr/lib:/usr/X11R6/lib:/usr/local/lib:/usr/local/bin:/usr/local/festival/festival/bin:~/bin:.

    -------------------

7) Configure and build xastir.  Configure should report that
   festival is found.

8) Start the festival server:

    festival --server &

   To do this automatically I added the following lines to my
   .bash_profile:

    -------------------
    if  [ `ps -ef | grep festival | wc -l` -eq 0 ]
    then
      festival --server &
      sleep 1
    fi
    -------------------

9) Run xastir, do File->Configure->Speech, add things to say, and
   listen.



OPTIONAL:  How to make Sound Alerts work under Cygwin:
------------------------------------------------------

There is currently (November 2017) a problem using sound alerts
under Cygwin.  It is recommended that sound alerts are turned off
within Cygwin or you may experience lockups.

You'll need to add the .wav files to Xastir.

git clone http://github.com/Xastir/Xastir-sounds

cd Xastir-sounds
cp -r sounds/* /usr/local/share/xastir/sounds/


November 2017 documentation updates by K2DLS.  There may be
out-of-date items that remain in this document.  Please report
issues via the Xastir mailing list.

APRS(tm) is a Trademark of Bob Bruninga

Copyright (C) 2000-2019 The Xastir Group

Git Instructions:
-----------------

    For those who think git might be a bit too complicated to deal with,
    here are (I think) the minimal commands. See the "SUDO" section in
    README.sudo for ideas to make updating Xastir even simpler.


USERS:
------

    Initial Copy (Git Clone):
    -------------------------

    0) Make sure git is installed on your system.

    1) Run
        git config --global user.name "Your Name" user.email "Your@email.address"

        The above is not strictly necessary, but if you ever try to make changes
        to Xastir and get them integrated with the project it is important.

        NOTE: If you already have a different git global config, you can create
        a local config for a particular repo by going into that repo and doing:
        git config --local user.name "Your Name" user.email "Your@email.address"

        Check the config by:
            git config --local -l
            git config --global -l
            git config -l   # Doesn't differentiate between global and local though!

    2) Go to <http://github.com/Xastir/Xastir> to access the project page.
        There you will find the URL of the git repository, just to the
        right of a button that says "HTTPS". Copy this URL to your clipboard.

        (At the time of this writing, the URL was
         <https://github.com/Xastir/Xastir.git>)

    3) Open a shell, navigate to a directory where you want to store
        the Xastir source code, and enter this command:

        git  clone https://github.com/Xastir/Xastir.git

        This will create a clone of the Xastir git repository in an
        "Xastir" subdirectory of the current directory.

    All done!  You now have the latest development sources on your computer.
    Not only that, you have a complete copy of the entire project history
    and access to all prior releases.

    4) Please set your default git commit message template for the project to
       the one included in the Xastir source tree:

       cd Xastir
       cp git_commit_message_template ~
       git config --global commit.template ~/git_commit_message_template

       This will assure that when you make commits, your editor will start
       with a template that helps guide you through the process of writing
       commit messages that conform to the guidelines below in the section
       titled "Important: Git Commit Message Format".  This template is quite
       generic and conforms to the guidelines of many other open source
       projects, so it is reasonable to make it a global git option.

    Updating Your Copy:
    -------------------

    cd Xastir
    git pull           # Update your local repo (May be dangerous for developers)
    ./bootstrap.sh
    mkdir -p build     # Build in a separate directory
    cd build
    ../configure
    (make clean;make -j3 2>&1) | tee make.log
    sudo make install  # "make install-strip" can be used after the first
                       # time: It removes debugging info from executable
    sudo chmod 4555 /usr/local/bin/xastir  # Only needed if using kernel AX.25
    xastir &   # Start it up!

    Note that you'll need autoconf 2.53 or newer and automake 1.6.3 or newer
    in order to run the "./bootstrap.sh" script.

    -or-

    Bypass all of the commands above and just type:
        cd Xastir
        ./update-xastir


   PLEASE NOTE: Bootstrap.sh is used by both methods above, even
   "update-xastir", which is simply a script that performs all the
   steps listed explicitly earlier.

   The bootstrap.sh script is what creates the configure script.
   Running bootstrap.sh requires having autoconf and automake
   installed, and it will fail if these are not installed.  If
   bootstrap.sh fails, configure won't exist.  If bootstrap.sh fails,
   stop, fix the problem and try again.  There is no point continuing
   if bootstrap.sh gives you error messages about programs not being
   found (aclocal, autoconf, automake).

   This is a common problem reported to the Xastir team, and its solution
   is always the same:  install all prerequisite tools before trying to
   build Xastir.

DEVELOPERS:
-----------

    Initial Checkout:
    -----------------

    HTTPS Method:
      git clone https://github.com/Xastir/Xastir

    -or-

    SSH Method. Add keys to GitHub and then:

      git clone git@github.com:Xastir/Xastir

    Note that using the SSH method means that you won't have to answer the
    popups for user/password each time you do anything with the remote repo,
    although you will have to enter a passphrase if you added a passphrase to
    your SSH key. The SSH method is highly recommended for active developers!


    Normal Development Flow:
    ------------------------

    A pull before committing can be dangerous, if there are substantial
    conflicts between your work and others (not very likely with Xastir, but
    definitely likely in bigger projects). It is much better to do a fetch
    (which pulls down changes from the remote but DOESN'T merge them into your
    tracking branch), then look at what changed upstream, and then either a
    merge, rebase, stash/pop, or something else depending on the level of
    conflict you see. See README.GIT.

    Doing a pull before starting your own work is reasonable, but if someone
    pushes while you're working (again, not very likely with Xastir), you can
    still wind up with really ugly history, with weird merge commits and
    undesired branching.

    On the other hand, if you replace "git pull" with "git pull --rebase" in
    that recipe, with the caveat that sometimes you might have to be more
    careful and that you need to understand what you're doing, a lot of the
    danger of the simple git pull can be avoided.

    We will often be working on a branch for development, then merging that
    branch with the trunk when that feature or bug-fix is ready for prime-time.

    Commit your work to your LOCAL repo:

       - First add all desired changes to the staging area:
           git add <file1>  <file2> <file3> ...

       - Then commit your staged changes to your local repo

          git commit

    Push your local repo changes up to GitHub when you are ready to
    publish them:

       git push


    Important: Git Commit Message Format
    ------------------------------------

    Git commit messages need to be in a certain format to make the best use
    of the "git log" commands. In particular the first line needs to be 50
    chars or less, then a BLANK LINE, then a detailed commit message. See
    this link for more info:

    http://chris.beams.io/posts/git-commit/


    Checking Out A Branch:
    ----------------------

    All branches associated with the Xastir project are contained in the clone
    you made earlier. You can switch your current working directory to
    one of those branches easily:

    cd Xastir
    git fetch (this updates your local repo copy from github, but doesn't
               merge changes into your working tree)
    git checkout <branch name>    (this switches all the files in your working
                                   tree to match those in the branch)
    git merge                     (This makes sure that all the changes that
                                   may have happened upstream on that branch
                                   get into your copy)

    You do not have to do this in a new directory --- so long as
    you haven't changed any files in the source tree, git checkout
    automatically swaps out all files it knows about with versions from the
    branch.

    If you really want to keep more than one branch's code around to work on,
    you can do that if you have git version 2.5 or later with the following
    commands:

    cd Xastir
    git worktree add <path> <branchname>

    This will create a new directory tree called <path> with the named
    branch checked out into it.

    In early 2018, there is only one active branch, the master branch,
    and we will be performing releases by creating release branches.

    There are many more git commands and options. Many of them are more of
    use to the developers. Some of those are listed below. The above should
    be enough for most people to keep their copies in sync with the latest git
    development sources.


    If Using Multiple GitHub Accounts:
    ----------------------------------

    You may have trouble getting your commits attributed to the correct GitHub
    login. GitHub uses the username/email in your git config settings for
    attribution. If it is wrong, you may have to do some of the below in order
    to set a LOCAL username and email for the one repository.

    The user.name and user.email are pulled from the global git config, but a
    local git config inside each repo will override those settings.

    Go to root of checked-out repo and set local user.name and user.email for
    this repo:

       git config user.name <github username>
       git config user.email <email address>
       git config -l           # Shows both local and global settings, hard to tell which is which
       git config --global     # Shows global settings
       git config --local -l   # Shows local repo configs, so should show new settings

    Another method (but more error-prone) of editing local/global git config is:

       git config edit             # Edit local config
       git config --global edit    # Edit global config

    If new commits still aren't using the right email, make sure you have not
    set GIT_COMMITTER_EMAIL or GIT_AUTHOR_EMAIL environment variables.


    More Info:
    ----------

    Make sure you know how git works. Read https://git-scm.com/book/en/v2

    If you are very familiar with CVS, get used to working differently, because
    git is different.

    Read and understand http://chris.beams.io/posts/git-commit/

    Read http://justinhileman.info/article/changing-history/

    Read http://think-like-a-git.net/

    Read "Visual Git Cheat Sheet" at http://ndpsoftware.com/git-cheatsheet.html

    Branching and merging in git is very simple, and is documented very well
    by all those links. We will not repeat it here.

    If you use SSH, set up your SSH keys on GitHub and do the "git clone" using
    the SSH path. This will save you having to put in your password each time
    you use the remote repository, although if you added a passphrase to your
    SSH key you'll have to enter that each time.

    Useful Git Commands:
    --------------------

    Set up global user/email
        git config --global user.name "Your Name"
        git config --global user.email "user@domain.com"

    Set up user/email for a local repository
        cd /path/repository
        git config user.name "Your Name"
        git config user.email "user@domain.com"

    Configure Git's editor:
        git config --global core.editor /path/to/editor

    Colorizing Git output (set once and forget):
        git config --global color.ui auto

    Clone a repo:
        git clone http://github.com/Xastir/Xastir
        git clone https://github.com/Xastir/Xastir
        git clone git@github.com:Xastir/Xastir

    Status of local repo:
        git status

    Diff for a file:
        git diff <filename>

    See all branches, local and remote:
        git branch -a

    Visual Git viewer:
        gitk (tcl/tk and generic X11 viewer, comes with git)
        or
        gitg (gnome git viewer)

    Add files to the staging area:
        git add <file1> <file2>

    Commit changes to LOCAL repo:
        git commit      # If have files in staging area already
        git commit <file1> <file2>  # Ignores staging area

    Push local changes to remote repository:
        git push

    Update local repo from remote repo
        git fetch

    Update local repo and merge remote/local changes in local repo (May be
    dangerous for developers with modified code in their working tree):
        git pull

    Rebase local changes against latest master branch
        git fetch
        git rebase master


------------------------------------------------------------------------
Copyright (C) 2000-2019 The Xastir Group

Hello new user, and welcome to Xastir!


This document will take you through the steps necessary to get
Xastir up and running in one of the following configurations:


1) Minimal install, which will get you up and running quickly.  It's
   recommended that you try this configuration first then add to it.

2) Typical install including maps, weather alerts, geo-coding files,
   etc. so that full regular operation is achieved.

3) Maximum install with all configure options enabled and most of
   the useful maps loaded/enabled.  All the bells and whistles.


Note that you can start with either of the first two options and add
only the options you wish in order to come up with your own custom
configuration of Xastir.

These instructions are written for Linux users.  Windows users
should refer to the README.CYGWIN document instead.

Users of other operating systems should refer to the README document
first, then the INSTALL document and the below instructions for
further notes, and finally the Installation Notes section of the
Xastir wiki at http://xastir.org/.  Linux users may also benefit from
reading the Installation Notes section of the wiki, because each
distro of Linux has its own quirks, and many of those quirks are
documented on the wiki.

One question you might ask is whether you can just find a binary on
the 'net somewhere and install it instead of compiling Xastir from
sources.  Yes, this is possible, but not what most Xastir users
ultimately want.  Xastir changes often enough (bug fixes and of course
adding new features) that you're really limiting yourself by using
pre-compiled binaries.  Binaries are typically not updated all that
often, if at all, so you'll forever be behind the curve.  Most
packaged versions of Xastir in package management systems tend to be a
couple of years out of date, or even worse.

Another reason to compile from sources is to customize it to use all
of the features you have available on your system.  As you add more
libraries that Xastir can use, you can do a quick
configure/compile/install and Xastir will be able to take advantage
of them.

For those that really must have the latest-latest:  Download the
Xastir sources using Git instead, then issue the command "git
pull" periodically in order to snag the latest changes.  If
anything comes down the pipe, just configure/make/install and then
use the latest version.  This avoids large file downloads (after the
initial download) as it just grabs _changes_ to the sources off the
'net each time you issue the "git pull" command.  This is the
power-user's method of keeping Xastir up-to-date.  See README.GIT
for details.

After the three configuration sections there's a section on
operating, which simply talks you through the initial configuration
settings and how things work.  After that you can refer to the Help
menu option in Xastir itself, plus the INSTALL and README.* text
files for additional information.  Please note that the non-English
help files lag severely behind the English help file.

First of all, NEVER RUN XASTIR AS THE ROOT USER!  You're risking the
security of your system by attempting it.  Create another regular
user on your system and use that user for all of your normal
activity.  This goes for any other normal activity on the system as
well.  Only use the "root" account for maintenance activities, not
for regular user activities.  You'll thank me later!

Before we begin, consider subscribing to the Xastir mailing list.
That's where everyone is kept up-to-date on the latest features,
plus lots of questions are asked/answered there on a weekly or
sometimes daily basis.  It's a great way to learn and to stay
connected with the other Xastir users.  See the mailing links on the
left of the Xastir home page:  http://xastir.org
You must be subscribed in order to post messages there.

So...  Let's get started!


--------------------------------------------------------------------
--------------------------------------------------------------------


Latest info:

*) Xastir starts up with a default world map the first time you run
it plus pops up a dialog where you can enter your callsign.  Enter
a callsign, then close/restart Xastir or save the configuration via
"File->Configure->Save Config Now!".  Either of these methods saves
the callsign to disk.

*) Xastir includes "Shapefile" map capability by default.  Run the
script:

    "/usr/local/share/xastir/scripts/get-NWSdata"

as root to download/install NOAA Shapefile maps using the "wget"
utility.  You'll of course need wget installed in order to fetch the
files using this method.  Installing the NWS files enables weather
alert support in Xastir.  Verify that "Map->Enable Weather Alerts" is
selected and that "Map->Disable All Maps" is _not_ selected, else
you won't see weather alerts on your screen.


--------------------------------------------------------------------
--------------------------------------------------------------------


Sources of help you may find useful:

*) "FAQ" file

*) "INSTALL" file:  Non-Windows instructions for installing Xastir
   and optional map libraries may be found here.

*) "README.md" file:  General info and some OS-specific notes.

*) "CONTRIBUTING.md" file:  Info on how to contribute to the
   Xastir project.

*) "README.GIT" file:  Info on a more advanced way to keep up-to-date
   on the latest Xastir sources.

*) "README.Getting-Started" file:  The file you're reading.

*) "README.MAPS" file:  Much of the info about maps and where to get
   them may be found here.  Also see the Xastir Documentation
   section, the Wiki pages, at <http://xastir.org>

*) "README.CYGWIN" file:  For Windows/Cygwin users.

*) "UPGRADE" file:  Useful info for updating some old versions of
   Xastir.

*) Xastir Web-based documentation, including a set of Wiki pages,
   found at <http://xastir.org>

*) Xastir man page, accessed by typing "man xastir" on a Unix or
   Unix-like system.  This page is a bit out-of-date.

*) "Help->Help Index" in the Xastir program itself.  Note that only
   the English language variation of this is even approximately up-to-date.

*) Mailing lists at <http://xastir.org>

*) User forums at <http://xastir.org>


--------------------------------------------------------------------
--------------------------------------------------------------------


Minimal Install:
----------------

First, let's describe it:  This will get Xastir up and running with
a few built-in map types.  You'll be on the air or on the 'net
quickly, then can build upon this working base to add more map
libraries and other cool features later.


Getting the package:
--------------------

*) Option 1: Download one of release tarballs from
http://xastir.org.  There are links from that page or you can go to
the github site (https://github.com/Xastir/Xastir) and click on "Releases"
to see the entire set that is available.

Once you have the file (which will generally be called
"Xastir-Release-<number>.tar.gz," create a subdirectory for it to
reside.  I usually do this:

    cd                      # Go to my home directory
    mkdir src               # Make a "src" subdirectory
    cd src                  # Change to it
    mkdir xastir            # Make an "xastir" subdirectory
    cd xastir               # Change to it
    cp /path/filename .     # Copy the downloaded file here
    tar xzvf filename       # Un-archive the sources

That last step will create a directory called
Xastir-Release-<release number> underneath the first one, so
your full path might be something like (starting at your home
directory): ~/src/xastir/astir-Release-2.1.0

The path just listed is where you'll go in order to run the
configure and make commands listed below.

    cd  ~/src/xastir/Xastir-Release-2.1.0

from an xterm window should take you there.

*) Option 2: An alternative is to use Git to snag the sources for you.
Using this method you can periodically update to the latest released
version, the latest "stable" version, or the latest development
sources, and even switch back and forth between them at will.  See README.GIT
for info about that option.  One of the advantages of Git is that you
only pull down the changes since you last updated, instead of doing
very large file downloads each time.  Another advantage is that you
can keep up with the latest features on a daily basis if you wish,
nearly effortlessly.


Configure:
----------
In order to complete the configure/compile/install of Xastir, you'll
need some of the development tools and headers installed.  Here's a
list of a few items you'll need to have installed.  Look for them in
the development tools sections on your Linux distribution:


    autoconf
    automake
    bash
    binutils
    gcc
    gcc development headers
    cpp
    glibc
    glibc development headers?
    freetype2
    freetype2 development headers
    openmotif (or Lesstiff or Motif)
    openmotif development headers (or Lesstiff or Motif)
    XFree86
    XFree86 development headers
    XFree86 fonts
    XFree86 libraries
    make (GNU flavor, not BSD flavor)
    gzip
    m4
    grep


Note:  Only install one of the Motif packages and the corresponding
development package to go with it.  Recommendation:  OpenMotif.

If you'd like to install additional packages at this point that may
be needed later, install these as well:


    patch
    diffutils
    perl
    less
    bzip2
    curl
    curl development headers
    cvs
    git
    rcs
    tar
    liblcms
    liblcms development headers
    libtiff
    less
    pcre
    pcre development headers
    tcl
    tcl development headers
    tk
    zip
    unzip
    wget
    ax25-apps
    ax25-doc
    ax25-tools
    libax25
    festival
    festival development headers
    gawk
    ghostscript-x11
    ghostscript-fonts
    ghostview
    gv
    ImageMagick
    ImageMagick development headers


Note that some packages may have dependencies on yet more packages.
Hopefully your package installation tool will take care of those for
you.  It's also common for at least one of these packages to forget
to list some of it's dependencies (ImageMagick is known for that).
In that case you may have to rely on the compiler to tell you what
is missing, then go back and re-install a package or two.

Now it is necessary to create the "configure" script that will be needed
to configure Xastir for your system.  In versions prior to release 2.1.8,
this script was included in the Xastir tarballs, but it is no longer included.

   cd ~/src/xastir/Xastir-Release-2.1.0/
   ./bootstrap.sh

You will then create a "build" directory in which to run the
compilation of Xastir, and run Xastir's configure script in that
directory.  In the instructions below we describe making this build
directory inside the Xastir source tree, so it would be

    mkdir -p ~/src/xastir/Xastir-Release-2.1.0/build
    cd  ~/src/xastir/Xastir-Release-2.1.0/build
    ../configure

If you do this, then the simplest path to Xastir's configure script is
just "../configure".  You could create this build directory anywhere,
though, so long as you remember to replace "../configure" with the
full path to Xastir's script, e.g,
~/src/xastir/Xastir-Release-2.1.0/configure.

When you run the "../configure" step from the "build" directory, the
script will attempt to figure out what facilities are available that
Xastir can take advantage of.  Sometimes the script guesses wrong
and you must disable an option and try again.  The correct way to do
this is (Festival speech synthesizer is used as an example, not that
I'm picking on Festival or anything):

    mkdir build
    cd build
    ../configure --without-festival

That will guarantee that configure will skip Festival entirely,
which will set up the Makefiles to skip it, and the Xastir binary
will be created without any support for it.

Some operating systems place their packaged third-party libraries into places
where configure won't find them by default.  In that case you may need to add
additional options the help it out.  Please look at the Installation Notes
section of the Xastir wiki, where it is likely you'll find special instructions
for your operating system.

Other configure options are:

    --without-ax25
    --without-festival
    --without-gpsman
    --without-shapelib
    --without-imagemagick
    --without-libproj
    --without-geotiff
    --without-pcre
    --without-dbfawk
    --without-map-cache
    --with-errorpopups
    --with-rtree


That said, you probably won't have to use any of these!  Type
"../configure" all by itself and the script should eventually give
you a summary of the packages that it will try to compile support
into Xastir for.  The only time you may want to add some of the
above options is if the compile hangs up because of one of them.
You can then add the option to configure, re-create the Makefiles to
skip that feature, and get Xastir compiled without it.  Once you get
the problem solved, you can reconfigure and recompile to add that
feature back in.

At this point, if some things don't appear in the summary that you'd
like/expect to appear, as long as you get to the "Type 'make' to
build Xastir" message, you're doing fine.  You can work on getting
more things in there later.

This is what you'd like to see at the end of the "../configure" run
(minimum, there may be more "yes" answers):

  AX25.......... : no
  Festival...... : no
  GPSMan........ : no
  ImageMagick... : no
  libproj....... : no
  GeoTiff....... : no
  ShapeLib...... : yes (internal)
  pcre.......... : no
  dbfawk........ : no
  libgc (Debug). : no

In other words, Xastir should build/compile with NO optional
libraries installed!  This will still give you USGS GNIS maps,
APRSdos maps, WinAPRS maps, and PocketAPRS maps, plus audio alerts
if you have a suitable audio player installed on your system.
You'll also be able to attach a TNC either in command-line or KISS
mode and connect it to Xastir.  Mobile support will work with an
attached serial GPS.  Attached weather stations should work fine
too.  You won't get online maps or weather alerts with this
configuration though.  Worry about that stuff later once you get the
minimal configuration working.


Make:
-----
Type "make".  That stage should complete with no errors.  You may
have a warning or two show up, depending on your compiler version
and your operating system.


Make install:
-------------
For this stage you need to have root privileges.  "root" is the
user on a Unix/Linux box that has the ultimate authority over
everything.  Follow these steps:

    su
    make install
    chmod 4755 /usr/local/bin/xastir (optional, see below)
    exit

The first step takes you to root user privileges.  You'll need to
type in the root password when it asks for it.  The "make install"
step installs all of the pieces of Xastir in the appropriate places
on your system.

The "chmod" step sets up the Xastir executable so that it can assume
root privileges at the points where it needs to, usually when it
needs to access serial ports or AX.25 kernel networking ports.  Note
that if you don't need the above chmod command, don't use it.  It
will prevent creation of "core" files in case Xastir crashes, which
makes debugging to figure out the root cause much more difficult.
There are also some security risks in doing "chmod 4755", as it
makes Xastir run as the root user at times.  We've tried to minimize
the risk by giving up root permissions when we don't absolutely
require them, so the risks are smaller.

At this point you have a minimal Xastir installed.  Jump down to the
"Operating Xastir" step below.


--------------------------------------------------------------------
--------------------------------------------------------------------


Typical Install:
----------------

First, let's describe it:  This will give you a working Xastir with
local Shapefile maps, online street/topo/satellite-image maps,
weather alerts, and audio alerts.  Optionally you can add
synthesized speech to the mix.

You'll need to run /usr/local/share/xastir/scripts/get-NWSdata as root
after you do the install in order to get the NOAA data files you'll
need for the weather alerts.  "get-NWSdata" requires "wget" in order
to work.

This is what you'd like to see at the end of the "./configure" run
(minimum, there may be more "yes" answers):


-------------------------------------------------------------------
  MINIMUM OPTIONS:
    ShapeLib (Vector maps) ................. : yes

  RECOMMENDED OPTIONS:
    GraphicsMagick/ImageMagick (Raster maps) : yes (GraphicsMagick)
    pcre (Shapefile customization) ......... : yes
    dbfawk (Shapefile customization) ....... : yes
    rtree indexing (Shapefile speedups) .... : no
    map caching (Raster map speedups) ...... : no
    internet map retrieval ................. : yes (libcurl)

  FOR THE ADVENTUROUS:
    AX25 (Linux Kernel I/O Drivers) ........ : no
    libproj (USGS Topos & Aerial Photos) ... : no
    GeoTiff (USGS Topos & Aerial Photos) ... : no
    Festival (Text-to-speech) .............. : no
    GPSMan/gpsmanshp (GPS downloads) ....... : no
-------------------------------------------------------------------


Note:  You may see "ImageMagick" instead of "GraphicsMagick" and/or
"wget" instead of "libcurl" for your installation of Xastir.  Those
are alternative packages that give similar functionality.  You may
also see "(internal)" at the end of the Shapelib line, which is fine
also.


TBD


--------------------------------------------------------------------
--------------------------------------------------------------------


Maximum Install:
----------------

First, let's describe it:  This will give you a working Xastir with
all of the non-debug "configure" options enabled, local maps, online
street/topo/satellite-image maps, weather alerts, audio alerts,
synthesized speech, Garmin RINO support, GPS download support,
search for street address capability, FCC/RAC callsign lookups, and
all of the supported map types.

This is what you'd like to see at the end of the "./configure" run:


-------------------------------------------------------------------
  MINIMUM OPTIONS:
    ShapeLib (Vector maps) ................. : yes

  RECOMMENDED OPTIONS:
    GraphicsMagick/ImageMagick (Raster maps) : yes (GraphicsMagick)
    pcre (Shapefile customization) ......... : yes
    dbfawk (Shapefile customization) ....... : yes
    rtree indexing (Shapefile speedups) .... : yes
    map caching (Raster map speedups) ...... : yes
    internet map retrieval ................. : yes (libcurl)

  FOR THE ADVENTUROUS:
    AX25 (Linux Kernel I/O Drivers) ........ : yes
    libproj (USGS Topos & Aerial Photos) ... : yes
    GeoTiff (USGS Topos & Aerial Photos) ... : yes
    Festival (Text-to-speech) .............. : yes
    GPSMan/gpsmanshp (GPS downloads) ....... : yes
-------------------------------------------------------------------


Note:  You may see "ImageMagick" instead of "GraphicsMagick" and/or
"wget" instead of "libcurl" for your installation of Xastir.  Those
are alternative packages that give similar functionality.  You may
also see "(internal)" at the end of the Shapelib line, which is fine
also.


TBD


--------------------------------------------------------------------
--------------------------------------------------------------------


Operating Xastir:
-----------------

Again, NEVER RUN XASTIR AS THE ROOT USER!  You're risking the
security of your system by attempting it.  Create another regular
user on your system and use that user for all of your normal
activity.  This goes for any other normal activity on the system as
well.  Only use the "root" account for maintenance activities, not
for regular user activities.  You'll thank me later!

Assuming you want to start Xastir up in the English language, you
can type (from an xterm window):

    xastir

which will start up the program without giving you back a
command-prompt in your xterm window (until Xastir exits), or you can
type (from an xterm window):

     xastir &

which will start Xastir in the background, giving you back your
xterm for more commands.  The typical way to start it is with
"xastir &".  Of course you can get fancier and attach it to your
window manager's menus or create an icon on your desktop which
starts it.  Those are operating system/window manager-specific, so
we won't cover how to do that here.

The first time you start Xastir it will show a default map of the
world plus pop up the File->Configure->Station dialog.  Enter a
callsign on that dialog and press the OK button.


Changing the Language:

If you want to start Xastir using some other language, you do that
with command-line switches when you start Xastir.  Once you use one
of these switches, that language option becomes "sticky", meaning
you won't have to enter that command-line switch again unless you
wish to change languages.

There are some command-line switches that you can
If you type "xastir -?", which is an invalid command-line option,
you'll see this:

  xastir: invalid option -- h

  Xastir Command line Options

  -c /path/dir       Xastir config dir
  -f callsign        Track callsign
  -i                 Install private Colormap
  -geometry WxH+X+Y  Set Window Geometry
  -l Dutch           Set the language to Dutch
  -l English         Set the language to English
  -l French          Set the language to French
  -l German          Set the language to German
  -l Italian         Set the language to Italian
  -l Portuguese      Set the language to Portuguese
  -l Spanish         Set the language to Spanish
  -l ElmerFudd       Set the language to ElmerFudd
  -l MuppetsChef     Set the language to MuppetsChef
  -l OldeEnglish     Set the language to OldeEnglish
  -l PigLatin        Set the language to PigLatin
  -l PirateEnglish   Set the language to PirateEnglish
  -m                 Deselect Maps
  -p                 Disable popups
  -t                 Internal SIGSEGV handler enabled
  -v level           Set the debug level


Ignore those for now unless you need to change the Language.

OK, Xastir should show up on your screen at this point.  We're
assuming that you're already running X-Windows graphical environment
at this point.  If you're in command-line Linux/Unix only, Xastir
won't run.

If you've configured in ShapeLib capability, you'll need to run
/usr/local/share/xastir/scripts/get-NWSdata as the root user in order
to get the NOAA data files you'll need for the weather alerts.  The
script requires "wget" in order to work.  Run this script periodically
(once every six months perhaps?) to keep your weather alert maps
up-to-date.  If you're not in the U.S. or one of it's possessions then
you can safely ignore this download.


Various ways to manipulate Xastir:


Context-Dependent Operations:
-----------------------------
                Normal      Draw-CAD    Measure     Move
                ------      --------    -------     ----
Cursor          Arrow       Pencil      Crosshairs  Crosshairs
LeftClick                                           SelectObject
LeftDrag        ZoomToArea  ZoomToArea  MeasureArea MoveObject
MiddleClick     ZoomOut     SetCADPoint ZoomOut     ZoomOut

Alt-F, Alt-V, etc to bring up main menus via the keyboard.  Use
arrow keys to navigate menus and/or single letters corresponding to
the "hot" letter (underlined lettter) for each menu item.

"ESC" to back out of the menu system.


Global Operations:
------------------
LeftClick       Select Menu or GUI Item (when in menus or dialogs)
LeftDblClick    FetchAlertText (when in View->Wx Alerts dialog)
RightClick      OptionsMenu
Home            Center the map on your home station
PageUp          ZoomOut
PageDown        ZoomIn
ArrowUp         PanUp
ArrowDown       PanDown
ArrowLeft       PanLeft
ArrowRight      PanRight
"="             GridSize++
"+"             GridSize++
"Num+"          GridSize++
"-"             GridSize--
"Num-"          GridSize--
"Space"         Activate current widget
"Tab"           Rotate among widgets
"Back-Tab"      Rotate among widgets backwards


Other Possible External Stimuli:
--------------------------------
Send a SIGUSR1 to cause a snapshot to be taken.
Send a SIGHUP to cause Xastir to save/quit/restart.
Send a SIGINT, SIGQUIT, or SIGTERM to cause Xastir to quit.
Connect to TCP port 2023 if Server Port is enabled to send/receive packets.
Send to UDP port 2023 via the xastir_udp_client program to inject packets.


Note that you can also tweak a define/recompile to reverse the
left/right button functions.



Configuring Xastir:
-------------------
*) Note that the menu's have a dashed line near the top.  If you
click on that dashed line it acts like a cut-line for the menu and
detaches that menu from the main menu.  You can then move that menu
off to another area of your screen.  You might try that with the
File->Configure menu at this time.

*) Go to File->Configure->Station and set your callsign.  Set up
other parameters/comment fields on this dialog that may need
setting.

*) Go to File->Configure->Defaults and set parameters there.

You have the main parameters set now.  Next is to enable some
interfaces so that you can see some packets come across.  Easiest
might be the Internet interfaces, assuming the computer you're on
has Internet access and is hooked up to it currently.

*) Run "callpass" in another Xterm window in order to generate your
Pass-code number.  Save that number as you'll need it for each
Interface dialog where you might need to authenticate your callsign.
Of course you can always run callpass again if you forget it!

*) Go to Interface->Properties then click on "Add".  Click "Internet
Server".  Another dialog will come up that allows you to enter the
Host, and the Port.  Enter your Pass-code number here.  People often
check the "Activate on Startup?" and the "Reconnect on NET failure?"
options on this box.  You may also assign a comment to this
interface which describes the interface better for you.  Click "OK"
to create the interface.  If you checked "Activate on Startup?" then
the interface will start as well and you'll be receiving packets.

Browse "http://www.aprs2.net/" to find a reasonable set of servers
to start with.  Another possibility is to use "rotate.aprs2.net"
port 14580, which theoretically should rotate among the available
second-tier servers.  See "http://www.aprs2.net" for more info.
You'll need to put in a filter string, such as "r/35/-106/500" which
shows you stations that are within 500km of 35dN/106dW (Thanks for
that one Tom!).  For additional filter settings check out:

    http://www.aprs-is.net/javaprssrvr/javaprsfilter.htm

*) Start that interface from the Interface->Start/Stop dialog if
it's not started already.  You'll see icons in the lower right
toggling and see callsigns in the lower left status box if packets
are coming in.

One thing about configuration:  Most things don't get written to
Xastir's config file until you choose either "File->Configure->Save
Config Now!" or you exit Xastir.  Map Selections however are
immediate.

*) Creating/starting interfaces for other types of devices is
similar.  If you're wanting to create AX.25 kernel networking ports
you'll have to refer to the HAM HOWTO documents and perhaps the
linux-hams mailing list for help.  For AGWPE connections refer to
that AGWPE docs and mailing list.

It's recommended that if you run a local TNC, you run it in KISS
mode.  You can do that via the Serial KISS TNC interface, or via
AX.25 Kernel Networking ports.

Some of the more esoteric types of interfaces may require some
questions on the Xastir list.  Don't be afraid to ask them as we've
all been there before.


A Note About Paths:
-------------------
New path methods were discussed early April, 2005, and are being
implemented world-wide:

    "WIDE2-2" for fixed stations, balloons, aeronautical-mobile
    "WIDE1-1,WIDE2-1" for mobiles/portables

With this system, "WIDE1-1" has replaced "RELAY".  Never use
"WIDE1-1" in anything but the first path slot.  "RELAY", "WIDE",
"TRACE", and "TRACEn-N" are deprecated and should not be used
anymore.

If you want to insert a single hop callsign later in the path use
"WIDE2-1" instead, for example:  "WIDE1-1,WIDE2-1" will go exactly
two hops and use _either_ home fill-in digi's or mountaintop digi's
for the first hop, mountaintop digi's only for the second hop.

Home fill-in digi's (only where absolutely needed) should be set up
to respond to "WIDE1-1" instead of "RELAY".


A Note About the Map Directory:
-------------------------------
The map directory (/usr/local/share/xastir/maps/) is free-form,
meaning you can have links in there, subdirectories, etc.  Organize
it in any way that makes sense to you.  From within the Map Chooser
you can select a directory name, which will select every map
underneath that directory, so keep that in mind while organizing
your maps.


Enabling Weather Alerts:
------------------------
You must have Shapelib compiled into Xastir.  Xastir now comes with
Shapelib support built-in.  PRCE/dbfawk are optional.  Install NOAA
shapefile maps as specified in README.MAPS.  These files must be
installed into the /usr/local/share/xastir/Counties/ directory.  You
may use this script to download/install them for you:

    "/usr/local/share/xastir/scripts/get-NWSdata"

which must be run as the root user, and requires "wget" to work.

A neat trick:  You can copy some of these maps into the
/usr/local/share/xastir/maps directory somewhere (a new subdirectory
under there is always fine), then you can select some of these maps
as regular Xastir maps as well.


Enabling FCC/RAC Callsign Lookup:
---------------------------------

Run the /usr/local/share/xastir/scripts/get-fcc-rac.pl script as root,
which will download and install the proper databases into the
/usr/local/share/xastir/fcc/ directory.  At that point the callsign
lookup features in the Station Info dialog and in the "Station->Find
Station" menu option should be functional.


Enabling Map Feature Lookup:
----------------------------
Install USGS GNIS files into the /usr/local/share/xastir/GNIS/
directory.  Call out the proper file when invoking the "Map->Locate
Map Feature" menu option.  Note that if you also link a subdirectory
name under the maps directory back to the
/usr/local/share/xastir/GNIS/ directory, you'll be able to use the
GNIS files as maps under the Map Chooser as well.  See README.MAPS
for how to do this.


Enabling Street Address Lookup:
-------------------------------
Download the USA.geocode file and install it into the
/usr/local/share/xastir/GNIS/ directory.  This will enable the
"Map->Find Address" menu option to work.  Xastir will place a big
"X" on the map at the street address it finds for you.  This file is
sometimes available at http://www.dementia.org/geocoder/tgr2003/
As an alternative you can download the individual state files that
are located there.


Enabling Audio Alarms:
----------------------
Download and install sample audio files from Xastir's GitHub
download site:

  git clone http://github.com/Xastir/xastir-sounds

Copy the files to your Xastir sounds directory, for instance:
  /usr/local/share/xastir/sounds/

Install a command-line audio player.  Call out the path/name of that
player in the File->Configure->Audio Alarms dialog.  Common ones are
vplay and auplay, but there are many others.  Enable the types of
alarms you desire in that same dialog.

You should be able to test it manually from a shell by typing the
command in something like this:  vplay filename

Once you find a command that works, type it into Xastir's Audio
Alarms dialog exactly the same except omit the filename.


Enabling Synthesized Speech:
----------------------------
*) MacOSX
    TBD

*) Windows
    TBD

*) Linux/FreeBSD/Solaris
Install the Festival Speech Synthesizer.  Configure/compile support
for it into Xastir.  Start up the Festival server before starting
Xastir.  Xastir should start up and connect to the server.  Use the
options in File->Configure->Speech to decide which things you'd like
Xastir to speak to you about.

Note that the Proximity Alert option in the File->Configure->Speech
dialog uses the distances set in the File->Configure->Audio Alarms
dialog.


Enabling GPS Waypoint/Track/Route Download Support:
---------------------------------------------------
Install GPSMan and gpsmanshp.  Configure/compile support for it in
Xastir.  Start up GPSMan separately and configure it for your GPS
and serial port.  You'll see download options for each type on the
Interface menu.

Note that Xastir requires a version of gpsman at least as recent as 6.1.  Older
versions of gpsman may not work.


Enabling Garmin RINO Support:
-----------------------------
Install GPSMan (and gpsmanshp if you wish normal GPS download
support as well).  Configure/compile support for it in Xastir.
Start up GPSMan separately and configure it for your GPS and serial
port.  In the "File->Configure->Timing" dialog you'll see an option
for "RINO -> Objects Interval".  That sets the interval at which
Xastir will download waypoints from an attached RINO unit.  Any
waypoints that begin with "APRS" will have the "APRS" chopped off,
and the remaining name will be used to create APRS(tm) Objects.  Those
objects will be plotted on the map and transmitted as well if
transmit for objects/items is enabled.
TBD


Transmit Enable/Disable Options:
--------------------------------
Each interface has a separate transmit enable.  The Interface menu
also has a few global transmit enables.  All of these must be
enabled for a particular interface to transmit.  Also, for Internet
servers, you typically need to authenticate with the server using
your callsign/pass-code before you're allowed to inject packets into
the Internet stream which may get gated out to RF.  If you just want
to talk to other Internet users, you don't need a pass-code to
authenticate to the servers.


Igating Options:
----------------
There are igating options on each local TNC interface.  There are
other global igating options on the File->Configure->Defaults
dialog.  The global option sets restrictions on all igating.


Where stuff is kept:
--------------------

Per-user configurations are kept in each user's ~/.xastir directory, by
default.  In particular the ~/.xastir/config/xastir.cnf file is where most
of the configs are kept.  This directory can be optionally specified using
the -c /path/dir command line option.  Make sure you specify a directory,
not a file!  Xastir will create the directory and several subdirectories if
they do not exist when you start up.

A few executables are installed in /usr/local/bin/.

Scripts are installed in /usr/local/share/xastir/scripts.

Maps are installed in /usr/local/share/xastir/maps/.  Lots of other
directories are under /usr/local/share/xastir/.


More?
-----
Anything else?  Let's hear about what's still confusing or needs to
be expanded in this document.  Thanks!


APRS(tm) is a Trademark of Bob Bruninga

Copyright (C) 2000-2019 The Xastir Group

Recommended Configurations for:

  U.S. Users:
  -----------

    Minimum:  Shapelib, pcre
    --------
      Allows use of all built-in map types plus 2003 (and later) Tigermap data,
      shapefile weather alerts, and local ESRI Shapefile format
      maps, including U.S. satellite/image/topo maps via Internet.

    Medium:  Shapelib, pcre, lcms, ImageMagick, libcurl/wget,
    -------

      Allows use of all the above plus Internet maps and local image
      maps.

    Maximum:  Shapelib, pcre, lcms, ImageMagick, libcurl/wget,
    --------  libtif, libproj, libgeotiff

      Allows use of all the above plus USGS topo maps.

  Rest of World:
  --------------

    Minimum:  lcms, ImageMagick, libcurl/wget
    --------
      Allows use of all built-in map types plus local and Internet
      image maps, including Canadian topo maps via Internet.

    Medium:  lcms, ImageMagick, libcurl/wget, Shapelib, pcre,
    -------

      Allows use of all the above plus ESRI Shapefile maps.

    Maximum:  libproj/libtiff/libgeotiff
    --------
      Adds more map types.  Some of these may not be useful in your
      part of the world.


Map Type:           Libraries Required/Notes:
---------------     -------------------------
DosAPRS             Built-in.
WinAPRS             Built-in.
X-APRS              Built-in.
MacAPRS             Built-in.
PocketAPRS          Built-in.
USGS GNIS           Built-in.  Can split into county-sized chunks
                    using xastir/scripts/split_gnis.pl to speed
                    things up.
Address Lookup      Built-in.
Weather Alerts      Shapelib
pre-2003 Tigermaps  Shapelib
post-2003 Tigermaps Shapelib, pcre
ESRI Shapefiles     Shapelib
Image Maps          ImageMagick.  Often need lcms library and others
                    as well (whatever it takes to make ImageMagick
                    happy).  Can also use the XPM library for some
                    image types without installing ImageMagick.
Internet Maps       ImageMagick plus wget or libcurl.  Often need
                    lcms library and others as well (whatever it
                    takes to make ImageMagick happy). WMS Maps are
                    in this category as well.
UI-View Maps        Convert from .INF to .GEO format using
                    xastir/scripts/inf2geo.pl
OziExplorer Maps    Convert some maps to .GEO format using
                    xastir/scripts/ozi2geo.pl
USGS DRG Topo       libtiff, libtiff-devel, libproj, libgeotiff
APRS Overlays       Convert to Shapefile maps with scripts/pos2shp.pl


The default map, "worldhi.map", is used with permission of its creator, Keith Sproul, WU2Z.


How to Use APRS Overlay Maps (*.POS files) within Xastir:
---------------------------------------------------------
    Use the "xastir/scripts/pos2shp.pl" script to convert the
    overlay files to ESRI Shapefile maps:

        # ./pos2shp.pl test.pos testmap
        # cp testmap* /usr/local/share/xastir/maps/.

    Xastir:  Map->Configure->Index: Add New Maps
             Map Chooser:  Select the "testmap" map


Using Online Maps:
------------------
      There are a few *.geo files that get installed into Xastir's maps/
      directory upon install. These invoke online map sources of various types:

   OpenStreetMap
   -------------

      Select the appropriate files from the Online/ directory in Map Chooser

   WMS Map Servers
   ---------------

      Xastir has support for WMS map servers built-in. To use this you'll need
      to create a *.geo file in your map directory (usually
      "/usr/local/share/xastir/maps/Online/", "/usr/share/xastir/maps/Online/"
      or any directory below those) for each LAYER you wish to use, perform a
      re-index of your maps, then select them in the Map Chooser.

      Procedure: Hunt down a WMS map server that you wish to use, then find
      its "GetCapabilities" link. Here's an example:

  http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetCapabilities

      Look at it directly in your browser or use Xastir's "wms.pl" script to
      see the structure and keywords of the XML. Note that if using "wms.pl"
      you must add backslashes prior to each '&' character in the URL.

  wms.pl "http://geogratis.gc.ca/maps/CBMT?service=wms\&version=1.1.1\&request=GetCapabilities"

      "wms.pl" will show the format of the XML file plus a section at the end
      which looks like:

---------------
  POSSIBLE .GEO FILE CONTENTS:

  WMSSERVER
  URL http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetMap&SRS=EPSG:4326&FORMAT=image/png&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&STYLES=&LAYERS=National

  WMSSERVER
  URL http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetMap&SRS=EPSG:4326&FORMAT=image/png&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&STYLES=&LAYERS=Sub_national

  WMSSERVER
  URL http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetMap&SRS=EPSG:4326&FORMAT=image/png&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&STYLES=&LAYERS=Regional

  WMSSERVER
  URL http://geogratis.gc.ca/maps/CBMT?service=wms&version=1.1.1&request=GetMap&SRS=EPSG:4326&FORMAT=image/png&BGCOLOR=0xFFFFFF&TRANSPARENT=FALSE&STYLES=&LAYERS=Sub_regional
---------------

      This means there are four different map layers you can get from that WMS
      server. To see/use each one you'll need to create four different .geo
      files for Xastir. The format of a WMS Server .geo file is exactly two
      lines. Try using each of the two-line outputs from wms.pl as a start
      towards creating your own .geo files.


Getting Maps and other Data Files for Xastir:
---------------------------------------------

      NOTE:  Set map FILES to permissions 644 ("rw-r--r--"), map
      DIRECTORIES to 755 ("rwxr-xr-x") using the "chmod" command.
      These permissions will allow anyone on the box to read the map
      files, and access the map directories. Type these
      commands exactly as shown in order to set the map directory's
      permissions properly.  Do this as the root user:

      cd /usr/local/share/xastir/maps
      find . -type d -exec chmod 755 {} \;
      find . -type f -exec chmod 644 {} \;

      You can repeat these commands at anytime, to fix up errant map
      permissions that are created by downloading/installing new
      maps.

      Currently the maps/GPS directory needs to be writable by normal users
      in order to support downloading GPS data using GPSMan.  This will be
      changed at some future date, moving this directory into the user's
      home directory instead.

      cd /usr/local/share/xastir/maps
      chmod 777 GPS
      find GPS -type d -exec chmod 777 {} \;
      find GPS -type f -exec chmod 777 {} \;



    Download some maps:

      If you compiled with ImageMagick and have wget or libcurl installed,
      you can skip this step and use the online OSM/WMS maps
      exclusively. However, having maps on your computer is often faster
      than transferring images over a modem, and is not subject to the
      failures of your Internet connection.  See the section below on map
      caching for an exciting feature that works with most online maps to
      really speed things up!

      You can have any number of maps in the /usr/local/share/xastir/maps
      directory.  You can organize the maps however you like. You can also
      use symbolic links to link to files/directories on other disks. Map
      files are loaded in the order that they appear in the chooser unless
      you adjust the layering priorities in the "Properties" dialog (it's
      recommended that you use these now instead of a directory hierarchy to
      choose the layering).

      There are many methods for organizing many maps. Create a map
      hierarchy using something that makes sense to you. The old method of
      creating transparent/filled or raster/vector directories has been
      superceded by the new map layering features in the Map
      Chooser->Properties dialog. It's now suggested that the map layering
      be done there, and the directory layout designed to make it easiest
      for the user to select maps. Perhaps a good start would be:

           World/
           Canada/
           Canada/Province/
           USA/
           USA/State/WA/
           USA/State/WA/County/
           ...
           GNIS/
           Overlay/

      Please note that the map directories are entirely up to the user
      now. Use the map layering facilities (Map Chooser->Properties) to
      determine the order in which they will be drawn, and to determine
      which will draw filled areas.  Note that raster maps will always draw
      filled, not matter what the setting suggests.  For vector maps, you
      have a choice of:

            Fill = No       Polygons will never be filled
            Fill = Yes      Polygons will always be filled
            Fill = Auto     Polygon fill is determined by map (or if it's a
                            Shapefile, by any associated dbfawk file).

      Map types available by extension:

      Vector Format:
      .shp/.shx/.dbf  Shapefile vector map (need all three files)
      .map            APRSdos/WinAPRS/MacAPRS vector map
      .gnis           GNIS labels file (actually points instead of vectors)
      .geo            Vector map or Internet vector map.  Note that for
                      http/ftp-based maps Xastir requires an IMAGESIZE line.

      Raster Format:
      .tif/.fgd       geoTIFF raster image map
      .geo            Raster image map or Internet raster image map.  Note that
                      for http/ftp-based maps Xastir requires an IMAGESIZE line
                      unless using WMS maps.

      Note:  .geo is listed twice because it can fit in both categories,
      depending on the base format of the map file that the .geo file
      points to.  .geo files are handled by the XPM library or by
      ImageMagick, so most anything that can be handled by those installed
      libraries can by handled by Xastir.

      A few maps of various types are available from:

        http://we7u.wetnet.net/xastir/maps/

      Here's a page that we'll try to keep up-to-date which will have lots of
      links to download-able maps on it:

        http://xastir.org/index.php/Xastir_Maps

     Dos/Win/MacAPRS style vector/fill maps:

      http://www.winaprs.com/Maps.htm
      http://www.cnunix.com/ftp/hamradio/rutgers.mirror/maps/maps2/
      ftp://ftp.tapr.org/aprssig/maps/

       WORLDHI.MAP is suggested as a basic view of the world map.

      You can use any of the other maps available from this site. Many of
      them were created from Tiger/Line maps, but they are several years out of
      date. It is suggested that you don't use these as your primary
      street-level maps; the newer shapefile-based maps are usually preferable.
      In cases where you cannot compile shapefile support, these maps suffice.


     PocketAPRS vector maps:

      The WinAPRS 2.51 distribution included the full collection of
      PocketAPRS vector maps for the USA. The download is about 60MB, from the
      TAPR ftp site.

        ftp://ftp.tapr.org/aprssig/winstuff/WinAPRS/waprs251.zip


     Raster Maps:

      For Canada there is a country wide set of topographic map images available
      from the "Department of Natural Resources Geomatics Canada". Running
      /scripts/toporama250k.pl will pull down 430mb of 1:250k map images
      from that departments site. If thats not enough data, running
      /scripts/toporama50k.pl will pull down around 10gigs

**** Note that recent changes at the "Department of Natural Resources Geomatics
Canada" have made these scripts fail.  Changes to the scripts are being coded
and tested.  Git will be updated once the scripts are proven to work again. ****


     For Ireland, EI8IC (http://www.mapability.com) has produced a set of overlay
     maps that show the County Borders, Main Towns and Roads.  John, EI7IG, has
     created a set of ".geo" files to go with them and they are all available in one
     tarball from [http://ireland.aprs2.net/xastir/IrelandMaps/Ireland.tar.gz
     ireland.aprs2.net] They are free for non-commercial use.

     Also available are a map of the
     [http://ireland.aprs2.net/xastir/IrelandMaps/Ireland1600x2000.bmp country], with
     an associated [http://ireland.aprs2.net/xastir/IrelandMapsIreland1600x2000.geo
     geo] file, the [http://ireland.aprs2.net/xastir/IrelandMaps/Ireland1600x2000.bmp
     South East], its associated
     [http://ireland.aprs2.net/xastir/IrelandMapsIreland1600x2000.geo geo] and a
     [http://ireland.aprs2.net/xastir/IrelandMaps/IrishMET.geo Weather Radar] .geo file.


     Shapefile format maps (Requires shapefile support):

      Shapefile format maps are slowly becoming the standard vector format of
      maps used with Xastir. Xastir 1.3.2 and above by default enable dbfawk
      support for parsing shapefile metadata, see below.

      A nice world map is available at http://aprsworld.net/gisdata/world/
      thanks to James Jefferson, TerraSpace, Russia, and the Digital Chart
      of the World (for Antarctica).  Note that this file is currently
      available only in uncompressed or in tar/bzip2 format.  To decompress
      the latter file, you'd type "bunzip2 filename" and then
      "tar xvf filename".

      Some other shapefile format maps are available at:
      http://www.nws.noaa.gov/geodata/

      Still other shapefiles are available from esri.com, geographynetwork.com
      and gisdatadepot.com (from their "free data" link).  Lot's of useful
      stuff at these sites, just look around.  You can also check
      with your County GIS office for shapefiles of your county.  You can
      convert them from State Plane to Lat/Long projection using
      instructions later in this document.

      Canada street maps in Shapefile format are available at
      http://www.geobase.ca

      If you also use GeoTIFF images, get the handy usgs_24kgrid.zip file from
      http://data.geocomm.com/quadindex/.  This file provides a grid of all of
      the 7.5' maps and their names for the U.S.

      A nice world map is available at http://aprsworld.net/gisdata/world/
      thanks to James Jefferson, TerraSpace, Russia, and the Digital Chart
      of the World (for Antarctica).  Note that this file is currently
      available only in uncompressed or in tar/bzip2 format.  To decompress
      the latter file, you'd type "bunzip2 filename" and then
      "tar xvf filename".

      www.bts.gov has the "National Transportation Atlas" that you can download
      pieces of (at least for the larger layers) or ask for (free) CD-ROM's to be
      mailed to you.

      -----
      Re-projecting shapefiles (or: why doesn't my shapefile show up?)

      A shapefile is pretty much just a collection of points and lines
      between points.  Xastir expects that those points are expressed in
      degrees of longitude and latitude with positive values indicating N
      and E and negative values indicating S and W.

      One often comes across shapefiles with data in some other format, such
      as UTM or state-plane projections with units in meters or feet.  You
      must re-project these sorts of shapefiles in order to use them in
      Xastir.  You must either know what the current format is of the
      shapefile you wish to re-project, or have the .prj file that some
      shapefiles come with.

      Fortunately, the shapelib-1.2.10 distribution (which you probably
      compiled and installed to enable shapefile maps in Xastir) includes a
      tool for performing this re-projection.

      First make the shpproj utility by:

      1. change to directory: <shapelib source directory>/contrib
      2. type 'make' to compile the contrib files
      3. Optionally install shpproj by copying it to /usr/local/bin

      shpproj takes 4 arguments:

          shpproj shp_file new_shp -i="in_params" -o="out_params"

      shp_file is the name of your existing shapefile triad (without the
      extension).

      new_shp is the name of your new shapefile triad (which doesn't exist
      yet).

      -i="in_params" are the parameters describing the existing shapefile.

      -o="out_params" are the parameters describing the new shapefile.  We
      want this to be "geographic".

      Examples:

      Convert shapefile triad from US State-plane, South Central Texas region
      (FIPS code 4204), in feet to geographic:

        shpproj stateplane_shapefile geographic_shapefile \
             -i="init=nad83:4204 units=us-ft" -o=geographic

      Convert UTM zone 15 to geographic:

        shpproj utm_shapefile geographic_shapefile \
             -i="proj=utm zone=15 units=m" -o=geographic

      To get a listing of the FIPS codes, you need to have proj installed
      (see elsewhere in this file for more information).  Look in the
      "<proj source directory>/nad/nad.lst" file.

      For more detailed documentation, see the shpproj.txt file in the
      "<shapelib source directory>/contrib/doc" directory.

      There's a resource for looking up the FIPS codes for a particular
      area:

            http://www.aprs.net/fips/

      An important note about using shpproj to re-project maps

      The shpproj program cannot be used to convert shapefiles unless they're
      already using the NAD83 or WGS84 datum.  shpproj will do the conversion
      if you ask it to, but it will do it incorrectly.

      A simple program to convert shapefiles between various projections
      that does do datum conversions correctly is "shpcs2cs," available
      from
          <http://www.swcp.com/~russo/shape_web/>
      That program requires libproj to be installed properly, and uses a
      command line format similar to the "cs2cs" program that comes with
      libproj.

      If you already have GDAL installed, you should have the "ogr2ogr"
      program available to you.  ogr2ogr will not only convert projections
      and geodetic datum correctly, but will also convert format (ArcView
      binary format to shapefile, TIGER/Line files to shapefile, etc.).
      Some detailed instructions for using ogr2ogr to do this conversion
      are available at
          <http://www.swcp.com/~russo/shape_web/>

      -----

      Using "dbfawk" to interpret shapefile DBF data:  Each shapefile
      map (*.shp, *.shx) comes with a DBase data file (*.dbf) in which
      each shape in the .shp file has a corresponding set of descriptive
      data about that shape in the .dbf file.  While shapefiles are all
      a standard format and will most always draw (possibly after having
      been re-projected with shpproj), the corresponding .dbf data varies
      widely depending on the data source.  For example, US Census
      Tiger/Line files contain 20 attributes for each shape including such
      values as the name of the shape (i.e. street name), and a "Census
      Feature Class Code" (CFCC) which indicates whether a shape is a
      dirt road or a superhighway, for example.

      In "pre-dbfawk" Xastir, knowledge of the various sources of
      shape files was built into the program and it was necessary to
      add code to support new shapefile sources (such as those
      produced by local government agencies, non-US, etc.).  Xastir
      with dbfawk moves this logic into metadata files named *.dbfawk.
      These files are linked to the .shp/.dbf files they belong with in
      one of two ways:
        1. "Signature" recognition.  .dbfawk files located in the config/
           directory are read to find the "dbfinfo" signature, which is
           simply the ordered list of attribute names found in the .dbf file.
           If you browse config/*.dbfawk you will see dbfawk's for the most
           well know shapefile types.  For example, tgrlk.dbfawk matches
           all the "tgr*lk?.dbf" US Census Tiger/Line files.  When a shapefile
           map is displayed, its .dbf signature is matched up with one of
           the config/*.dbfawk files.
        2. "Tied" to a file.  If you installed a .dbfawk file in the same
            directory as the .shp and .dbf files (e.g. sample.shp, sample.dbf
            get a corresponding sample.dbfawk) then that file is used instead
            of signature matching.
      The first method allows a single .dbfawk file to be automatically
      used for hundreds of standard shapefile maps.  The later allows you
      to customize how your particular shapefile map displays.

      What's in a .dbfawk file?  The best documentation of these files
      is found by looking at the commented examples in config/*.dbfawk.
      dbfawk is modeled after the "awk" pattern scanning and processing
      language -- but, it is *not* exactly awk:
        - Regular expression syntax is that used by Perl (the pcre library
          is used) rather than pure awk.
        - Action statements are much more limited than full-blown awk.
        - The concept of records and fields is used since a .dbf record
          is structured of usually several fields (name, feature type, etc.).
      That said, what dbfawk does is allow a great degree of control of
      how and when shapes and their names are displayed.  This is done by
      setting the values of several "builtin" variables [Technically, these
      are only built-in to shapefile support.  Potentially the awk-like
      code can be extended to other uses.]:
        dbfinfo:   the "signature" to match against.
        dbffields: which fields to read from the .dbf file.
        color:     what color code to display the shape with.
        lanes:     width of the shape.
        name:      name of the shape.
        key:       search key (used for WX alerts to find the shape)
        symbol:	   symbol for landmarks, etc.
        filled:	   draw polygons filled.  Filled="Yes" or "No" in the Map
                   Properties dialog will override this option.  Set to "Auto"
                   in that dialog to have the dbfawk file control this.
        fill_style: style of fill (0=solid, 1=FillTiled, 2=FillStippled, etc.)
        fill_color: color of fill
        fill_stipple: stipple pattern if fill_style=2 ("FillStipple")
                      0=13 percent, 1=25 percent, 2=50 percent.
        pattern:   solid or dashed lines.
        display_level: at what zoom level to begin displaying the shape
        label_level: at what zoom level to begin displaying labels
        label_color: color to use for labels

      Execution of a dbfawk file:  Just like awk, the file consists of
      patterns that are matched against input data and actions to take
      when the pattern matches.  There are four special patterns in dbfawk:
        BEGIN_RECORD: action is executed just before parsing a record.
        BEGIN: action is executed just before parsing a field.
        END: action is executed just after parsing the field.
        END_RECORD: action is executed just after parsing a record.
      All other patterns are regular expressions that are matched against
      a data value of <fieldname>=<value>.  For example:
        FENAME=Main

      Actions in dbfawk files consist of setting variables and two special
      actions:
        next: skips to the next field in the record.
        skip: skips to the next record.
      If neither next nor skip is given in the action, then processing falls
      through to the next pattern/action pair in the dbfawk file.

      The special dbffields variable is used to list which fields of the
      record to be processed and in what order.  The order is significant
      since it may take several DBF fields to build up a complete name.
      For example, in Tiger/Line, the street name is actually the
      concatenation of FEDIRP, FENAME, TYPE, FEDIRS.  Here's an excerpt
      from tgrlk.dbfawk to demonstrate:
        BEGIN {dbffields="TLID:FEDIRP:FENAME:FETYPE:FEDIRS:CFCC"}
        ...
	/^FEDIRP=(.+)$/ {name="$1 ";next}
	/^FENAME=United States Highway (.*)$/ {name="$(name)US $1"; next}
	/^FENAME=State Highway (.*)$/ {name="$(name)State $1";next}
	/^FENAME=State Route (.*)$/ {name="$(name)SR $1";next}
	/^FENAME=(.*)$/ {name="$(name)$1; next}
	/^FETYPE=(.+)$/ {name="$(name) $1"; next}
	/^FEDIRS=(.+)$/ {name="$(name) $1"; next}

      Creating and testing dbfawk files:  You can test an existing dbfawk
      file by setting debug level 16 in Xastir (this will generate a huge
      amount of map rendering debug output, including dbfawk info):
       "./xastir -v 16 2>/tmp/log"
      Or, use "testdbfawk" which reads a .dbf file (or single field assignments
      on the command line).  For example:

    cd /usr/local/share/xastir
	testdbfawk -D config -d Counties/mz01ap14.dbf 2>&1 | less
    8 Columns,  479 Records in file
    sig: ID:WFO:GL_WFO:NAME:AJOIN0:AJOIN1:LON:LAT
    DBF Signatures match!
    name=Lake Okeechobee, key=AM_Z610, symbol=, color=8, lanes=2, filled=0, pattern=0, display_level=65536, font_size=2, label_level=512
    label_color=20
    ...

      testdbfawk takes the following command line syntax:
        testdbfawk --help
          Prints command line usage
        testdbfawk -D directory -d file.dbf
          Scans directory for dbfawk files with signatures matching file.dbf,
          runs the dbfawk program that matches if it's found.
        testdbfawk -f file.dbfawk -d file.dbf
          runs the dbfawk file "file.dbfawk" over the dbf file "file.dbf"

      So in the example above, testdbfawk scans the current directory
      for dbfawk files with signatures that match tgr36119lkA.dbf's
      signature.  testdbfawk dumps its output to standard error, so in
      the example standard error is redirected to standard out and
      piped into "less" for paging.

      To create a .dbfawk file, you need to understand the layout and contents
      of your .dbf file.  Use "dbfinfo" and "dbfdump" which are in the shapelib
      contrib directory.  Dbfinfo will list the field names and dbfdump will
      dump out all fields of all records.  Take the field names from dbfinfo,
      and concatenate them together in order, separated by ":" to make the
      dbfinfo= signature variable assignment.

      Your best bet is to start with an existing .dbfawk file as an example.

      Dbfawk hints and kinks:  You have to think like an awk programmer and
      realize that the order that rules are listed matters, that it's important
      to use "next" as soon as it makes sense so other rules aren't looked at
      unnecessarily and, to use "skip" when you want to fix bad dbf data.
      For example, my county's Tiger/Line maps have several coding errors
      where a segment of a main highway is incorrectly labeled as a local
      street.  This rule overrides one of those incorrect records:
	# This Furnace Dock Rd segment is really Rt 9!
	/^TLID=139773160$/ {name="Briarcliff-Peekskill Pky"; display_level=8192; label_level=512; color=4; lanes=4; skip;}
      TLID is the Tiger/Line ID which is the unique identifier for this
      segment.
      -----

    Rolling your own shapefile maps:

    It is relatively easy to create your own shapefile maps (for example,
    if you want to highlight a walk-a-thon course).  There are several
    methods available with Xastir:

    1. Use GPSMan to download a GPS track to a shapefile.

    2. Save a station tracklog of an actual station or an object that
       you manually move along the course.  When you select Station Info,
       you are presented with the option to save the track, which gets
       put in
       .xastir/tracklogs/<datestamp>_<callsign>_APRS_Trail_<color>.*
       You can move the .shp, .shx, and .dbf files to your maps directory.
       Use DBFAWK to make a map-specific .dbfawk file.  For example:
	BEGIN {dbfinfo="Credits:DateTime";dbffields="Credits:"}
	BEGIN_RECORD {key=""; lanes=4; color=12; name=""; filled=0;
           pattern=1; display_level=8192; label_level=32; symbol=""}
       This makes the track width 4 and red (12).

    3. You can use xastir's "object" capability to generate shapefile maps.
       a) Turn off object transmission using
          Interface->Disable Transmit:Objects
       b) Put objects where you want.  Set the display symbol as you like it.
       c) run the "object2shp.pl" script in the scripts directory
           (/usr/local/share/xastir/scripts/object2shp.pl in most installations)
          to generate a shapefile:
            /usr/local/share/xastir/scripts/object2shp.pl ~/.xastir/object.log myshape
          This requires the four shapelib utilities "dbfcreate", "shpcreate",
          "shpadd" and "dbfadd" as described below.
       d) EXIT XASTIR
       e) REMOVE ~/.xastir/config/object.log
       f) move "myshape.shp," "myshape.shx," and "myshape.dbf" to your maps
          directory.
       g) restart xastir.
       h) select your newmap in the map chooser.
      Creating maps in this way is basically just a scripted version of the
      manual map generation technique in (4) below.

    4. You can also use the shapelib tools (shpproj was presented earlier)
       to manually create a shapefile.  For example, the following
       marks out the mile-posts for a marathon, using tgrlpt.dbfawk
       (US Census Tiger/Line landmark points with an APRS(tm) symbol extension)
       for the metadata:
       #!/bin/sh
       # turn mileposts into a Tiger landmark shapefile

       rm -f posts.shp posts.dbf
       shpcreate posts point
       dbfcreate posts -n ID 8 0 -s CFCC 3 -s NAME 30
       shpadd posts -74.0570 40.6025
       dbfadd posts 1 'X\m ' Start
       shpadd posts -74.0443 40.6065
       dbfadd posts 2 'X\m ' 1M
       shpadd posts -74.0353 40.6093
       dbfadd posts 3 'X\m ' 2M
       shpadd posts -74.0268 40.6260
       dbfadd posts 4 'X\m ' 3R
       shpadd posts -74.0200 40.6277
       dbfadd posts 5 'X\m ' 3G
       shpadd posts -74.0270 40.6252
       dbfadd posts 6 'X\m ' 3B
       shpadd posts -74.0197 40.6395
       dbfadd posts 7 'X\m ' 4R
       shpadd posts -74.0203 40.6388
       dbfadd posts 8 'X\m ' 4BG
       shpadd posts -74.0077 40.6508
       dbfadd posts 9 'X\m ' 5R
       shpadd posts -74.0083 40.6503
       dbfadd posts 10 'X\m ' 5BG
       shpadd posts -73.9957 40.6623
       dbfadd posts 11 'X\m ' 6R
       shpadd posts -73.9962 40.6617
       dbfadd posts 12 'X\m ' 6BG
       shpadd posts -73.9850 40.6743
       dbfadd posts 13 'X\m ' 7R
       shpadd posts -73.9858 40.6738
       dbfadd posts 14 'X\m ' 7BG
       shpadd posts -73.9782 40.6865
       dbfadd posts 15 'X\m ' 8M
       shpadd posts -73.9597 40.6890
       dbfadd posts 16 'X\m ' 9M
       shpadd posts -73.9573 40.7007
       dbfadd posts 17 'X\m ' 10M
       shpadd posts -73.9622 40.7122
       dbfadd posts 18 'X\m ' 11M
       shpadd posts -73.9515 40.7230
       dbfadd posts 19 'X\m ' 12M
       shpadd posts -73.9520 40.7345
       dbfadd posts 20 'X\m ' 13M
       shpadd posts -73.9525 40.7465
       dbfadd posts 22 'X\m ' 14M
       shpadd posts -73.9403 40.7503
       dbfadd posts 23 'X\m ' 15M
       shpadd posts -73.9578 40.7587
       dbfadd posts 24 'X\m ' 16M
       shpadd posts -73.9556 40.7675
       dbfadd posts 25 'X\m ' 17M
       shpadd posts -73.9465 40.7808
       dbfadd posts 26 'X\m ' 18M
       shpadd posts -73.9372 40.7935
       dbfadd posts 27 'X\m ' 19M
       shpadd posts -73.9272 40.8047
       dbfadd posts 28 'X\m ' 20M
       shpadd posts -73.9343 40.8142
       dbfadd posts 29 'X\m ' 21M
       shpadd posts -73.9453 40.8050
       dbfadd posts 30 'X\m ' 22M
       shpadd posts -73.9525 40.7923
       dbfadd posts 31 'X\m ' 23M
       shpadd posts -73.9630 40.7810
       dbfadd posts 32 'X\m ' 24M
       shpadd posts -73.9720 40.7696
       dbfadd posts 33 'X\m ' 25M
       shpadd posts -73.9811 40.7683
       dbfadd posts 34 'X\m ' 26M
       shpadd posts -73.9763 40.7720
       dbfadd posts 35 'X\m ' Finish
    ---------

    Splitting large Shapefile maps into regularly-sized tiles:

      Look for "shp2tile" at http://imaptools.com/tools/, it does
      exactly that.  This can speed up Xastir tremendously if you're
      zoomed in quite a bit on a large Shapefile map (or maps).  If
      it is broken into tiles Xastir only has to load the tiles of
      interest instead of slogging through the entire large file
      each time.


    GeoTIFF Map files (requires GeoTIFF):

      If you compiled in geoTIFF support, you can use USGS DRG topographic
      maps. These are primarily useful to U.S. users. DRG topo maps can be
      found for free for most states, and can be purchased for others.

        http://www.bianifc.org/gis_gps/gps/drgfree.html
        http://www.gisdatadepot.com

      or try a google search with "free drg maps" as the search query.

      If you have no luck finding free DRG maps, go to
      http://www.geocomm.com/ and check out the "DRG Data Bundles"
      they have available.  You can purchase a DVD containing all the
      DRGs for an entire state in three scales, all of them usable in
      xastir, for a relatively low price.  Be warned, however, that
      parts of the US have DRGs that are produced by an agency other
      than the United States Geological Survey, and these DRGs are not
      necessarily in correct GeoTIFF format.  The areas covered by the
      Tennessee Valley Authority appear to be among those, as one
      xastir user discovered when purchasing a DVD of DRGs for North
      Carolina.  It is still possible to use these DRG files, but they
      need preprocessing.  See the section below entitled "Defective
      GeoTIFF files need even more special processing."

      Many useful US maps can be downloaded from the National Map Viewer:
      http://nmviewogc.cr.usgs.gov/viewer.htm

      Free FAA sectional charts can be downloaded from
        http://aviationtoolbox.org/raw_data/FAA_sectionals/current/
      This site was set up by someone who had a subscription to the FAA
      DVD collection and made them available on the web (this is legal per
      FAA's terms of use).  They are no longer being updated as of mid 2005.
      These charts are in Lambert Conformal Conic projection, though, and
      need to be converted with gdalwarp to be usable in xastir (see below).

      Current, valid-for-navigation FAA sectional charts may be purchased
      from the FAA at
 	https://naco.faa.gov/ecomp/Catalog.aspx?a=AERO+NOS+DIGITAL
      for about $1.50US each.  These files are also in GeoTIFF and are the
      same type as those that are available on aviationtoolbox, but these are
      updated every 6 months and are kept current.  You will have to process
      them before viewing in xastir.

      The 7.5' topo maps work the best so far.  Be sure to install the .tif AND
      the .fgd files side-by-side into the map directories. Without the .fgd
      file Xastir won't be able to crop the white border from the map.  Xastir
      currently knows how to handle NAD27, NAD83, and WGS84 geoTIFF files.
      GeoTIFF files created in other datums will be displayed at an incorrect
      location with Xastir. The .tfw files included with most geoTIFF images
      are not used by Xastir.

      If you must make FGD files by hand, the included script mapfgd.pl can
      create them for you from the USGS geoTIFF files. The format Xastir is
      looking for is the following:

        1.5.1.1  WEST BOUNDING COORDINATE:  -122.000000
        1.5.1.2  EAST BOUNDING COORDINATE:  -120.000000
        1.5.1.3  NORTH BOUNDING COORDINATE:  48.000000
        1.5.1.4  SOUTH BOUNDING COORDINATE:  47.000000

     -or-

        1.5.1.1  West_Bounding_Coordinate:  -122.000000
        1.5.1.2  East_Bounding_Coordinate:  -120.000000
        1.5.1.3  North_Bounding_Coordinate:  48.000000
        1.5.1.4  South_Bounding_Coordinate:  47.000000

      Notes about DRG-Enhanced (DRG-E) files:
      * The DRG-E files will draw over the correct spots if you remove
      the .fgd file, but will overflow their boundaries and

      * The DRG-E files will draw over the correct spots with decent
      boundary trimming (as far as I can tell, which isn't very far:
      correct me!) if you use a .fgd file taken from 'real' DRG files
      from USGS.

      Basically: get rid of the .fgd file from the DRG-E!!

    Highly Compressed MrSID image files:

      Be wary of DRG-E or DOQQ files that are compressed with MrSID
      compression.  That is a proprietary compression format for
      which we do not have access to the decoding algorithm.  We
      cannot use those from within Xastir.  There's possible good news
      lurking on the horizon though:  LizardTech has mentioned on the
      gdal-dev mailing list that they might be supporting open-source
      with a driver for gdal sometime soon.

      It is also possible to decompress these files with a free tool
      from LizardTech called "mrsiddecode", available at
        http://www.lizardtech.com/download/dl_options.php?page=tools

      mrsiddecode can produce GeoTIFF output with the right command line
      options.  There is a Linux version of mrsiddecode, but one user
      has observed that the Windows version running under Wine is a little
      more robust.  Your milage may vary.

      Be warned that MrSID is a very effective compression algorithm, and
      compressed MrSID files of size 5MB could easily decompress into 50MB
      GeoTIFFs.

      Note also that many GIS departments take perfectly usable
      GeoTIFF files with all projection and datum tags and use ESRI products
      to compress them down into MrSID files, thereby losing all the
      GeoTIFF tags.  See below.

    GeoTIFF files in certain projections need special processing:

      Not all geotiff files available on the net are usable directly in
      xastir.  Some of them are in projections that xastir can't use
      properly, and others are missing all of the metadata information that
      is needed to work out how to convert them to Lat/Lon unprojected rasters.
      If you encounter a geotiff file that has the correct tags, but is
      in some projection other than UTM, you can convert that file to a
      lat/lon raster if you have gdal installed.  Simply run the following
      command:
        gdalwarp -t_srs EPSG:4326 original_raster.tif usable_raster.tif

      This will warp the geotiff file "original raster.tif" from
      whatever projection it was in into an unprojected lat/lon raster
      "usable_raster.tif" that can be directly read into xastir.
      Depending on the source projection, you might get a map that
      doesn't tile well with other maps due to the inclusion of opaque
      border material, but it can sometimes be the only way to import
      a map you need to use.

    Defective GeoTIFF files need even more special processing:

      It is unfortunately the case that the ESRI software in use by many
      GIS departments produces GeoTIFF files that have NO information about
      the coordinate system that applies to them --- they'll have just
      enough information to know what the numerical coordinates of each
      pixel are, but no information to tell you whether those coordinates are
      UTM, Lat/Lon, State Plane, or anything else.  For such maps you will
      need to determine the coordinate system by finding external files
      called "metadata" that are associated with the images.  US
      Federal datasources have a standardized file format (".fgd") that
      provides this information, but many state or university GIS departments
      just make some other format up for themselves.  Most sources of
      map data should have such metadata available, but sometimes it is a bit
      of a chore to find it.

      You can determine whether a .tif file has coordinate system information
      in it using the "gdalinfo" command from the GDAL suite or "listgeo" from
      the libgeotiff distribution.  If gdalinfo shows something like this:

        Driver: GTiff/GeoTIFF
        Size is 5364, 7620
        Coordinate System is `'
        Origin = (588067.750000,5331248.500000)

      you're the lucky owner of a file that has no coordinate system info
      (because the only thing after "Coordinate System is" is a pair of
      quotation marks).   Another dead givaway would be:
         Metadata:
           TIFFTAG_SOFTWARE=Arc/Info
      which tells you that the image was processed with a piece of software
      that fails to put in all the right tags.

      If you get maps whose metadata say are in UTM projection but for which
      gdal indicates missing geoTIFF tags like it does in the example above,
      xastir won't be able to display them unless you fix them up.
      Fortunately, the GDAL library tool "gdal_translate" can do the
      job.  For example, if you have a source map with metadata that
      says it's in UTM Zone 10, NAD83 datum, to make it suitable for
      Xastir to read you can do something like this:

      gdal_translate -a_srs EPSG:26910 original.tif georeferenced.tif

      The inclusion of the "-a_srs" option to gdal_translate
      forces the new tiff file to have the correct geotiff tags to
      indicate that coordinate system.

      The EPSG number to use for images in UTM projection with NAD83
      datum is 26900 plus the UTM zone number.  The EPSG number for UTM in
      NAD27 is 26700 plus the zone number.  The above command
      will allow Xastir to read in the image and reference it
      properly.  If you do the gdalwarp option above instead, you can end up
      with solid color areas between the edges of the original image
      and the lat/long rectangle that the image will be warped to; these
      extra pixels represent "no data" areas due to the difference in shape
      between the original rectangular image and the warped image.   The
      color of this area depends on the colors present in the original
      image; GDAL attempts to use a color that is different from any in the
      source image.  If those areas don't matter to you, then either
      method will work for you.  If you're planning to tile multiple
      UTM images together, then the gdal_translate option is best.

      If your maps are NOT in UTM, you must also gdalwarp, because xastir
      cannot properly display geotiffs that are in projections other than
      UTM or "unprojected" lat/lon.

      EPSG numbers for odd-ball coordinate systems can be found at
      http://www.remotesensing.org/geotiff/proj_list/Wkt_adam.zip

      Maps that require gdalwarp include the FAA sectionals mentioned above,
      and some topo maps in obscure state plane coordinates from various state
      GIS departments.

    XASTIR can only use GeoTIFF files that are 8-bit per pixel with one band

      Some geotiff files contain multiple bands or multiple bytes per pixel.
      Xastir currently uses only BYTE format, so you may need to convert the
      geotiff file with gdal_translate.  The number of bands, bytes per
      pixel and other information about geotiff files can be obtained using
      gdalinfo.

      One-band, 16- or 32-bit-per-pixel:
       The command "gdal_translate -ot BYTE original.tif new.tif"
       can convert 16 and 32 bit per pixel geotiffs to ones that can be used
       by xastir

      Multiple band, 8-bit-per-pixel:

      The command "gdal_translate -ot BYTE -b 1 old.tif new.tif"
      can extract a single band as a grey scale layer from a multi-band
      geotiff file, but this is probably not what you really want.
      The command
            rgb2pct.py old.tif new.tif
      can create a single band palette based geotiff from a three band rgb
      tif by dithering the colors down to a small pallette.  This last
      tool requires gdal built with Python support.  See the gdal
      documentation for these tools for further information.

    More manipulations of GeoTIFF files:

      gdal also provides several additional tools that can be used to
      tile maps or chop them up into smaller pieces, but explaining the
      details of that process is probably beyond the scope of this document.
      See the man pages for "gdal_translate" and "gdal_merge.py" for
      an explanation of how those tools could be used to accomplish this.

    .geo files/online maps & graphics:

      If you have ImageMagick and wget or libcurl installed, .geo files
      for NWS radars are available from one of these sites:

          ftp://gcpoolz.com/geos/Srb_geos.zip
          http://we7u.wetnet.net/xastir/maps/radar-geos.tgz

      You'll probably want to add an IMAGESIZE line to each one to speed up
      loading when some radars are offscreen: (bash syntax, modify for your
      shell...)

          for a in srb_*; do echo "IMAGESIZE 620 620" >> $a; done

      NOTE:  For .geo files with an ftp or http address for fetching the image,
      IMAGESIZE is currently a REQUIRED parameter in the .geo file.  For .geo
      files where the image is resident on your hard drive, the IMAGESIZE tag
      is optional.

      Please also note that the coordinates in the .GEO files are expressed
      in decimal degrees, and are listed with longitude first then latitude
      on the TIEPOINT lines.

      Other tags you can put in a .geo file:
      DATUM: (not used, yet...)
      PROJECTION: Currently only supports "TM" for transverse Mercator.
      REFRESH: number of seconds to reload the maps.  Multiple maps
          with different values pick the smallest value.
      TRANSPARENT:  Color to remove from the background (make it transparent).
          Use a number, 0=black.  Color-mapped images use the map value, so
          white is usually 0xffff.  Value can be decimal or hex if preceeded
          by "0x".  Multiple TRANSPARENT lines can be used in a file to make
          multiple colors transparent.
      CROP: removes borders.  Values are [left top right bottom] with
          (0,0) at the upper left.  A good value for the NWS radar
          images above is "CROP 35 20 616 600"
      GAMMA, CONTRAST, NEGATE, EQUALIZE, NORMALIZE, LEVEL, MODULATE:  These
          are all ImageMagick options, and are documented there, and
          briefly in the xastir help file.


     "Find Address" feature (US only):

      The "Find Address" feature is based on the open source geo-coder by
      Dan Egnor and as such uses the same format for the data. You can
      download preprocessed data based on Census Tiger 2003 data at:
      http://www.dementia.org/geocoder/tgr2003/

      Reprocessed geocoding files from the 2006 Second Edition TIGER/Line
      data were produced by Jason Winningham in June of 2007 and made
      available on the TAMU FTP server by Gerry Creager.  They are much
      better than the 2003 data, and it is recommended that they be used
      instead.  Download them from
         ftp://aprs.tamu.edu/pub/geocode/

     Geographic Names Information System Labels:

      These aren't maps, but are collections of name labels for locations.
      These display at various zoom levels like Dos/WinAPRS map labels, but are
      also searchable from the Maps menu.

         http://geonames.usgs.gov/

      Click the link "Download GNIS Data: State and Topical Gazetteers" on
      the left.

      These files should be renamed in the form "<ST>.gnis" after download,
      where <ST> is the abbreviation for the state that they cover, and
      should be placed in the /usr/local/share/xastir/GNIS/ directory. To
      make sure that maps are layered correctly with GNIS labels on the top
      of the map stack, plus searchable, it is suggested that you link
      /usr/local/share/xastir/maps/z to this GNIS directory.

      Type this as root to create the link and directories:
       cd /usr/local/share/xastir/maps
       ln -s ../GNIS z

      The map files must end in ".gnis" to be used by Xastir, and must be in
      pipe delimited format.  These are readily available from the above link
      with such filenames as "AZ_DECI.TXT". The files must be renamed to
      <ST>.gnis, and the trailing whitespace should be removed for speed. This
      can be accomplished in one step with the following command. (bash
      style...)

   for a in *deci; do sed -e 's/[ ]*$//g' < $a > `basename $a _deci`.gnis; done

      Individual files can have whitespace removed as follows:
        sed -e 's/[ ]*$//g' < inputfile > outputfile

      Populated places GNIS file can be had at:

          http://geonames.usgs.gov/stategaz/POP_PLACES_DECI.zip

      A note from Jason Winningham, kg4wsv:

      "The file has over 181k records in it.  You can use the following command
      to weed out all places with populations less than 1000, and get it down
      to just under 14k records, which is really fast to load:

        awk -F\| '{if ($17 > 1000) print $0}' \
            /usr/local/share/xastir/GNIS/0pop_places.gnis \
            >/usr/local/share/xastir/GNIS/0pop_places_over_1k.gnis

      I stuck a zero at the beginning of the filename so this would
      show up in the GNIS directory before any of the state files."


     County weather Warning maps (requires shapefile support):

       The latest shapefile format weather maps may be found here:
         http://www.nws.noaa.gov/geodata/

       or more easily found here (but not guaranteed to be the most
       current:
         http://we7u.wetnet.net/xastir/Counties/

       We now have a script in the xastir/scripts directory called
       "get-NWSdata" which fetches the files you need and plops them
       into the correct directory and unzips them.  Run that script
       as root.  It requires "wget" to work.  You may then try the
       NWS-TEST.log test shown below to verify proper operation.

        --------------------------
        The files of interest are:
        --------------------------

        NWSI Libraries:
        ---------------
        County Warning Area Boundaries (c_*.zip)
        Public Zone Boundaries (z_*.zip)
        Coastal and Offshore Marine Zones (mz*.zip, oz*.zip, hz*.zip)
        Fire Weather Zone Boundaries (fz*.zip)

        County Libraries:
        -----------------
        AWIPS Counties (w_*.zip)

      Unzip those files in the /usr/local/share/xastir/Counties/ directory and
      Xastir should find them and use them for weather alerts. Be sure to
      include the .shp, .shx, .and dbf.

       Note that you can also use the county file as the background polygon
       filled map for drawing county lands and borders.  Either make a link
       to these files from your maps directory, or copy the files there so
       that they show up in the Map Chooser.

      To test whether the weather alerts are working (whether weather?), copy
      the NWS-TEST.log file to your ~/.xastir/logs/ directory and then bring it
      in to Xastir using the File->Open Log File option.  Zoom in to the
      WA/OR/ID area (Pacific Northwest) and you should see a picture that looks
      like this:  <http://www.eskimo.com/~archer/xastir/xastir-wx-alerts.png>
      Note that you may have to change the dates embedded in the file if Xastir
      thinks they are expired.  See the notes at the top of that file.  If the
      alerts are still active they should appear in the View->Weather Alerts
      dialog.

	Australian rules Weather Alerts

		http://wxsvr.aprs.net.au/implementation.html

     Download audio files:

       To play the wav files you will need a program such as vplay to play the
       audio file through your sound card.

       Grab xastir-sounds.tgz at the ftp site you downloaded Xastir, or at
        ftp://ftp.tapr.org/software_lib/Linux/xastir/xastir-sounds.tgz

       Un-tar the file.  Put the sounds files into the
       /usr/local/share/xastir/sounds directory where Xastir can find them.
       (FIXME: thunder.wav is missing?).

     Download FCC and/or RAC Database files:

       If the FCC database is installed, a Search FCC Database button will
       appear in the station info box. If the RAC (Radio Amateurs of Canada)
       database is installed, a Search RAC Database button will appear for
       callsigns beginning with "VE" or "VA".

       The download and installation of these is automated in the get-fcc-rac.pl
       script included with Xastir, but you may install them by hand
       individually if you wish as described here:

       To use the FCC lookup:
       ----------------------

         Download:
         http://wireless.fcc.gov/uls/data/complete/l_amat.zip

         (The only file needed from this 87 Meg zip is the EN.dat file)

         **** NOTE To use the data base file it must be sorted first!!! ****

         unzip l_amat.zip

         To sort the file, make sure you have plenty of disk space for this as
         the file is BIG!

         cat EN.dat | /usr/bin/perl -pe 's/\r\r\n//g' | sort +4 -t \| > EN.dat.sorted

         Install it in the xastir/fcc directory:

         su
         mv EN.dat.sorted /usr/local/share/xastir/fcc/EN.dat


       To use the RAC lookup:
       ----------------------

         Download:
         http://205.236.99.41/%7Eindicatif/download/amateur.zip

         unzip amateur.zip
         mv AMATEUR.RPT /usr/local/share/xastir/fcc/AMACALL.LST


       Hiking trails from National Geographic's Topo or mapXchange:
       ------------------------------------------------------------

        For those of you who may be familiar with National Geographic's Topo!
        program, there's a way to use the user-saved data (but not topo maps
        themselves) from within Xastir.  Many users create TPG and/or TPO
        files in TOPO from GPS data and/or hand-drawn routes.  They can then
        upload them to the mapXchange site, and in fact there are many hiking
        trails that one can download for free from that site.  Okay, how to use
        them?

        Go to <http://www.gpsbabel.org>.  Go to the Project page and then the
        CVS page and follow the instructions for grabbing the CVS gpsbabel
        sources.  Only CVS has the Topo version 3.x support, which was just
        recently added (May 2006).  Follow their instructions for building/
        installing/using the program.  It's a command-line program where you
        specify the input and output formats and filenames.  Using this program
        you can snag the interesting data out of the files and convert it to
        GPX format.  Once you have that, you can use the "gpx2shape" script to
        convert them to Shapefiles.  Xastir can then use them as map files.



WHERE TO FIND MORE INFO ON MAP DATUMS, ETC:

    Geodesy:
    http://oceanservice.noaa.gov/education/geodesy/welcome.html

    "Geodesy for the Layman"
    http://www.ngs.noaa.gov/PUBS_LIB/Geodesy4Layman/toc.htm



MAP CACHING (WORKS WITH MOST ONLINE MAPS):

    Map caching works in conjunction with the map download routines,
    which fetch maps from http or ftp addresses.  The map caching features
    use functions found in Berkeley DB 4.0 library, AKA libdb (version 4.0
    or better), to create and manage a cache directory and a persistent
    database of information about the files in the cache directory.  This
    directory defaults to ~/.xastir/map_cache.  The files under this
    directory can be cleaned up or removed by hand at any time - the
    caching routines will simply download the maps and put new entries
    into the .db file.

    Map files are saved with filenames that include the number of seconds
    since the Unix epoch.  This allows the caching routines to easily
    determine the age of maps so that older cached maps can be deleted.
    This is currently (Dec 2004) controlled with a compile time maximum
    age setting.  See map_cache.h for specifics and for brief
    documentation about all of the map_cache functions.



DRAWING YOUR OWN MAPS USING XASTIR ITSELF:

    The final result here will be ESRI Shapefile vector maps that
    you can then use within Xastir.  You'll need Shapelib compiled
    into Xastir to make use of this feature (the private copy of
    Shapelib is fine for this).

    Turn off Object Transmit first (Interface menu).

    Place an object or item at the start location of your route.

    Click on the "Move" button to active move mode, then move that
    object around the map.  Once you're done you'll have a bunch of
    straight lines that depict the course.

    Now bring up Station Info on that object and click on the Store
    Track button.  If you've got Shapelib compiled in, you'll get a
    shapefile created with the track you just drew.

    After you're done you can delete the object and then turn on the
    Object Transmit toggle again.  You'll end up transmitting the
    deleted final position of the object for a few hours unless you
    kill/restart Xastir, but that's ok.  Nobody will see it on their
    maps 'cuz it's a deleted object.

    Look in ~/.xastir/tracklogs/ for the Shapefile.  Copy it to your
    maps directory, changing the name on the three files as you
    like, then create a dbfawk file for it if you want to change how
    it is drawn in Xastir.

    Another way would be to drive the course with a GPS and then
    download the track via Xastir/GPSman to create a Shapefile map.

    Yet another way would be to drive it with an APRS rig and then
    Store Track as described above.  You could also drive with
    GPS/Xastir (without APRS) to get a very detailed track and then
    save your own track.



DRAWING SAR SEARCH SEGMENTS IN XASTIR:

    Turn on "Draw" mode (togglebutton at the top of the main
    window).  The cursor should change to the Measure/Draw symbol.

    Using the middle mouse button, click on each vertice until you
    are almost done describing a polygon (don't close it yet).  If
    you don't have a middle mouse button, clicking on BOTH mouse
    buttons at once will do it if you have "emulate third mouse
    button" enabled in your X-Windows configuration.

    Go to Map->Draw CAD Objects->Close Polygon.  The polygon will
    get completed, the area enclosed will be computed, and a dialog
    will pop up asking you for more information.  You do not have to
    enter any information in this dialog, but a name of some type is
    helpful in order to be able to identify each segment when
    modifying/deleting/viewing these segments.

    Note that these CAD Objects get saved in a file and reloaded
    each time you start Xastir, but they cannot currently be written
    out as a map file and used as a general map.

    Note also that these CAD Objects don't get transmitted.  They
    are currently for local display only.

    The display of various kinds of data related to these segments
    can be modified in the Map->Draw CAD Objects menu.  Modifying
    parameters for any segment is done in the
    Map->Draw CAD Objects->CAD Polygons dialog.

    Click on the dashed line in the menus in order to separate that
    menu from the rest and allow you to keep the menu on the screen.
    This is very useful when drawing CAD Objects or changing
    display/filtering options.

    Turn off "Draw" mode when you're done.  The cursor should return
    to normal.



SUMMARY OF DISTANCE/AREA/ANGLE CALCULATIONS:


    DISTANCE:
    ---------
    *) Haversine formula (2-parameter atan version) for computing
    distance between two points, for our general distance routines:

        calc_distance()
        calc_distance_course()
        distance_from_my_station()

    *) Haversine formula (2-parameter atan version) in "Measure" for
    both the X/Y offsets and the total distance.

    Haversine formula is more accurate for shorter distances than
    spherical trigonometry calculations.  Both methods are equivalent
    for longer distances.  Both are Great-Circle calculations (as
    opposed to Rhumb-line or planar geometry).  See the GIS FAQ for info
    on these methods.  Dr. Math website mentions both of these and refers
    people to the same GIS FAQ.

    Also note that the Haversine formula is ill-conditioned if the
    two points are antipodal (on opposite sides of the Earth).  From the
    GIS FAQ: "but the error, perhaps as large as 2km (1 mi), is in the
    context of a distance near 20,000km (12,000 mi)."  For our purposes
    that's just fine.


    AREA:
    -----
    *) Area of a spherical rectangle from Dr. Math's website for the
    "Measure" function.  There are errors in their last two derived
    formulas.  They have been notified of it.  Our implemented code
    is correct.

    *) The area calculation for CAD Object Polygons is probably not
    spherical, but closer to planar.  It might take some doing to calculate
    the area of irregular polygons on a spherical surface.  We use Greene's
    Theorem to compute the area based on the vectors.  The lengths of each
    vector are computed via the Haversine formula, so it's not strictly a
    planar area calculation either.  Somewhere in-between planar and spherical?
    This should be plenty good enough for areas that are less than 12 miles on
    a side (that's about where planar geometry starts to diverge from spherical
    trigonometry), perhaps also for somewhat larger areas than this due to the
    advantage of computing the vector lengths with the Haversine formula.


    ANGLE:
    ------
    *) Great Circle departure angle for the "Measure" function.

    *) Great Circle departure angle for the calc_distance_course()
    function.

    *) Dead-reckoning angle is essentially a Rhumb-line calculation
    (constant heading), with a few caveats:

        We compute the next point along a constant angle based on the last
        position transmitted, the time elapsed, and the course desired.
        This then gets corrupted a bit either by the standard APRS grid that
        it has to snap to (and the position snapped to for the previous
        position) and/or by the relatively course angle available for Base-91
        compressed positions.

        Standard APRS positions give 1-degree angular resolution but 60-foot or
        so grid points.  Base-91 Compressed positions give something like 1 to
        3-foot grid points but less angular resolution (+/- 2 degrees.  We
        can't win!

        The end result is that we start off like a drunk sailer due to our
        short transmit times and the above limitations, then the angle smooths
        out as the time increases between the transmits.  You can see this
        easily at zoom level 1 when you place an object, when you make a change
        to an object, or move an object (transmit rate goes up for any of these
        conditions).

    Dead-reckoning effectively does a Rhumb-Line calculation as it is
    trying to do a constant heading.  That means it is not the shortest
    distance between the points.  I'm still trying to get my head around
    that last concept as it is counter-intuitive to someone versed in
    compass/maps on land and with shorter distances.

    A Great-Circle route is the shortest distance between two points on
    a sphere, whereas a Rhumb-line is what you get if you move along a
    constant compass heading and is a bit longer.

    We probably do not need to go to ellipsoid calculations for Xastir.
    Spherical calculations should be easily accurate enough for what we do.



  ------------------------------------------------------------------------
APRS(tm) is a Trademark of Bob Bruninga

Copyright (C) 1999 Frank Giannandrea
Copyright (C) 2000-2019 The Xastir Group

Copyright (C) 2000-2019 The Xastir Group


  Using OpenStreetMap in Xastir
  ------------------------------------------------------------------------
  CONTENTS
     Introduction
     Map Types
     Map Sources and Renderings (Styles)
     Map Cache
     Sharing Tiles
     Map Definition Files
     Copyrights and Licenses


  Introduction
  ------------
    What, you may ask is 'OpenStreetMap' (OSM)? From the web site,
    www.openstreetmap.org, we read that

        "OpenStreetMap is a free editable map of the whole world.
         It is made by people like you".

    The tag line for the map is "The Free Wiki World Map".

    Xastir will display bitmap versions of the OSM. There are multiple
    renderings of the OSM to choose from and, by default, nine (9)
    are available in Xastir.

  Map Types
  ---------
    Xastir can use two different map types based on OSM: static and
    tiled. Static maps are bitmaps that are least as large as the Xastir
    window. Tiled maps are built up from 256x256 pixel images.

    Static maps are also assembled from tiles, but the assembly occurs
    at the server and the full size image is downloaded to Xastir. There
    is a major disadvantage to static maps: even slight changes in map
    position requires a new map download.

    Most online maps, includng OSM, use map tiles that follow the "Web
    Mercator" projection and tiling scheme. The Web Mercator
    projection was first popularized by Google Maps. It is a modified
    Mercator projection, using a hybrid spheroid/ellipsoid model that
    is faster to compute. Wikipedia has a nice description:
    https://en.wikipedia.org/wiki/Web_Mercator.

    Map tiles are referred to by their zoom level, and row and column
    number. Major providers (such as OSM, Google, Apple, Mapbox, and
    Bing) and open source projects (such as Open Layers and
    openmaptiles.org) use the same general tile numbering scheme,
    although they vary in the specific sequence of zoom/row/column
    numbers, and the supporting parts of the URL. The URL for a
    particular tile looks something like this:
    https://a.tile.openstreetmap.org/11/329/715.png
    (tile server a, zoom level 11, column 329, row 715).
    You can see more in this Wikiepedia article:
    https://en.wikipedia.org/wiki/Tiled_web_map.

    Bitmap images, whether static or tiled, are available for only a
    limited number of zoom levels. There are 18 possible zoom levels.
    It takes 2^zoom tiles to represent 360 degrees. Since the tiles are
    256 pixel squares, there are 2^(zoom + 8) pixels in 360 degrees.

    When the Xastir scale is different from a bitmap image's zoom
    level, the bitmap image is scaled. However, scaled bitmaps tend to
    look ugly. The scaled bitmap can have jagged lines, unequal pixel
    sizes, and/or missing information. At best a scaled bitmap looks
    blurred, but more typically some pixels will be enlarged into visible
    blocks or compressed invisibility.

    You can use the F4 key to adjust the Xastir scale to approximate the
    OSM zoom level and refresh the display. (The key can be changed by
    modifying a variable in the OSM definition (GEO) files.


  Map Sources and Renderings (Styles)
  -----------------------------------
    The OSM data is rendered into tiles using different styles. The
    easiest place to view and compare the styles is at
    http://ojw.dev.openstreetmap.org/StaticMap/?mode=Style&

    Tiles can be retrieved from a number of servers. The supplied map
    definitions will download tiles from http://tile.openstreetmap.org/

  Map Cache
  ---------
    Static maps are cached with other bitmap map images in the
    ~/.xastir/map_cache/ directory.

    Tiles are cached separately to make it possible to share them
    with other applications. By default tiles are cached in
    ~/.xastir/map_cache/OSMtiles/, but that location can be changed on a
    by-style basis. The tiles are organized directories by style, zoom
    level, and longitude:

      ~/.xastir/map_cache/OSMtiles/
                             + <style1>/
                             |    + <zoom>/
                             |         <longitude>/
                             |            + [0 ... (2^zoom - 1)].png
                             + <style2>/
                             ...

     Note that 'longitude' is a tile number between 0 and (2^zoom -1).

     Xastir downloads tiles as needed. If Xastir is compiled with
     libcurl support, then it will check for updates to tiles that have
     been cached for 7 days or more.
     See http://wiki.openstreetmap.org/wiki/Tile_usage_policy

     If a tile can not be downloaded for any reason or if the downloaded
     file is not usable image, then the downloaded file (if any) will be
     deleted and a red area will be shown in it's place on the display.

     NOTE: Run Xastir at debug level 512 (-v 512) for more information
           on download issues. At debug level 512, corrupt tile files
           will not be deleted. Examining the contents of the corrupt
           files can be informative.

           If Xastir is compiled with libcurl support, then debug level
           8192 will enable verbose output from libcurl.

     WARNING: Corrupt tile files will not be deleted when running at
              debug level 512. If you do not delete them manually before
              restarting Xastir, then the first time Xastir displays the
              tile it will be shown in red and then deleted from the
              cache.


  Sharing Tiles
  -------------
     The directory structure used to cache tiles is common to other
     programs, though the style names are typically different. An
     example of a program that can share tiles with Xastir is TangoGPS
     (http://www.tangogps.org).

     Here are some examples of how you can share tiles with TangoGPS
     (the setup for other programs would be similar):

       1) Setup a symlink at the style level of the caches
           $ cd ~/.xastir/OSMmaps/
           $ ln ~/Maps/<tangoStyleName>/ <xastirStyleName>

       2) Change the Xastir map definition file to specify the TangoGPS
          cache by changing the following variables (see the next
          section for more information):
             OSM_TILED_MAP-<tangoStyleName>
             TILE_DIR /home/<user>/Maps

       3) Share all styles and tiles by creating a symlink at the top
          level of the cache. This also requires changing the Xastir
          map definition files to specify the style names used by
          TangoGPS:
             $ cd ~/.xastir
             $ rm -rf OSMmaps/
             $ ln -s ../Maps OSMmaps


  Map Definition Files
  --------------------
    OSM map type, style, server, cache directory, and function keys are
    specified in Xastir GEO files. By default the files are located in
    the /usr/local/share/xastir/maps/Online/ directory. The supplied
    definition files have filenames of this form:

       OSM_<name>.geo        - static maps
       OSM_tiled_<name>.geo  - tiled maps

    Where <name> is replaced with the style name. Note that <name> could
    be any unique string and is not required to be the style.

    Read the comments in the supplied definition files for more
    information.


  Copyrights and Licenses
  -----------------------
    Maps and tiles from the OpenStreetMap project are
    Copyright OpenStreetMap and contributors, CC-BY-SA

       http://www.openstreetmap.org/
       http://creativecommons.org/licenses/by-sa/2.0/

    in addition, tiles from CloudMade are
    Copyright CloudMade, CC-BY-SA

        http://www.cloudmade.com/
        http://cloudmade.com/about/api-terms-and-conditions
        http://cloudmade.com/terms_conditions

    TopOSM tiles are a composite of CC-BY-SA and public domain data,
    including MassGIS data. See
    http://wiki.openstreetmap.org/wiki/TopOSM for more information.

  Changing the Displayed Attribution
  ----------------------------------

    The licenses from OpenStreetMap and CloudMade require attribution
    that is met, in part, by a label shown at the top left corner of the
    map. Two label images have been provided, one shows icons and the
    other shows black text on a white background.

    You can change between the two label styles by changing a symlink:

       $ cd /usr/local/share/xastir/maps/   # your installing may differ!
       $ rm CC_OpenStreetMap.png
       $ ln -s CC_OpenStreetMap_txt.png CC_OpenStreetMap.png
          or
       $ ln -S CC_OpenStreetMap_logo.png CC_OpenStreetMap.png


  ------------------------------------------------------------------------

# Developer notes on creating releases

Since the move to git, the old process we followed to push development
snapshots and stable releases to SourceForge is no longer possible,
nor especially helpful.  With git and github, we are doing away with
the concept of development snapshots, because one can always just
download a tarball of the current repo state from github.  We are also
simplifying the stable release process, doing away with the difference
between building a tarball release and building from a git clone.


## Development snapshots

Xastir migrated to git and github instead of cvs and sourceforge, and
therefore creating "development snapshots" isn't necessary, because
every commit is essentially a development snapshot that can be checked
out by referencing its SHA-1 hash.  Furthermore, github allows users
to download code as a tarball directly without needing to clone, so we
need not make a duplicate process for it.

## Stable Releases

Stable releases are the enduring, numbered releases that tend to make
it into official package repositories (eventually).  It is necessary
to do more for these releases than just tag a repository state,
because most package management systems require that a stable version
of the code be downloadable, and don't support pulling
versions-of-the-day out of source code management systems.

Beginning with release 2.1.8 we stopped providing "configure" scripts
and all the droppings from "bootstrap.sh" in release tarballs, and all
users must now use "bootstrap.sh" as a first step in building Xastir.

### Stable release process in a nutshell

- Get master ready for a release.
- Update version number.
- Test everything.
- Tag the repo.
- Push the repo and the tag to Github.
- Define a release on github and associate it with the tag.
- Email interested parties that there has been a release.
- Go back and update the version number on master and move on.

### Stable release in gory detail

- Make sure the current state of the master branch is what you want to
  release.  This should include all documentation updates and help
  file updates.  Only when the master branch is really ready to
  release do you perform the following steps.  Let's assume we're
  creating release X.Y.Z, and that our Xastir clone and working
  directory is in ~/XASTIR/Xastir.

- By our long-standing convention, stable releases are always even
  numbers in the last field of the release number, and odd numbers
  mean "this is a development version."  So whatever version number
  appears in configure.ac on the master branch is going to be odd at
  the moment, and you're going to pick X.Y.Z so that the new Z is
  even.

- Change the version number in configure.ac to X.Y.Z.  Grep around the
  code and remember to fix any other places where the old version
  string appears (there should, at this point, not be any).  Commit
  this change:

      git add configure.ac
      git commit

  Mention why you're doing this in the commit message (e.g., "Update
  release version number").  Follow our commit log message guidance in
  CONTRIBUTING.md

- Run bootstrap.sh

- Make sure the program builds:

      mkdir build
      cd build
      ../configure [options]
      make
      cd ..

  For safety's sake, you should remove the build directory now, too.

      rm -rf build

- You now have a working directory that should look
  like what we want to distribute to users.  Check that there are no
  uncommitted changes:

      git status

  should tell you you're on master, and that you're one commit ahead
  of "origin/master", with nothing to commit and a clean working tree.
  If it says anything else, figure out why and get the current working
  tree to the right state, with all important changes committed
  properly.

- Create an annotated tag marking the current state of the repo as
  your new release:

      git tag -a -m "Xastir Release X.Y.Z" Release-X.Y.Z

- At this point, you are almost done, but all of your changes are only
  in your local repository clone.  Double check that it really works
  by creating a tar file of your code from the tagged state, then try
  to build it somewhere other than in your git checkout directory:


      git archive --format=tar.gz --prefix=Xastir-Release-X.Y.Z/ Release-X.Y.Z > ~/src/Xastir-Release-X.Y.Z.tar.gz

  This process will exactly reproduce what Github will be doing when
  we're finished and actually create the release.  Now make sure it builds:

      cd ~/src
      tar xzf Xastir-Release-X.Y.Z.tar.gz
      cd Xastir-Release-X.Y.Z
      ./bootstrap.sh
      mkdir build
      cd build
      ../configure [options]
      make

- If the sanity check above worked, you can throw away the testing
  tarball and unpacked code:

      cd ~/src
      rm -rf Xastir-Release-X.Y.Z Xastir-Release-X.Y.Z.tar.gz

  - If the sanity check did NOT work, then you need to go back to
    your original working directory and fix any problems you found.
    Commit your changes, and then MOVE THE TAG so it points to your
    NEW proposed release:

      git tag -d Release-X.Y.Z
      git tag -a -m "Xastir Release X.Y.Z" Release-X.Y.Z

    Now go back and redo the sanity check.  Repeat until the tarball
    you created actually produces a working Xastir.

- Now go back to your working directory and finish up by pushing the
  code and tag to Github:

      cd ~/XASTIR/Xastir
      git push origin master
      git push origin Release-X.Y.Z

- Log in to github and go to the Xastir project releases page at
  http://github.com/Xastir/Xastir/releases.  Click the "Draft a new
  release" button.  Put your tag name (Release-X.Y.Z) into the
  dialog box that says "Tag version" and Github will display a note
  that it found a matching, existing tag.  Fill in the rest of the
  form:

    - Give the release a name ("Xastir Release X.Y.Z") that will
      appear prominently above it in the releases list.

    - Enter some release notes in the large text box below the title
      where it says "Describe this release."  Ideally, you should list
      release highlights (new features, bug fixes, etc.).  Use
      Markdown to pretty up the text, using the Preview tab to render
      the markdown until it looks the way you want it to.

    - Click "Publish Release."


- You have finished releasing the code as far as Github is concerned.
  This new release will now appear on the "Releases" page, along with
  links to tar and zip files for the source code and the release notes
  you just created.  The fixed URL
  https://github.com/Xastir/Xastir/releases/latest will always point
  to the most recent release.  The source code download link will be

    https://github.com/Xastir/Xastir/archive/Release-X.Y.Z/Xastir-Release-X.Y.Z.tar.gz

  with the obvious change for the zip version.

- The last step here is to announce the new release in all the usual
  places.  These days it is probably enough to announce it on the
  xastir mailing list, and possibly the aprssig and linux-hams groups.
  No need to spam every ham radio mailing list.  On the other hand,
  the Xastir wiki does recommend sending notification of all releases
  (both development and stable) to:

      - xastir at xastir.org
      - nwaprssig at nwaprs.info
      - aprssig at  tapr.org
      - aprsnews at tapr.org
      - macaprs at yahoogroups.com
      - aprs at yahoogroups.com

  and stable releases to:

      - SAR_APRS at yahoogroups.com
      - CSAR at yahoogroups.com
      - aprs at mailman.qth.net
      - linux-hams at vger.kernel.org
      - linux at tapr.org
      - linux-hams-using-ax25 at yahoogroups.com

  This list is probably excessive nowadays, and probably contains a
  lot of groups that are long gone.


#### Getting master ready to move on

All of this work got the X.Y.Z release done, which has now been
finished and pushed to github.  Now we need to change the version
number on the master branch so that development versions show a
different version than releases.


- Make sure you're still in your master branch in your main clone:

      cd ~/src/Xastir
      git checkout master


- Edit configure.ac and change the version number to be one higher than the
  release you just did.  So if you just pushed release 2.1.8, set the
  version to 2.1.9.

- Commit this change and push it to github.

      git add configure.ac
      git commit
      git push

  The release is done, and now the repo is ready for further development.

# README
------------------------------------------------------------------------

 Please at least SKIM this document before asking questions. In fact,
 READ IT if you've never successfully set up Xastir before. PLEASE!
 READ IT! If you haven't read this file, and ask for help
 expect to be told to READ the README file first! or RTFM :)

 Contents:

 0.    Important notice
 1.    What is Xastir?
 2.    How do I get Xastir & Git usage
 3.    Quick startup
 4.    Upgrading
 5.    Identification notes
 6.    OS-specific notes
 7.    Gating weather alerts
 8.    Boring legal stuff
 9.    Mailing list
 10.   Documentation
 11.   Obtaining help

------------------------------------------------------------------------

0. NOTICE

   Please read this file carefully before trying to set up Xastir.
   This software was developed to be used by licensed amateur radio
   operators.  You are responsible for any information transmitted
   or propagated on any network.

1. WHAT IS XASTIR?

   Xastir is an open-source project to create a free X11 graphical
   APRS(tm) client. APRS(tm) use amateur radio and Internet services to
   convey GPS mapping, weather, and positional data in a graphical
   application.  It has been developed by and for amateur radio
   enthusiasts to provide real-time data in an easy to use package.

   Xastir currently runs under several flavors of Linux and BSD Unix.
   A few people are running Xastir on Solaris Unix, FreeBSD, Lindows
   and Mac OS X, but there may be small changes necessary in order to
   get Xastir to configure/compile on some systems.  There are a few
   notes below which may help in this task.  Most of the developers use
   Linux which makes it the best supported platform at the moment.

   Xastir is an open-source project: Most sources, documentation, and
   binaries are available under the GPL license, with a few modules
   available under other open-source or public domain licenses.

   More information on Xastir can be found here:

   * http://xastir.org
   * http://github.com/Xastir

   including the latest releases, Git access (lets you
   download the latest developers' code), and information on how to join
   Xastir mailing lists.  Note that you must be subscribed in order to
   post to the mailing lists.

   SmartBeaconing(tm) was invented by Tony Arnerich (KD7TA) and Steve
   Bragg (KA9MVA) for the HamHUD project.  They offer the algorithm to
   other authors as long as proper credit is given and the term
   SmartBeaconing(tm) is used.  Thanks to Tony and Steve for that
   contribution!

   -- The Xastir Group.

2. HOW TO GET XASTIR

   Xastir is currently developed at
   <http://github.com/Xastir/Xastir>
   You can get the latest version of Xastir from there.

   You might try <http://xastir.org> for help and information,
   particularly the Xastir mailing list (listed near the bottom
   of the page).

   * Git USAGE

     Obtain the *very latest* version of Xastir under development by
     using Git.

     See the file README.GIT for more details.

   * Release version tarballs

     You can get the latest packaged release source code without git
     at https://github.com/Xastir/Xastir/releases.  Be warned that packaged
     source tarballs may be quite old and not representative of the current
     state of the project.  We highly recommend not using this method unless
     you have a specific reason to stick to official releases.

3. QUICK STARTUP

   See [README.Getting-Started](README.Getting-Started) for a
   relatively quick overview of how to build and use Xastir.

   Check the Xastir wiki (http://xastir.org) for OS-specific guidance
   for building Xastir on your system.

   WINDOWS USERS:  Please refer to the "README.CYGWIN" file for
   specific instructions.

   See the 'INSTALL' file in the Xastir source tree for detailed
   information about configure.

4. UPGRADING

   Upgrading Xastir that has been built from a recent Git clone
   is as simple as running "git pull" in the source tree and
   recompiling.

5. IDENTIFICATION NOTES

   Packet radio modes, by their very nature, typically identify
   themselves with every transmission. Xastir has a few features
   targeted to people who used Xastir in demonstrations and other
   broadcasts where Xastir itself is used over radio.

   Xastir can auto-ID via voice if Festival is compiled in and/or via a
   message splashed across the screen. It does this identification
   every 9.5 minutes if enabled. These identification modes were
   designed for broadcasting Xastir across fast-scan television (for
   events perhaps). Set the "ATV_SCREEN_ID" variable to 1 to enable the
   screen message, and "SPEAK_ID" variable to 1 to enable festival to
   speak the message. These variables are in the
   ~/.xastir/config/xastir.cnf file.

6. OS SPECIFIC NOTES

   [The OS-specific notes that were here were horribly outdated
   and not maintained.  That text has been removed.  Please
   see the Xastir wiki at http://xastir.org in the "Installation Notes"
   section for OS-specific build guidance.]

7. GATING WEATHER ALERTS, STATIONS, OBJECTS/ITEMS TO RF

   ## Gating NWS Weather Alerts to RF:

   If you wish to gate NWS weather alerts from the Internet onto RF, you'll
   need to create a text file in the users directory as
   ~/.xastir/data/nws-stations.txt
   List each NWS station that you would like to transmit via RF. Wildcards
   are implied for lengths of 3 or greater. Here's what an example file
   looks like:

       #
       # Seattle, WA
       SEANPW
       #
       # Portland, OR (any alert type)
       PDX
       #
       # Pendleton, OR
       PDTNPW
       #
       # Medford, OR
       MFRNPW
       #

   All text should start at the beginning of the line.

   Once that file is in place, you'll need to hook up to at least one
   Internet server that is feeding you the weather alerts. You'll also need
   to have at least one RF interface up and running with transmit enabled on
   that interface. Make sure that "Interfaces->Disable Transmit: All" is not
   selected.  You should now be gating NWS weather messages to RF.

   Turn on igate logging and look at that log file to view what you're
   sending out via RF. Don't forget to turn off logging or set up
   auto-rollover of the log files, else your hard drive might fill up with
   logging info. Auto-rollover of log files is typically accomplished via
   CRON.

   ## Gating Stations, Objects/Items to RF:

   The latest code also allows gating packets from specific stations to RF
   using the above method (except object/item packets).  You can also gate
   objects/items to RF by name.  The same wildcarding rules apply as listed
   above.  Callsigns or object/item names listed in this file are
   case-insensitive, so they'll match any case in received packets.

   Bob Bruninga, WB4APR, recommends gating these calls to RF:

    SCOUTS, SATERN, KIDS, REDCROSS, FOUR-H, YOUTH, GUARD, MARS, JOTA

   See his link: "Generic Callsigns for National Events" off this web page
   for his current list of recommended callsigns:

  http://www.aprs.org/aprs-jota.txt


8. BORING LEGAL STUFF

   Xastir is Copyright � by Frank Giannandrea. Xastir is
   distributed according to the GNU General Public
   License. There should be a copy of this license in the
   file COPYING. If not, write to the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA
   02139, USA.

   As of Xastir 0.4.0 all changes made by the Xastir
   development team to the Xastir source code and any related
   files are Copyright (C) 2000-2019 The Xastir Group. The source
   code will still be distributed according to the GNU General
   Public License as Frank Giannandrea did in the past.

   There is no warranty, implied or whatever. You use this
   software at your own risk, no matter what purpose you put
   it to.

   You didn't pay for it, so don't expect magic.


9. MAILING LIST

   There are currently a couple of mailing lists about Xastir.
   xastir@xastir.org is the one relevant for most users.

   The xastir@xastir.org mail-list is dedicated to Bug
   reports, technical questions, your thoughts or
   suggestions on new features being added to Xastir, things
   that should be removed or fixed, amazing problems that even
   stump the guru's, etc... are what we want to see here.  You
   must be subscribed to the list in order to post messages.

   To subscribe to the Xastir mailing list, send email to:
   xastir-request@xastir.org In the body of the message,
   put "subscribe xastir"; or go to
   http://xastir.org and click on "XASTIR MAILING LISTS" (in the
   "Resources" section near the bottom) to subscribe.

        ### DO NOT SEND FRANK EMAIL ABOUT XASTIR ###

   Frank is no longer developing the Xastir code (although
   he does put a word in every now and then) so don't bother
   e-mailing him. If you have a serious problem, email the
   Xastir mailing list and it will get to the coders.

   Please, before posting to this list, see what things are
   like, and when you do post, read over your post for
   readability, spelling, and grammar mistakes. Obviously,
   we're all human (or are we?) and we all make mistakes (heck,
   look at this document! ;).

   Open discussion and debate is integral to change and
   progress. Don't flame others over mere form (grammar and
   spelling), or even substantive issues either for that
   matter. Please read and follow the mailing list rules.

   A second mailing list, xastir-dev@xastir.org is intended for
   developer's discussion.

10. DOCUMENTATION

    We're trying to get the documentation up to date. If you
    feel that anything is missing here, or that anything should
    be added etc, please email xastir@xastir.org about it,
    thank you.

11. OBTAINING HELP

    Please read the file FAQ, and make sure you've followed any relevant
    instructions in INSTALL. If the problem still exists, feel free to
    ask on the Xastir mailing-list, as described above.


  ------------------------------------------------------------------------
APRS(tm) is a Trademark of Bob Bruninga

Copyright (C) 1999 Frank Giannandrea
Copyright (C) 2000-2019 The Xastir Group

LATEST STATUS:
--------------
The File->Exit and Interface->Interface Control portions work. No other
menu options have been implemented. It will connect to a server and display
raw packets as they come in, but there are no maps, symbols, etc. There's
not any packet decoding either. The networking is both IPv4 and IPv6
compatible. It compiles/runs fine and should be very cross-platform at
this stage (must be compiled on each one though).


INITIAL PREPARATION:
--------------------
Qt4 development tools are required for compiling -or- GUI design. For SuSE
Linux they are in the "libqt4-devel" RPM package. This includes "qmake",
"uic", and "designer" (Qt4 Designer).

You'll also need the gcc-c++ compiler installed. For SuSE Linux that's in
the "gcc-c++" package.

You can do manual builds or builds from within Qt Creator. In general I
describe manual builds here.


MANUAL BUILD:
-------------
  cd Xastir/src/qt
  ./build.sh


RUN THE EXECUTABLE:
-------------------
  cd build
  ./xastir_qt &


GENERAL QT4 NOTES:
------------------
*) Do an out-of-source build to keep the source code directory pristine.
   Perform all configure/compile commands from inside a "build" directory:

   mkdir -p build
   cd build

*) Use QT 4 Designer to create the graphical elements. Each
   dialog/window gets written out to a separate *.ui file.

    designer &
    Open->mainwindow.ui

*) Manual compile of ".ui" files:  Use the "uic" compiler to compile
   .ui files to .h files:  Note:  The "qmake" command below does this
   automatically!

    uic -o *.h *.ui

*) moc -o mydialog.moc mydialog.h

*) Use "qmake -project" to create the initial .pro file for the
   os-independent build system.

*) Include the .h files in the .cpp files for your C++ program.

*) Use "qmake" to build the project.

*) "make"

Examples: (Generic, not for the Xastir project:
  uic -o ui_mydialog.h mydialog.ui
  moc -o mydialog.moc mydialog.h
  qmake -project
  qmake
  make


Once the project branch has been checked-out, these steps issued
from the command-line should compile it:

  cd Xastir/src/qt
  mkdir -p build
  cd build
  qmake ../xastir-qt.pro
  make


Remember also that the *best* way to do multiple builds of an
autoconfiscated code (and a qmake-ified code) is do do out-of-source
builds, not in-source builds. Doing so keeps the source tree
unpolluted with build droppings. Thus,

  mkdir ~/builds/xastir-qt -p
  cd ~/builds/xastir-qt
  qmake ~/src/xastir/qt/xastir-qt.pro
  make

will build the qt stuff, and

  mkdir ~/builds/xastir-motif -p
  cd ~/builds/xastir-motif
  ~/src/xastir/configure
  make

will build the normal build, and neither will interfere with the
other.


libqt4-devel rpm provides these binaries (as well as include files
and others). Those with '*' are the ones we currently use:
*   /usr/bin/designer
    /usr/bin/lconvert
    /usr/bin/linguist
    /usr/bin/lrelease
    /usr/bin/lupdate
*   /usr/bin/moc
    /usr/bin/pixeltool
    /usr/bin/qdbuscpp2xml
    /usr/bin/qdbusxml2cpp
    /usr/bin/qdoc3
    /usr/bin/qhelpconverter
    /usr/bin/qhelpgenerator
*   /usr/bin/qmake
    /usr/bin/qt3to4
    /usr/bin/qttracereplay
    /usr/bin/qvfb
    /usr/bin/rcc
*   /usr/bin/uic
    /usr/bin/uic3


SPECIFIC NOTES:
---------------


Here's what Qt Creator does when you do a Build->Clean All:
-----------------------------------------------------------
Starting: /usr/bin/make clean -w
make: Entering directory `/home/src/we7u/xastir/xastir-qt'
rm -f moc_xastir.cpp
rm -f ui_mainwindow.h
rm -f main.o mainwindow.o moc_xastir.o
rm -f *~ core *.core
make: Leaving directory `/home/src/we7u/xastir/xastir-qt'
Exited with code 0.


Here's a Qt Creator Build->Build All command:
---------------------------------------------
Configuration unchanged, skipping QMake step.
Starting: /usr/bin/make -w
make: Entering directory `/home/src/we7u/xastir/xastir-qt'
/usr/bin/uic mainwindow.ui -o ui_mainwindow.h
g++ -c -m64 -pipe -g -Wall -W -D_REENTRANT -DQT_GUI_LIB -DQT_NETWORK_LIB -DQT_CORE_LIB -DQT_SHARED -I/usr/share/qt4/mkspecs/linux-g++-64 -I. -I/usr/include/QtCore -I/usr/include/QtNetwork -I/usr/include/QtGui -I/usr/include -I. -I. -o main.o main.cpp
g++ -c -m64 -pipe -g -Wall -W -D_REENTRANT -DQT_GUI_LIB -DQT_NETWORK_LIB -DQT_CORE_LIB -DQT_SHARED -I/usr/share/qt4/mkspecs/linux-g++-64 -I. -I/usr/include/QtCore -I/usr/include/QtNetwork -I/usr/include/QtGui -I/usr/include -I. -I. -o mainwindow.o mainwindow.cpp
/usr/bin/moc -DQT_GUI_LIB -DQT_NETWORK_LIB -DQT_CORE_LIB -DQT_SHARED -I/usr/share/qt4/mkspecs/linux-g++-64 -I. -I/usr/include/QtCore -I/usr/include/QtNetwork -I/usr/include/QtGui -I/usr/include -I. -I. xastir.h -o moc_xastir.cpp
g++ -c -m64 -pipe -g -Wall -W -D_REENTRANT -DQT_GUI_LIB -DQT_NETWORK_LIB -DQT_CORE_LIB -DQT_SHARED -I/usr/share/qt4/mkspecs/linux-g++-64 -I. -I/usr/include/QtCore -I/usr/include/QtNetwork -I/usr/include/QtGui -I/usr/include -I. -I. -o moc_xastir.o moc_xastir.cpp
g++ -m64 -o xastir-qt main.o mainwindow.o moc_xastir.o -L/usr/lib64 -lQtGui -L/usr/lib64 -L/usr/X11R6/lib64 -lQtNetwork -lQtCore -lpthread
make: Leaving directory `/home/src/we7u/xastir/xastir-qt'
Exited with code 0.


Here's a Qt Creator Build->Run qmake (I must have something misconfigured in my project):
-----------------------------------------------------------------------------------------
Starting: /usr/bin/qmake /home/src/we7u/xastir/xastir-qt/xastir-qt.pro -spec linux-g++-64 -r CONFIG+=debug QMLJSDEBUGGER_PATH=/usr/share/qtcreator/qml/qmljsdebugger
Exited with code 0.


<I'm pretty sure that Curt's notes below assume that there are
left-over droppings from a previous qmake on another system. None of
those files are still in CVS, so they shouldn't be relevant: you
should always need to do a qmake from a fresh check-out, and you are
highly advised to do an out-of-source build as noted above>

LINUX:
------
For Linux:  Had to run "qmake;make" on a 32-bit system because all the files
had been created on a 64-bit system.  On a 64-bit system just run "make".

SUDO Instructions:
------------------

    "sudo" is a command that can make your life much simpler.  After you set
    it up that is!  By adding a couple of lines to your /etc/sudoers file
    (using the "visudo" command to edit this file), you'll be able to run a few
    commands as root without having to type the root password each time.
    Another thing you can do at that point is automate the entire
    "git pull; mkdir -p build; cd build; ../configure; su; make install"
    process via a script.  Here's how to set all of this up:

    Type "su" to become the root user, then type "visudo".  This will bring up
    the "vi" editor on the /etc/sudoers file.  If you'd like to learn more
    about what I'm going to describe, type "man sudoers" in another window and
    read about this file.  Another man-page that is useful here is the "man
    sudo" page.

    Back to the editing:  There's a section in there for user alias.  Mine is
    labeled "# User alias specification".  Add a line there that reads like
    this:

        User_Alias XASTIR = username1, username2, username3

    where username1, etc, are valid usernames that you wish to be able to do
    Xastir installs.  For instance you might have:

        User_Alias XASTIR = mikey

    Next, add a line near the bottom that reads like this:

        XASTIR ALL = NOPASSWD: /bin/chmod, /usr/bin/make

    Now write out and close the file.  At this point the "mikey" user will have
    root permissions when he/she runs the commands "/bin/chmod" or
    "/usr/bin/make".  Make sure the paths to those programs are correct for
    your system.

    Exit from "su" so that you're a regular (non-root) user again.

    Now, in the "xastir" source directory (mine is in "~/src/xastir"), create a
    script that reads like this.  I named my script  "update-xastir" but nearly
    any name for the script will do:

    -----------------cut here--------------------
        #! /bin/sh

        git pull
        ./bootstrap.sh
        mkdir -p build
        cd build
        ../configure
        sudo make clean
        sudo make install
        sudo chmod 4755 /usr/local/bin/xastir
    -----------------cut here--------------------

    Now type "chmod u+rwx update-xastir" to make that script executable.

    Actually, we've just created a script for Xastir that implements the above
    and called it "update-xastir".  Do a "git pull" to get it.

    Try out the script.  Type:

        ./update-xastir

    It should run through the entire update/configure/make/install process for
    Xastir.  Remember to either change to the proper xastir directory before
    running it, or add a "cd" command at the beginning of the script so that it
    will run in the proper directory in all cases.  If you add the proper "cd"
    command you can copy the script to /usr/local/bin and then run it as
    "update-xastir" from anywhere.

    Windows users:  You may need to remove the "sudo" keyword on each line to
    have it work properly for you.

    A note from Gerry Creager as to another way to set up the sudoers file:

      "I now consider it a good idea to add the "gifted" users to the 'wheel'
      group and then solely enable wheel in /etc/sudoers; I've seen a recent
      article also supporting this."


  ------------------------------------------------------------------------
Copyright (C) 1999 Frank Giannandrea
Copyright (C) 2000-2019 The Xastir Group