.. _tutorial_background:


===================
Tutorial background
===================

Tutorial Timeframe
==================

While some users can go through this tutorial in one day, those who work on each 
example in detail can probably expect to finish in one week.

Tutorial Data
=============

The dataset used in this tutorial was taken from the U.S. Department of the 
Interior's National Atlas of the United States (which is now hosted by 
`data.gov <https://catalog.data.gov/harvest/1997-2014-edition-of-the-national-atlas-of-the-united-states>`__). 
The dataset was clipped to the upper great lakes region (Minnesota, Michigan, 
and Wisconsin) to reduce storage size. Additional raster images were added 
courtesy of the TerraSIP project at the University of Minnesota. When using 
this tutorial, you are encouraged to use your own dataset.

Like MapServer itself, this tutorial is open and customizable to anyone. 
This was done in the hope that someone (or some folks) will help design and 
develop it further.

Download the data (and all html files) for this tutorial at http://download.osgeo.org/mapserver/docs/mapserver-tutorial.zip.

Before Using the Tutorial
=========================

There are some prerequisites to using this tutorial:

1. Users will need to have a web server installed and running on their computer. 
   This web server has to have support for common gateway interface (CGI) programs.

2. Users should have a basic understanding of web servers and internet security. 
   A poorly configured web server can easily be attacked by malicious people. 
   At the very least your software installation will be corrupted and you'll 
   lose hours of productivity, at worst your computer can be used to attack 
   other computers on the internet.

3. It is recommended that users of this tutorial read the 
   :ref:`Introduction to MapServer <introduction>` before proceeding with this 
   tutorial.

4. To use this tutorial, users will need to have a MapServer 
   CGI program (mapserv or mapserv.exe) installed in their systems. MapServer 
   source code is available for download :ref:`here <download>`. Documentation 
   exists on how to compile and install MapServer:
   
   * for UNIX users, please read the :ref:`MapServer UNIX Compilation and Installation HOWTO <unix>`. 
   * Windows users should read the :ref:`MapServer Win32 Compilation and Installation HOWTO <win32>` 
   
   In addition, precompiled binaries exist for a number of platform (see the
   :ref:`download page <download>`).

Windows, UNIX/Linux Issues
==========================

Paths
-----

This tutorial was created on Linux/UNIX but should work with minimal changes on 
Windows platform. The main differences are the paths in the map files. Windows 
users need to specify the drive letter of the hard disk where their tutorial 
files reside. Here's an example:

A UNIX map file might include a parameter like this:

.. code-block:: mapfile

   SHAPEPATH "/data/projects/tutorial/data"
     
In Windows, the same parameters might look like this:

.. code-block:: mapfile

   SHAPEPATH "C:/data/projects/tutorial/data"
     
or:

.. code-block:: mapfile
   
   SHAPEPATH "C:\data\projects\tutorial\data".

Notice that either slash or backslash works in Windows. The usual
backslash may work well for you if you want to make a distinction
between virtual (as in URLs or web addresses) and local paths in your
map file. However, if you plan to move your application to UNIX at
some point, you'll have the tedious task of switching all backslashes
to slashes.

While we're on the subject of paths, keep in mind that paths in
mapfiles are typically relative to the system's root directory: the
slash ("/") in UNIX or some drive letter ("C:") in Windows. This is
true except when specifically asked to enter a URL or when referencing
a URL. When working with HTML template files, paths are relative to
the web server's root directory.  i.e., "/tutorial/" is relative to
"https://demo.mapserver.org/". Please read
http://www.alistapart.com/articles/slashforward/ for a few insights on
URLs.

Executable
----------

Another issue is that UNIX executable files don't require a .EXE or
.COM extensions, but they do in Windows. If you are using Windows,
append .exe to all instances of "/cgi-bin/mapserv" or
"/cgi-bin/mapserv50" to make it "/cgi-bin/mapserv.exe" or
"/cgi-bin/mapserv50.exe".

Other Resources
===============

Other documentation exist to give you better understanding of the many
customizations MapServer offer. Please visit the MapServer
documentation page at http://www.mapserver.org/documentation.html. There you will find
several HOWTO documents, from getting started to using MapScript, a
scripting interface for MapServer.

----

:ref:`Back to Tutorial home <tutorial>` | :ref:`Proceed to Section 1 <tutorial_section1>`
