Commit f413c157 authored by Antoni Bella Pérez's avatar Antoni Bella Pérez 🚵🏻
Browse files

Re-indent (more readable) and remove final whitespaces

parent 2d9d2635
......@@ -4,1497 +4,1212 @@
<!ENTITY % English "INCLUDE"><!-- change language only here -->
]>
<book id="marble" lang="&language;">
<bookinfo>
<title>The &marble; Handbook</title>
<authorgroup>
<author>
<firstname>Torsten</firstname>
<surname>Rahn</surname>
<affiliation>
<address>&Torsten.Rahn.mail;</address>
</affiliation>
</author>
<author>
<firstname>Dennis</firstname>
<surname>Nienhüser</surname>
<affiliation>
<address>&Dennis.Nienhueser.mail;</address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<copyright>
<year>2005</year>
<year>2006</year>
<year>2007</year>
<holder>&Torsten.Rahn;</holder>
</copyright>
<copyright>
<year>2010</year>
<year>2013</year>
<holder>&Dennis.Nienhueser;</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>2013-12-12</date>
<releaseinfo>1.7 (&kde; 4.13)</releaseinfo>
<abstract>
<para>&marble; is a geographical atlas and a virtual globe
which lets you quickly explore places on our home planet.
You can use &marble; to look up addresses, to easily create maps,
measure distances and to retrieve detail information about locations that you have just heard about in the news or on the Internet. The user interface is clean, simple and easy to use.
</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>education</keyword>
<keyword>earth</keyword>
<keyword>globe</keyword>
<keyword>geography</keyword>
<keyword>marble</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<screenshot>
<screeninfo>&marble; logo</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="logo-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; logo</phrase></textobject>
</mediaobject>
</screenshot>
<para>
Welcome to &marble;, a small interactive globe and geographical atlas that puts
the world at your fingertips. Just like a real atlas or a conventional globe
&marble; allows you to freely move across its map and lookup places.
Furthermore &marble; allows you to zoom in and have many different views on the
surface of the Earth. In its default configuration &marble; offers 11 different
views: <guilabel>Atlas</guilabel>, <guilabel>OpenStreetMap</guilabel>, <guilabel>Satellite View</guilabel>, <guilabel>Earth at Night</guilabel>, <guilabel>Historical Map 1689</guilabel>, <guilabel>Moon</guilabel>, <guilabel>Plain Map</guilabel>, <guilabel>Precipitation (December)</guilabel>, <guilabel>Precipitation (July)</guilabel>, <guilabel>Temperature (December)</guilabel> and <guilabel>Temperature (July)</guilabel>.
</para>
<para>
&marble; comes with a small database of more than 12,000 locations (cities, mountains, volcanoes) which can be searched for and which are integrated with
Wikipedia. Additionally you can measure distances using &marble; between multiple measure points which can be set freely.
</para>
<para>
&marble; is free software and licensed under the &GNU; Lesser General Public License.
</para>
</chapter>
<chapter id="quick-start">
<title>&marble; quick start guide: Navigation</title>
<para>Here is &marble; the first time you run it, either with <menuchoice><guimenu>Applications</guimenu><guisubmenu>Education</guisubmenu><guimenuitem>Marble (Desktop Globe)</guimenuitem></menuchoice> from the &kmenu; or with <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo> and entering <command>marble</command> into the field.</para>
<screenshot>
<screeninfo>&marble; main window</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="quick-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; main window</phrase></textobject>
</mediaobject>
</screenshot>
<para>
On the right you can see a topographical map of our beautiful home planet. To allow for
better orientation the map offers a scale bar in the lower left corner as well as a windrose on the top right.
To navigate and to control the view you can use the tools on the <guilabel>Navigation</guilabel> info box at the right: Press the arrow buttons to rotate the globe. The <guilabel>Up</guilabel> and <guilabel>Down</guilabel> arrow buttons will tilt the earth axis back and forth. The <guilabel>Left</guilabel> and <guilabel>Right</guilabel> arrow buttons will make the earth spin around its physical axis.
</para>
<para>
You can accomplish the same behavior by pressing the &LMB; somewhere on the globe and by moving the mouse while keeping the &LMB; pressed. Using this drag and drop style navigation will allow you to adjust the viewing angle much easier and more precisely. The cursor keys on your keyboard offer another alternative way to quickly change directions.
</para>
<para>
Zoom in and out by moving the vertical slider up and down. If your mouse has got a mouse
wheel you can use that one instead - or you just hold the &LMB; and the &RMB; down both at once while moving the mouse up and down.
Changing the zoom level step by step can be done via the <guilabel>Zoom In</guilabel> and <guilabel>Zoom Out</guilabel> buttons which are placed above and below the zoom slider (or using the <keycap>+</keycap> and <keycap>-</keycap> keys on your keyboard).
</para>
<para>
Depending on the map's resolution zooming in will provide you with more detail. Smaller cities will appear and using the topographic map you might notice that coastlines are provided as vector graphics.
</para>
<para>
In case you should get lost you can always reset the viewing angle and zoom level back to the point where we started off: Just hit the <guilabel>Home</guilabel> button (or the <keycap>Home</keycap> button on your keyboard). To set the home location to the current position (center of the map) click on <guimenuitem>Set Home Location</guimenuitem> in the <guimenu>Bookmarks</guimenu> menu.
</para>
<para>A click onto the status bar using the &RMB; offers a menu which lets you customize the appearance of the status bar.
You can show the position, altitude, the current tile level and a progress indicator that displays the status of the map data download.
</para>
</chapter>
<chapter id="map-views">
<title>Choosing different map views for &marble;</title>
<para>
&marble; comes with 11 different views: <guilabel>Atlas</guilabel>, <guilabel>OpenStreetMap</guilabel>, <guilabel>Satellite View</guilabel>, <guilabel>Earth at Night</guilabel>, <guilabel>Historical Map 1689</guilabel>, <guilabel>Moon</guilabel>, <guilabel>Plain Map</guilabel>, <guilabel>Precipitation (December)</guilabel>, <guilabel>Precipitation (July)</guilabel>, <guilabel>Temperature (December)</guilabel> and <guilabel>Temperature (July)</guilabel>. You can choose among these by pressing the <guilabel>Map View</guilabel> tab on the bottom of &marble;'s toolbox:
</para>
<screenshot>
<screeninfo>&marble; map views</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="mapview-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Map Views</phrase></textobject>
</mediaobject>
</screenshot>
<itemizedlist>
<listitem>
<para>
<guilabel>Atlas</guilabel>: A classic topographic map. It uses vector lines ( "MicroWorldDataBase II" ) to mark coastlines, country borders &etc; and bitmap graphics ( "SRTM30" ) to create the height relief.
</para>
</listitem>
<listitem>
<para>
<guilabel>OpenStreetMap</guilabel>: A global roadmap created by the OpenStreetMap (OSM) project. OSM is an open community which creates free editable maps. The OSM data was rendered using Mapnik.
</para>
</listitem>
<listitem>
<para>
<guilabel>Satellite View</guilabel>: Earth as seen from Space. The map is based on NASA's beautiful <ulink url="https://earthobservatory.nasa.gov/Features/BlueMarble/">Blue &marble; Next Generation</ulink> pictures. Credits: NASA’s Earth Observatory
</para>
</listitem>
<listitem>
<para>
<guilabel>Earth at Night</guilabel>: This image of Earth’s city lights was created with data from the Defense Meteorological Satellite Program (DMSP) Operational Linescan System (OLS).
</para>
</listitem>
<listitem>
<para>
<guilabel>Historical Map 1689</guilabel>: A historical world map from the year 1689 created by G. van Schagen in Amsterdam.
</para>
</listitem>
<listitem>
<para>
<guilabel>Moon</guilabel>: A map of the moon. The map is based on data from the Clementine Moon mission (UVVIS Basemap Mosaic). Credits: NASA/SDIO, Courtesy USGS Astrogeology Research Program.
</para>
</listitem>
<listitem>
<para>
<guilabel>Plain Map</guilabel>: A plain map. It uses vector lines to mark coastlines and country borders &etc;
</para>
</listitem>
<listitem>
<para>
<guilabel>Precipitation (December)</guilabel>: A map which shows the average precipitation in December.
</para>
</listitem>
<listitem>
<para>
<guilabel>Precipitation (July)</guilabel>: A map which shows the average precipitation (rain/snow/hail/etc) in July.
</para>
</listitem>
<listitem>
<para>
<guilabel>Temperature (December)</guilabel>: A map which shows the average temperature in December.
</para>
</listitem>
<listitem>
<para>
<guilabel>Temperature (July)</guilabel>: A map which shows the average temperature in July.
</para>
</listitem>
</itemizedlist>
</chapter>
<chapter id="search-places">
<title>Searching places using &marble;</title>
<para>
&marble; comes with a small database of more than 12,000 cities ( from
<ulink url="https://www.populationdata.net/monde/"/> ) and a few mountains and volcanoes.
You can find a location by entering its name into the search line on the
top of the toolbox (&marble; always uses the native name in Latin letters). As you start
typing, suggestions below the search line will appear like this:
</para>
<screenshot>
<screeninfo>&marble; searching places</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="search-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Searching Places</phrase></textobject>
</mediaobject>
</screenshot>
<para>
As you hit <keycap>Return</keycap>, &marble; runners will also query both online and offline searches
to return you even more useful data.
<book id="marble" lang="&language;">
<bookinfo>
<title>The &marble; Handbook</title>
<authorgroup>
<author>
<firstname>Torsten</firstname>
<surname>Rahn</surname>
<affiliation>
<address>&Torsten.Rahn.mail;</address>
</affiliation>
</author>
<author>
<firstname>Dennis</firstname>
<surname>Nienhüser</surname>
<affiliation>
<address>&Dennis.Nienhueser.mail;</address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<copyright>
<year>2005</year>
<year>2006</year>
<year>2007</year>
<holder>&Torsten.Rahn;</holder>
</copyright>
<copyright>
<year>2010</year>
<year>2013</year>
<holder>&Dennis.Nienhueser;</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>2021-01-31</date>
<releaseinfo>2.2 (Applications 12.20)</releaseinfo>
<abstract>
<para>&marble; is a geographical atlas and a virtual globe which lets you quickly explore places on our home planet. You can use &marble; to look up addresses, to easily create maps, measure distances and to retrieve detail information about locations that you have just heard about in the news or on the Internet. The user interface is clean, simple and easy to use.
</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>education</keyword>
<keyword>earth</keyword>
<keyword>globe</keyword>
<keyword>geography</keyword>
<keyword>Marble</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<screenshot>
<screeninfo>&marble; logo</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="logo-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; logo</phrase></textobject>
</mediaobject>
</screenshot>
<para>Welcome to &marble;, a small interactive globe and geographical atlas that puts the world at your fingertips. Just like a real atlas or a conventional globe &marble; allows you to freely move across its map and lookup places. Furthermore &marble; allows you to zoom in and have many different views on the surface for the <guilabel>Earth</guilabel> or the <guilabel>Moon</guilabel> (with his view). In its default configuration &marble; offers 14 different views: <guilabel>Atlas</guilabel>, <guilabel>OpenStreetMap</guilabel>, <guilabel>Satellite View</guilabel>, <guilabel>Earth at Night</guilabel>, <guilabel>Behaim Globe 1492</guilabel>, <guilabel>Sentinel2 Satellite Map</guilabel>, <guilabel>Historical Map 1689</guilabel>, <guilabel>Political Map</guilabel>, <guilabel>Plain Map</guilabel>, <guilabel>Precipitation (December)</guilabel>, <guilabel>Precipitation (July)</guilabel>, <guilabel>Temperature (December)</guilabel>, <guilabel>Temperature (July)</guilabel> and <guilabel>Vector OSM</guilabel>.
</para>
<para>&marble; comes with a small database of more than 12,000 locations (cities, mountains, volcanoes) which can be searched for and which are integrated with Wikipedia. Additionally you can measure distances using &marble; between multiple measure points which can be set freely.
</para>
<para>&marble; is free software and licensed under the &GNU; Lesser General Public License.
</para>
</chapter>
<chapter id="quick-start">
<title>&marble; quick start guide: Navigation</title>
<para>Here is &marble; the first time you run it, either with <menuchoice><guimenu>Applications</guimenu><guisubmenu>Education</guisubmenu><guimenuitem>Marble (Desktop Globe)</guimenuitem></menuchoice> from the &kmenu; or with <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo> and entering <command>marble</command> into the field.</para>
<screenshot>
<screeninfo>&marble; main window</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="quick-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; main window</phrase></textobject>
</mediaobject>
</screenshot>
<para>On the right you can see a topographical map of our beautiful home planet. To allow for better orientation the map offers a scale bar in the lower left corner as well as a windrose on the top right. To navigate and to control the view you can use the tools on the <guilabel>Navigation</guilabel> info box at the right: Press the arrow buttons to rotate the globe. The <guilabel>Up</guilabel> and <guilabel>Down</guilabel> arrow buttons will tilt the earth axis back and forth. The <guilabel>Left</guilabel> and <guilabel>Right</guilabel> arrow buttons will make the earth spin around its physical axis.
</para>
<para>You can accomplish the same behavior by pressing the &LMB; somewhere on the globe and by moving the mouse while keeping the &LMB; pressed. Using this drag and drop style navigation will allow you to adjust the viewing angle much easier and more precisely. The cursor keys on your keyboard offer another alternative way to quickly change directions.
</para>
<para>Zoom in and out by moving the vertical slider up and down. If your mouse has got a mouse wheel you can use that one instead - or you just hold the &LMB; and the &RMB; down both at once while moving the mouse up and down. Changing the zoom level step by step can be done via the <guilabel>Zoom In</guilabel> and <guilabel>Zoom Out</guilabel> buttons which are placed above and below the zoom slider (or using the <keycap>+</keycap> and <keycap>-</keycap> keys on your keyboard).
</para>
<para>Depending on the map's resolution zooming in will provide you with more detail. Smaller cities will appear and using the topographic map you might notice that coastlines are provided as vector graphics.
</para>
<para>In case you should get lost you can always reset the viewing angle and zoom level back to the point where we started off: Just hit the <guilabel>Home</guilabel> button (or the &Home; button on your keyboard). To set the home location to the current position (center of the map) click on <guimenuitem>Set Home Location</guimenuitem> in the <guimenu>Bookmarks</guimenu> menu.
</para>
<para>A click onto the status bar using the &RMB; offers a menu which lets you customize the appearance of the status bar. You can show the position, altitude, the current tile level and a progress indicator that displays the status of the map data download.
</para>
</chapter>
<chapter id="map-views">
<title>Choosing different map views for &marble;</title>
<para>&marble; comes with 11 different views: <guilabel>Atlas</guilabel>, <guilabel>OpenStreetMap</guilabel>, <guilabel>Satellite View</guilabel>, <guilabel>Earth at Night</guilabel>, <guilabel>Historical Map 1689</guilabel>, <guilabel>Moon</guilabel>, <guilabel>Plain Map</guilabel>, <guilabel>Precipitation (December)</guilabel>, <guilabel>Precipitation (July)</guilabel>, <guilabel>Temperature (December)</guilabel> and <guilabel>Temperature (July)</guilabel>. You can choose among these by pressing the <guilabel>Map View</guilabel> tab on the bottom of &marble;'s toolbox:
</para>
<screenshot>
<screeninfo>&marble; map views</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="mapview-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Map Views</phrase></textobject>
</mediaobject>
</screenshot>
<itemizedlist>
<listitem><para><guilabel>Atlas</guilabel>: A classic topographic map. It uses vector lines ( "MicroWorldDataBase II" ) to mark coastlines, country borders &etc; and bitmap graphics ( "SRTM30" ) to create the height relief.</para></listitem>
<listitem><para><guilabel>OpenStreetMap</guilabel>: A global roadmap created by the OpenStreetMap (OSM) project. OSM is an open community which creates free editable maps. The OSM data was rendered using Mapnik.</para></listitem>
<listitem><para><guilabel>Satellite View</guilabel>: Earth as seen from Space. The map is based on NASA's beautiful <ulink url="https://earthobservatory.nasa.gov/Features/BlueMarble/">Blue &marble; Next Generation</ulink> pictures. Credits: NASA’s Earth Observatory</para></listitem>
<listitem><para><guilabel>Earth at Night</guilabel>: This image of Earth’s city lights was created with data from the Defense Meteorological Satellite Program (DMSP) Operational Linescan System (OLS).</para></listitem>
<listitem><para><guilabel>Historical Map 1689</guilabel>: A historical world map from the year 1689 created by G. van Schagen in Amsterdam.</para></listitem>
<listitem><para><guilabel>Moon</guilabel>: A map of the moon. The map is based on data from the Clementine Moon mission (UVVIS Basemap Mosaic). Credits: NASA/SDIO, Courtesy USGS Astrogeology Research Program.</para></listitem>
<listitem><para><guilabel>Plain Map</guilabel>: A plain map. It uses vector lines to mark coastlines and country borders &etc;</para></listitem>
<listitem><para><guilabel>Precipitation (December)</guilabel>: A map which shows the average precipitation in December.</para></listitem>
<listitem><para><guilabel>Precipitation (July)</guilabel>: A map which shows the average precipitation (rain/snow/hail/&etc;) in July.</para></listitem>
<listitem><para><guilabel>Temperature (December)</guilabel>: A map which shows the average temperature in December.</para></listitem>
<listitem><para><guilabel>Temperature (July)</guilabel>: A map which shows the average temperature in July.</para></listitem>
</itemizedlist>
</chapter>
<chapter id="search-places">
<title>Searching places using &marble;</title>
<para>&marble; comes with a small database of more than 12,000 cities ( from <ulink url="https://www.populationdata.net/monde/"/> ) and a few mountains and volcanoes. You can find a location by entering its name into the search line on the top of the toolbox (&marble; always uses the native name in Latin letters). As you start typing, suggestions below the search line will appear like this:
</para>
<screenshot>
<screeninfo>&marble; searching places</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="search-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Searching Places</phrase></textobject>
</mediaobject>
</screenshot>
<para>As you hit &Enter;, &marble; runners will also query both online and offline searches to return you even more useful data.
</para>
<para>The following online search runners are available:</para>
<itemizedlist>
<listitem><para>Nominatim: An online search and reverse geocoding service, using data from <ulink url="https://www.openstreetmap.org"/></para></listitem>
<listitem><para>HostIP: A reverse geocoding based on IP address, using data from <ulink url="https://www.hostip.info"/></para></listitem>
</itemizedlist>
<para>The following offline search runners are also available, depending on extra software and data you have installed:</para>
<itemizedlist>
<listitem><para>Local Database: All placemarks in all open documents will be searched for. This includes your Bookmarks of course.</para></listitem>
<listitem><para>Monav: An offline search service using the data from Monav offline routing information, based on OSM data</para></listitem>
<listitem><para>Gosmore: An offline reverse geocoding service using data from gosmore setup</para></listitem>
</itemizedlist>
<para>Once you have found your search on the map you can click on its label or its symbol using the &LMB;. After clicking the name of the location on the map a data sheet will appear, like this:
</para>
<screenshot>
<screeninfo>&marble; Data Sheet</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="search-2.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Data Sheet</phrase></textobject>
</mediaobject>
</screenshot>
<para>On the first tab of the dialog some very basic data is provided, like the name, coordinates and flag of the country the place belongs to. In addition, population numbers for cities get shown, as well as the elevation for mountains. If your computer is connected to the Internet and if you're online, &marble; will try to connect to the popular Internet encyclopedia <quote>Wikipedia</quote>. If a matching Wikipedia article is available &marble; will display it on the data sheet.
</para>
<note><para>The additional data sources can be enabled using <menuchoice><guimenu>View</guimenu><guisubmenu>Online services</guisubmenu></menuchoice> submenu. For example, you should mark <guimenuitem>Wikipedia</guimenuitem> menu item to see Wikipedia articles.</para></note>
</chapter>
<chapter id="routing">
<title>Find your way with &marble;</title>
<para>Besides searching for places, &marble; can display possible routes between two or more of them. Do you want to plan a bicycle tour in the nearby wood? Need driving instructions to get to an address in a foreign city? Click on the <guilabel>Routing</guilabel> tab on the top of &marble;'s toolbox to start planning your trip.
</para>
<sect1 id="routing-route-new">
<title>Creating a new Route</title>
<para>In the <guilabel>Routing</guilabel> tab you'll see two green buttons <guilabel>A</guilabel> and <guilabel>B</guilabel>. Enter the start address in the input field next to the <guilabel>A</guilabel> button, the route start input field. Press &Enter; or click on the <guilabel>Search</guilabel> button to find matching placemarks. A small progress animation will shorten your waiting time while the search is running. Using the search term <quote>Weavers Lane, London</quote>, the result will look similar to the screenshot below:
</para>
<screenshot>
<screeninfo>&marble; address search</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="routing-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Searching Addresses</phrase></textobject>
</mediaobject>
</screenshot>
<para>Matching placemarks line up in the list below the input fields. They are also shown in the map. The first result is automatically selected as the route start. In the map, this position is indicated using the same <guilabel>A</guilabel> icon as the button next to the route start input field. If the first result is not your desired route start, click on any other result to make that the new start position. You can either click on it in the result list or on its icon in the map to achieve that. The currently chosen route start is always indicated using the <guilabel>A</guilabel> icon.
</para>
<para>With the route start at hand, let's move on to enter the destination of our trip. The procedure is the same: Enter the destination address in the input field next to the <guilabel>B</guilabel> button, press &Enter; and select the desired item among the result list.
</para>
<para>Did you notice that the <guilabel>Search</guilabel> button is now gone and replaced by a <guilabel>Get Directions</guilabel> button? &marble; is signalizing that all information needed to calculate a route has been entered correctly. Click on the <guilabel>Get Directions</guilabel> button to retrieve a suitable route now. If your destination search term is <quote>Sun Walk, London</quote>, the result will resemble this screenshot:
</para>
<screenshot>
<screeninfo>&marble; route result</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="routing-2.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Displaying a Route</phrase></textobject>
</mediaobject>
</screenshot>
<para>If the start (or destination) position is already visible on the screen, you may find it more convenient to select it directly in the map. To do that, click on the <guilabel>A</guilabel> (or <guilabel>B</guilabel>) button next to the input field. Select <guilabel>From Map</guilabel> in the upcoming menu. Once clicked, the map input mode is activated: The next click on a position in the map will become the start (or end) of your trip. The mouse cursor turns into a cross to ease an accurate selection. The selected position will be included in the route and marked in the map. To abort the selection, either click on the button again or press &Esc;.
</para>
<para>An alternative selection of the route start and destination is provided via the context menu of the map: Click with the &RMB; on the desired location and select <guilabel>Directions from here</guilabel> or <guilabel>Directions to here</guilabel>, respectively.
</para>
</sect1>
<sect1 id="routing-profiles">
<title>Route Profiles</title>
<para>Which route to choose depends on the type of vehicle you plan to use (if any). You can tell &marble; about this and other preferences using route profiles. Each profile contains the settings for a certain routing scenario. On the first start, &marble; creates four common profiles for you: <guilabel>Car (fastest)</guilabel>, <guilabel>Car (shortest)</guilabel>, <guilabel>Bike</guilabel>, and <guilabel>Pedestrian</guilabel>.
</para>
<para>The examples in the previous sections used the <guilabel>Car (fastest)</guilabel> profile. Let's revisit the last route with a different profile: Select the <guilabel>Pedestrian</guilabel> option in the <guilabel>Profile</guilabel> combo box. The route now looks like this:
</para>
<screenshot>
<screeninfo>&marble; pedestrian routing</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="routing-5.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Pedestrian routing</phrase></textobject>
</mediaobject>
</screenshot>
<para>The proposed route has become shorter because footways are now also included when calculating the best route.
</para>
<para>If you want to tweak one of the default profiles further, select it in the <guilabel>Profile</guilabel> combo box and click on the <guilabel>Configure</guilabel> link. A new window opens.
</para>
<screenshot>
<screeninfo>&marble; route profile configuration</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="routing-6.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Route Profile configuration</phrase></textobject>
</mediaobject>
</screenshot>
<para>The left side lets you configure which routing backends are queried for routes. Eight or more backends are supported by &marble;, some working online and the other ones working offline. Online routing requires an Internet connection to query a route. Offline routing works without an Internet connection, but requires you to download and install offline routing maps in advance. The supported routing backends are
</para>
<itemizedlist>
<listitem><para>CycleStreets: Bicycle routing for the United Kingdom using cyclestreets.net</para></listitem>
<listitem><para>Gosmore: An offline router that also serves as the backend for the Yours online router</para></listitem>
<listitem><para>MapQuest: An online router which provides advanced turn-by-turn instructions</para>
<note><para>An AppKey is required for MapQuest routing to work. You can register the AppKey <ulink url="https://developer.mapquest.com/plan_purchase/steps/business_edition/business_edition_free/register">here</ulink>.</para></note></listitem>
<listitem><para>Monav: An offline router that is very fast even when calculating very large routes</para></listitem>
<listitem><para>OSRM: An online router that is very fast even when calculating very large routes</para></listitem>
<listitem><para>OpenRouteService: An online router that also generates driving instructions, limited to Europe</para></listitem>
<listitem><para>Routino: An offline router with a very flexible configuration</para></listitem>
<listitem><para>Yours: An online router that operates world-wide, but lacks driving instructions</para></listitem>
</itemizedlist>
<para>Once you select and enable a routing backend on the left to include it in routing queries, you can modify its settings on the right side. The settings are specific to each backend.
</para>
<para>Besides configuring the four default profiles, you can add new profiles and remove existing ones in the &marble; settings in the <guilabel>Routing</guilabel> page.
</para>
</sect1>
<sect1 id="routing-route-adjustments">
<title>Adjusting Routes</title>
<para>&marble; let's you modify several aspects of the route for fine-tuning: Change route options, insert via points, move or remove existing points. The modification of route options has been discussed in the previous section already; we'll concentrate on point management now.
</para>
<para>Inserting via points is done by drag-and-drop in the map. Every time you move the mouse pointer above any part of the route (except above existing trip points), a green flag icon appears to indicate that it is possible to insert a via point. To start the insert operation, click with the &LMB;. Move the mouse pointer to the desired new position while keeping the &LMB; pressed. Blue lines from the neighboring via points to the new position will appear:
</para>
<screenshot>
<screeninfo>&marble; route adding via points</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="routing-3.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Inserting a via point</phrase></textobject>
</mediaobject>
</screenshot>
<para>The new via point will be inserted between the existing neighbor via points once you release the &LMB;. At the same time the existing route is painted dotted to indicate that it contains outdated information. In the background, a new route is prepared which will replace the outdated one automatically.
</para>
<para>It is also possible to add via points before the start or after the end of the route. To do that, follow the instructions above for inserting a new via point, but press &Ctrl; while moving the mouse. One blue line from the start or the end of the route appears. Its origin indicates where the new via point will be appended.
</para>
<para>Existing via points can be moved freely across the map. Move the mouse pointer above a via point and drag it to its new location. Once released, the route will be updated automatically.
</para>
<para>To exclude via points from the route, remove them. This can be done using either the <guilabel>Remove</guilabel> button next to the via point input field or by clicking with the &RMB; on the via point in the map. In the context menu, choose <guilabel>Remove this destination</guilabel>. To start an entirely new route, remove all via points.
</para>
</sect1>
<sect1 id="routing-route-export">
<title>Loading, Saving and Exporting Routes</title>
<para>You can save routes in <acronym>kml</acronym> (Keyhole Markup Language) format and load them again at a later point - on the same computer or a different device running &marble;, or share them with your friends or other applications which are able to read kml files (like <application>Google Earth</application>). To save a route to a <literal role="extension">.kml</literal> file, click on the <guilabel>Save</guilabel> icon on the bottom of the routing tab. The upcoming save dialog allows you to choose a file name to save the route to. Similarly loading a route is initiated with the <guilabel>Open</guilabel> icon on the bottom of the routing tab. Select the <literal role="extension">.kml</literal> route file to open in the upcoming open dialog and &marble; loads the route from it.
</para>
<para>Routes planned in &marble; can be used in other applications or navigation devices which support <acronym>gpx</acronym> (GPS eXchange Format) or equivalent formats. If your navigation device does not support <acronym>gpx</acronym> directly, you can use a conversion utility like <command>gpsbabel</command> to convert a <acronym>gpx</acronym> file exported by &marble; to a suitable format. The export of a route in &marble; is initiated from the routing context menu in the map. Click with the &RMB; on any point of the route in the map. In the context menu that appears, choose <guilabel>Export route...</guilabel>:
</para>
<screenshot>
<screeninfo>&marble; route export</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="routing-4.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; Exporting a Route</phrase></textobject>
</mediaobject>
</screenshot>
<para>Enter the desired filename in the upcoming save dialog. The filename extension should be <literal role="extension">gpx</literal> to store in <acronym>gpx</acronym> format or <literal role="extension">kml</literal> to store in <acronym>kml</acronym> (Keyhole Markup Language) format. Note that the internal format of &marble; is <acronym>kml</acronym>; in doubt save routes as <acronym>kml</acronym> and only use <acronym>gpx</acronym> to share routes with other applications that are not capable of reading <acronym>kml</acronym> files.
</para>
</sect1>
</chapter>
<chapter id="measure-distances">
<title>Measuring distances with &marble;</title>
<para>As mentioned already &marble; always displays a dynamic scale bar on the lower left to estimate distances on the map. Together with the windrose in the top right corner these overlays are provided for better orientation. But there's more: &marble; allows you to measure distances between two or more points on earth. To do so click the respective points in correct order on the globe using the &RMB;. On each click a popup menu will appear which allows you to add a measure point (<guilabel>Add Measure Point</guilabel>) or to remove all measure points altogether (<guilabel>Remove Measure Points</guilabel>):
</para>
<screenshot>
<screeninfo>&marble; measuring</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="measure-1.png" format="PNG" /></imageobject>
<textobject><phrase>&marble; measuring distances</phrase></textobject>
</mediaobject>
</screenshot>
<para>Once you have added at least two measure points, the total distance will be displayed in the top left corner of the map. &marble; will assume a spherical earth for all measurements which should be accurate enough for most cases.
</para>
<tip><para>Displaying of distances and bearings for the measured segments can be configured using <link linkend="measure-tool-config">Measure Tool configuration dialog</link>.</para></tip>
</chapter>
<chapter id="download-region">
<title>Download Map Regions</title>
<para>Pre-installed with a set of maps, &marble; is ready to use. When you zoom in at places, more detailed parts of the current map theme are downloaded in the background. This works excellent whenever an Internet connection is available. What to do, however, when traveling to a foreign city where no constant Internet connection is available to download maps? Plan ahead and download those map regions you are going to use.
</para>
<para>To understand what needs to be downloaded to display certain parts of the map offline, let's briefly look into the concept of tiles which &marble; uses internally. A tile is an image which corresponds to a certain part of the map. Tiles are arranged by &marble; next to each other to form the map image that is displayed to you. Depending on the selected projection mode, tiles are arranged to form a rectangle (Flat Map Projection, left) or a sphere (Globe Projection, right):
</para>
<screenshot>
<screeninfo>&marble; projections</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="download-region-1.png" format="PNG" /></imageobject>
<textobject><phrase>Tiles at Level 1 in Flat Map (left) and Globe Projection (right)</phrase></textobject>
</mediaobject>
</screenshot>
<para>Zooming in at this view, more details need to be displayed. The tiles shown in the two screenshots above are too coarse then; &marble; automatically recognizes this and changes to the next tile level where images provide more details. This keeps going: The more you zoom in, the higher the tile level. The following sketch illustrates the different number of tiles (colored) corresponding to the same map region at different tile levels:
</para>
<screenshot>
<screeninfo>&marble; tile levels</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="download-region-2.png" format="PNG" /></imageobject>
<textobject><phrase>Different Tile Levels in &marble;</phrase></textobject>
</mediaobject>
</screenshot>