Warning, /education/marble/doc/index.docbook is written in an unsupported language. File is not indexed.

0001 <?xml version="1.0" ?>
0002 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
0003  <!ENTITY % addindex "IGNORE">
0004  <!ENTITY % English "INCLUDE"><!-- change language only here -->
0005  ]>
0006 
0007 <book id="marble" lang="&language;">
0008 
0009   <bookinfo>
0010     <title>The &marble; Handbook</title>
0011 
0012     <authorgroup>
0013       <author>
0014         <firstname>Torsten</firstname>
0015         <surname>Rahn</surname>
0016         <affiliation>
0017           <address>&Torsten.Rahn.mail;</address>
0018         </affiliation>
0019       </author>
0020       <author>
0021         <firstname>Dennis</firstname>
0022         <surname>Nienhüser</surname>
0023         <affiliation>
0024           <address>&Dennis.Nienhueser.mail;</address>
0025         </affiliation>
0026       </author>
0027 
0028       <!-- TRANS:ROLES_OF_TRANSLATORS -->
0029     </authorgroup>
0030 
0031     <copyright>
0032       <year>2005</year>
0033       <year>2006</year>
0034       <year>2007</year>
0035       <holder>&Torsten.Rahn;</holder>
0036     </copyright>
0037     <copyright>
0038       <year>2010</year>
0039       <year>2013</year>
0040       <holder>&Dennis.Nienhueser;</holder>
0041     </copyright>
0042 
0043     <legalnotice>&FDLNotice;</legalnotice>
0044 
0045     <date>2021-10-17</date>
0046     <releaseinfo>2.2 (KDE Gear 21.08)</releaseinfo>
0047 
0048     <abstract>
0049       <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.
0050       </para>
0051     </abstract>
0052 
0053     <keywordset>
0054       <keyword>KDE</keyword>
0055       <keyword>education</keyword>
0056       <keyword>earth</keyword>
0057       <keyword>globe</keyword>
0058       <keyword>geography</keyword>
0059       <keyword>Marble</keyword>
0060     </keywordset>
0061 
0062   </bookinfo>
0063 
0064   <chapter id="introduction">
0065   <title>Introduction</title>
0066     <screenshot>
0067       <screeninfo>&marble; logo</screeninfo>
0068       <mediaobject>
0069         <imageobject><imagedata fileref="logo-1.png" format="PNG" /></imageobject>
0070         <textobject><phrase>&marble; logo</phrase></textobject>
0071       </mediaobject>
0072     </screenshot>
0073 
0074     <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 15 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>, <guilabel>Vector OSM</guilabel> and <guilabel>Moon</guilabel>.
0075     </para>
0076 
0077     <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.
0078     </para>
0079 
0080     <para>&marble; is free software and licensed under the &GNU; Lesser General Public License.
0081     </para>
0082 
0083   </chapter>
0084 
0085   <chapter id="quick-start">
0086   <title>&marble; quick start guide: Navigation</title>
0087 
0088   <para>Here is &marble; the first time you run it, either with <menuchoice><guimenu>Applications</guimenu> <guisubmenu>Education</guisubmenu> <guimenuitem>&kde; &marble; (Virtual Globe)</guimenuitem></menuchoice> from the global menu or with <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo> and entering <command>marble</command> into the input field.</para>
0089 
0090     <screenshot>
0091       <screeninfo>&marble; main window</screeninfo>
0092       <mediaobject>
0093         <imageobject><imagedata fileref="quick-1.png" format="PNG" /></imageobject>
0094         <textobject><phrase>&marble; main window</phrase></textobject>
0095       </mediaobject>
0096     </screenshot>
0097 
0098     <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 <guibutton>Up</guibutton> and <guibutton>Down</guibutton> arrow buttons will tilt the earth axis back and forth. The <guibutton>Left</guibutton> and <guibutton>Right</guibutton> arrow buttons will make the earth spin around its physical axis.
0099     </para>
0100 
0101     <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.
0102     </para>
0103 
0104     <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 <guibutton>Zoom In</guibutton> and <guibutton>Zoom Out</guibutton> buttons which are placed above and below the zoom slider (or using the <keycap>+</keycap> and <keycap>-</keycap> keys on your keyboard).
0105     </para>
0106 
0107     <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.
0108     </para>
0109 
0110     <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 press the <guibutton>Home</guibutton> button (or the &Home; button on your keyboard). To set the home location to the current position (center of the map) select the <menuchoice><guimenu>Bookmarks</guimenu> <guimenuitem>Set Home Location</guimenuitem></menuchoice> menu item.
0111     </para>
0112 
0113     <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.
0114     </para>
0115   </chapter>
0116 
0117   <chapter id="map-views">
0118   <title>Choosing different map views for &marble;</title>
0119 
0120     <para>&marble; comes with 15 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> <guilabel>Vector OSM</guilabel> and <guilabel>Moon</guilabel>. You can choose among these by pressing the <guilabel>Map View</guilabel> tab on the top of &marble;'s toolbox:
0121     </para>
0122 
0123     <screenshot>
0124       <screeninfo>&marble; map views</screeninfo>
0125       <mediaobject>
0126         <imageobject><imagedata fileref="mapview-1.png" format="PNG" /></imageobject>
0127         <textobject><phrase>&marble; Map Views</phrase></textobject>
0128       </mediaobject>
0129     </screenshot>
0130 
0131     <itemizedlist>
0132       <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>
0133 
0134       <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>
0135 
0136       <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>
0137 
0138       <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>
0139 
0140       <listitem><para><guilabel>Behaim Globe 1492</guilabel>: Produced by Martin Behaim from 1490–1492, it is the oldest surviving terrestrial globe.</para></listitem>
0141 
0142       <listitem><para><guilabel>Sentinel2 Satellite Map</guilabel>: Based on the Sentinel data, see more information <ulink url="https://community.kde.org/Marble/Sentinel2MapTheme">here</ulink>.</para></listitem>
0143 
0144       <listitem><para><guilabel>Historical Map 1689</guilabel>: A historical world map from the year 1689 created by G. van Schagen in Amsterdam.</para></listitem>
0145 
0146       <listitem><para><guilabel>Political Map</guilabel>: A simple map with the current frontiers of countries.</para></listitem>
0147 
0148       <listitem><para><guilabel>Plain Map</guilabel>: A plain map. It uses vector lines to mark coastlines and country borders &etc;</para></listitem>
0149 
0150       <listitem><para><guilabel>Precipitation (December)</guilabel>: A map which shows the average precipitation in December.</para></listitem>
0151 
0152       <listitem><para><guilabel>Precipitation (July)</guilabel>: A map which shows the average precipitation (rain, snow, hail, &etc;) in July.</para></listitem>
0153 
0154       <listitem><para><guilabel>Temperature (December)</guilabel>: A map which shows the average temperature in December.</para></listitem>
0155 
0156       <listitem><para><guilabel>Temperature (July)</guilabel>: A map which shows the average temperature in July.</para></listitem>
0157 
0158       <listitem><para><guilabel>Vector OSM</guilabel>: Vector map from the <ulink url="https://www.openstreetmap.org/">OpenStreetMap project</ulink>.</para></listitem>
0159 
0160       <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>
0161     </itemizedlist>
0162   </chapter>
0163 
0164   <chapter id="search-places">
0165   <title>Searching places using &marble;</title>
0166 
0167     <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:
0168     </para>
0169 
0170     <screenshot>
0171       <screeninfo>&marble; searching places</screeninfo>
0172       <mediaobject>
0173         <imageobject><imagedata fileref="search-1.png" format="PNG" /></imageobject>
0174         <textobject><phrase>&marble; Searching Places</phrase></textobject>
0175       </mediaobject>
0176     </screenshot>
0177 
0178     <para>As you hit &Enter;, &marble; runners will also query both online and offline searches to return you even more useful data.
0179     </para>
0180 
0181     <para>The following online search runners are available:</para>
0182 
0183     <itemizedlist>
0184       <listitem><para>Nominatim: An online search and reverse geocoding service, using data from <ulink url="https://www.openstreetmap.org"/></para></listitem>
0185 
0186       <listitem><para>HostIP: A reverse geocoding based on IP address, using data from <ulink url="https://www.hostip.info"/></para></listitem>
0187     </itemizedlist>
0188 
0189     <para>The following offline search runners are also available, depending on extra software and data you have installed:</para>
0190 
0191     <itemizedlist>
0192       <listitem><para>Local Database: All placemarks in all open documents will be searched for. This includes your Bookmarks of course.</para></listitem>
0193 
0194       <listitem><para>Monav: An offline search service using the data from Monav offline routing information, based on OSM data</para></listitem>
0195 
0196       <listitem><para>Gosmore: An offline reverse geocoding service using data from gosmore setup</para></listitem>
0197 
0198     </itemizedlist>
0199 
0200     <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:
0201     </para>
0202 
0203     <screenshot>
0204       <screeninfo>&marble; Data Sheet</screeninfo>
0205       <mediaobject>
0206         <imageobject><imagedata fileref="search-2.png" format="PNG" /></imageobject>
0207         <textobject><phrase>&marble; Data Sheet</phrase></textobject>
0208       </mediaobject>
0209     </screenshot>
0210 
0211     <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.
0212     </para>
0213 
0214     <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>
0215   </chapter>
0216 
0217   <chapter id="routing">
0218   <title>Find your way with &marble;</title>
0219 
0220     <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? Select the <guilabel>Routing</guilabel> tab on the top of &marble;'s toolbox to start planning your trip.
0221     </para>
0222 
0223     <sect1 id="routing-route-new">
0224     <title>Creating a new Route</title>
0225 
0226       <para>In the <guilabel>Routing</guilabel> tab you'll see two green icons <guibutton>A</guibutton> and <guibutton>B</guibutton>. Enter the start address in the input field next to the <guibutton>A</guibutton> button, the route start input field. Press &Enter; or press the <guibutton>Search</guibutton> 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:
0227       </para>
0228 
0229       <screenshot>
0230         <screeninfo>&marble; address search</screeninfo>
0231         <mediaobject>
0232           <imageobject><imagedata fileref="routing-1.png" format="PNG" /></imageobject>
0233           <textobject><phrase>&marble; Searching Addresses</phrase></textobject>
0234         </mediaobject>
0235       </screenshot>
0236 
0237       <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 <guiicon>A</guiicon> 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 <guiicon>A</guiicon> icon.
0238       </para>
0239 
0240       <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 <guibutton>B</guibutton> button, press &Enter; and select the desired item among the result list.
0241       </para>
0242 
0243       <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. Press 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:
0244       </para>
0245 
0246       <screenshot>
0247         <screeninfo>&marble; route result</screeninfo>
0248         <mediaobject>
0249           <imageobject><imagedata fileref="routing-2.png" format="PNG" /></imageobject>
0250           <textobject><phrase>&marble; Displaying a Route</phrase></textobject>
0251         </mediaobject>
0252       </screenshot>
0253 
0254       <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, press the <guibutton>A</guibutton> (or <guibutton>B</guibutton>) button next to the input field. Select <guilabel>From Map</guilabel> in the upcoming menu. Once pressed, 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 press the button again or press &Esc;.
0255       </para>
0256 
0257       <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.
0258       </para>
0259     </sect1>
0260 
0261     <sect1 id="routing-profiles">
0262     <title>Route Profiles</title>
0263 
0264       <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>.
0265       </para>
0266 
0267       <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:
0268       </para>
0269 
0270       <screenshot>
0271         <screeninfo>&marble; pedestrian routing</screeninfo>
0272         <mediaobject>
0273           <imageobject><imagedata fileref="routing-5.png" format="PNG" /></imageobject>
0274           <textobject><phrase>&marble; Pedestrian routing</phrase></textobject>
0275         </mediaobject>
0276       </screenshot>
0277 
0278       <para>The proposed route has become shorter because footways are now also included when calculating the best route.
0279       </para>
0280 
0281       <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.
0282       </para>
0283 
0284       <screenshot>
0285         <screeninfo>&marble; route profile configuration</screeninfo>
0286         <mediaobject>
0287           <imageobject><imagedata fileref="routing-6.png" format="PNG" /></imageobject>
0288           <textobject><phrase>&marble; Route Profile configuration</phrase></textobject>
0289         </mediaobject>
0290       </screenshot>
0291 
0292       <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
0293       </para>
0294 
0295       <itemizedlist>
0296         <listitem><para>CycleStreets: Bicycle routing for the United Kingdom using cyclestreets.net</para></listitem>
0297 
0298         <listitem><para>Gosmore: An offline router that also serves as the backend for the Yours online router</para></listitem>
0299 
0300         <listitem><para>MapQuest: An online router which provides advanced turn-by-turn instructions</para>
0301 
0302           <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>
0303 
0304         <listitem><para>Monav: An offline router that is very fast even when calculating very large routes</para></listitem>
0305 
0306         <listitem><para>OSRM: An online router that is very fast even when calculating very large routes</para></listitem>
0307 
0308         <listitem><para>OpenRouteService: An online router that also generates driving instructions, limited to Europe</para></listitem>
0309 
0310         <listitem><para>Routino: An offline router with a very flexible configuration</para></listitem>
0311 
0312         <listitem><para>Yours: An online router that operates world-wide, but lacks driving instructions</para></listitem>
0313       </itemizedlist>
0314 
0315       <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.
0316       </para>
0317 
0318       <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.
0319       </para>
0320     </sect1>
0321 
0322     <sect1 id="routing-route-adjustments">
0323     <title>Adjusting Routes</title>
0324 
0325       <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.
0326       </para>
0327 
0328       <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:
0329       </para>
0330 
0331       <screenshot>
0332         <screeninfo>&marble; route adding via points</screeninfo>
0333         <mediaobject>
0334           <imageobject><imagedata fileref="routing-3.png" format="PNG" /></imageobject>
0335           <textobject><phrase>&marble; Inserting a via point</phrase></textobject>
0336         </mediaobject>
0337       </screenshot>
0338 
0339       <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.
0340       </para>
0341 
0342       <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.
0343       </para>
0344 
0345       <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.
0346       </para>
0347 
0348       <para>To exclude via points from the route, remove them. This can be done using either the <guibutton>Remove</guibutton> 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 <guimenuitem>Remove this Destination</guimenuitem>. To start an entirely new route, remove all via points.
0349       </para>
0350     </sect1>
0351 
0352     <sect1 id="routing-route-export">
0353     <title>Loading, Saving and Exporting Routes</title>
0354 
0355       <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, press the <guibutton>Save</guibutton> button 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 <guibutton>Open</guibutton> button 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.
0356       </para>
0357 
0358       <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 <guimenuitem>Export Route...</guimenuitem>:
0359       </para>
0360 
0361       <screenshot>
0362         <screeninfo>&marble; route export</screeninfo>
0363         <mediaobject>
0364           <imageobject><imagedata fileref="routing-4.png" format="PNG" /></imageobject>
0365           <textobject><phrase>&marble; Exporting a Route</phrase></textobject>
0366         </mediaobject>
0367       </screenshot>
0368 
0369       <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.
0370       </para>
0371     </sect1>
0372   </chapter>
0373 
0374   <chapter id="measure-distances">
0375   <title>Measuring distances with &marble;</title>
0376 
0377     <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 (<guimenuitem>Add Measure Point</guimenuitem>) or to remove all measure points altogether (<guimenuitem>Remove Measure Points</guimenuitem>):
0378     </para>
0379 
0380     <screenshot>
0381       <screeninfo>&marble; measuring</screeninfo>
0382       <mediaobject>
0383         <imageobject><imagedata fileref="measure-1.png" format="PNG" /></imageobject>
0384         <textobject><phrase>&marble; measuring distances</phrase></textobject>
0385       </mediaobject>
0386     </screenshot>
0387 
0388     <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.
0389     </para>
0390 
0391     <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>
0392   </chapter>
0393 
0394   <chapter id="download-region">
0395   <title>Download Map Regions</title>
0396 
0397     <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.
0398     </para>
0399 
0400     <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):
0401     </para>
0402 
0403     <screenshot>
0404       <screeninfo>&marble; projections</screeninfo>
0405       <mediaobject>
0406         <imageobject><imagedata fileref="download-region-1.png" format="PNG" /></imageobject>
0407         <textobject><phrase>Tiles at Level 1 in Flat Map (left) and Globe Projection (right)</phrase></textobject>
0408       </mediaobject>
0409     </screenshot>
0410 
0411     <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:
0412     </para>
0413 
0414     <screenshot>
0415       <screeninfo>&marble; tile levels</screeninfo>
0416       <mediaobject>
0417         <imageobject><imagedata fileref="download-region-2.png" format="PNG" /></imageobject>
0418         <textobject><phrase>Different Tile Levels in &marble;</phrase></textobject>
0419       </mediaobject>
0420     </screenshot>
0421 
0422     <para>When downloading a map region for offline usage, you need to download all tiles in the desired region for all tile levels you plan to use. Because of the connection between tile levels and zoom levels, you can think of it as downloading all tiles in the zoom levels you plan to use.
0423     </para>
0424 
0425     <para>To accomplish this for a certain region, make that region visible in the screen by zooming and moving the Globe. Now select the <menuchoice><guilabel>File</guilabel> <guilabel>Download Region...</guilabel></menuchoice> menu item to open the <guilabel>Download Region</guilabel> dialog. Keep the <guilabel>Visible region</guilabel> option selected to download those tiles that correspond to the map region visible in the screen. Next, select the <guilabel>Tile level range:</guilabel> (zoom range) you wish to download. The first field corresponds to the smallest, the second field corresponds to the largest tile level that will be downloaded. Tile levels in between will be downloaded as well. &marble; shows how many tiles (images) need to be downloaded and updates this number whenever you change the region or tile level range.
0426     </para>
0427 
0428     <screenshot>
0429       <screeninfo>&marble; Download Region dialog</screeninfo>
0430       <mediaobject>
0431         <imageobject><imagedata fileref="download-region-3.png" format="PNG" /></imageobject>
0432         <textobject><phrase>&marble;'s Download Region dialog</phrase></textobject>
0433       </mediaobject>
0434     </screenshot>
0435 
0436     <para>The tile level corresponding to the current zoom level is shown in the status bar on the bottom. Please note that you may have to configure &marble; to show that information: Click with the &RMB; on the status bar and select <guilabel>Show Tile Zoom Level</guilabel>.
0437     </para>
0438 
0439     <para>Select <guibutton>OK</guibutton> to trigger the map region download. The progress bar of &marble; will show the download progress (if activated).
0440     </para>
0441 
0442     <para>In case you do know the coordinates of the map region to download, you can enter them by clicking on the <guilabel>Specify region</guilabel> option. The map region visible in the screen will be ignored in that case.
0443     </para>
0444 
0445     <para>You can keep using &marble; while the <guilabel>Download Region</guilabel> dialog is open. This is useful to queue several downloads for different regions or different tile ranges. Just select <guibutton>Apply</guibutton> instead of <guibutton>OK</guibutton> to trigger the map region download.
0446     </para>
0447   </chapter>
0448 
0449   <chapter id="recording-movie">
0450   <title>Recording a movie with &marble;</title>
0451 
0452     <sect1 id="recording-movie-recording">
0453     <title>Recording a movie with &marble;</title>
0454 
0455       <para>To record a movie with &marble;, use this function for recording.
0456       </para>
0457 
0458       <para>Begin recording from the <menuchoice><shortcut> <keycombo action="simul">&Ctrl;&Shift;<keycap>R</keycap></keycombo> </shortcut> <guimenu>Edit</guimenu> <guimenuitem>Record Movie</guimenuitem></menuchoice> menu item to open the <guilabel>Record Movie</guilabel> dialog. You will see a dialog like this:
0459       </para>
0460 
0461       <screenshot>
0462         <screeninfo>&marble; Record Movie dialog</screeninfo>
0463         <mediaobject>
0464           <imageobject><imagedata fileref="movie-1.png" format="PNG" /></imageobject>
0465           <textobject><phrase>&marble;'s Record Movie dialog</phrase></textobject>
0466         </mediaobject>
0467       </screenshot>
0468 
0469       <para>Press the <guibutton>Open...</guibutton> button to choose the name and destination folder of the movie. Also you can change the frames per second (FPS) of the movie between 1 and 60.
0470       </para>
0471 
0472       <para>When all is set, you can start recording. To start, press the <guibutton>Start</guibutton> button. Once this is done you can zoom and pan around and &marble; will capture a video of your journey across the globe.
0473       </para>
0474 
0475       <para>To stop recording of the movie and save it, select the <menuchoice><guimenu>Edit</guimenu> <guimenuitem>Stop Recording</guimenuitem></menuchoice> menu item.
0476       </para>
0477 
0478       <sect2 id="recording-movie-troubleshooting">
0479       <title>Troubleshooting</title>
0480 
0481         <para>There may appear an error message because avconv or ffmpeg are not installed. Download from <ulink url="https://ffmpeg.org/download.html">ffmpeg's downloads page</ulink> and <ulink url="https://libav.org/download.html">avconv's downloads page</ulink> or use packages from your distribution.
0482         </para>
0483       </sect2>
0484     </sect1>
0485   </chapter>
0486 
0487   <chapter id="commands">
0488   <title>Command Reference</title>
0489 
0490     <sect1 id="marble-mainwindow">
0491     <title>Menus and shortcut keys</title>
0492 
0493       <sect2>
0494       <title>The File Menu</title>
0495 
0496         <variablelist>
0497           <varlistentry>
0498             <term><menuchoice>
0499             <shortcut><keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> </shortcut>
0500             <guimenu>File</guimenu>
0501             <guimenuitem>Open...</guimenuitem></menuchoice></term>
0502             <listitem><para><action>Opens</action> a map file.</para></listitem>
0503           </varlistentry>
0504 
0505           <varlistentry>
0506             <term><menuchoice>
0507             <guimenu>File</guimenu>
0508             <guimenuitem>Open Recent</guimenuitem>
0509             </menuchoice></term>
0510             <listitem><para>This is a shortcut to open recently opened maps. Clicking on this item opens a list to the side of the menu with several of the most recently opened files. Clicking on a specific file will open it in &marble; - if the file still resides at the same location.</para></listitem>
0511           </varlistentry>
0512 
0513           <varlistentry>
0514             <term><menuchoice>
0515             <shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> </shortcut>
0516             <guimenu>File</guimenu>
0517             <guimenuitem>Download Maps...</guimenuitem></menuchoice></term>
0518             <listitem><para><action>Displays</action> the <guilabel>Get Hot New Stuff!</guilabel> dialog to download additional maps for &marble;, among others maps for Mars and Venus.</para></listitem>
0519           </varlistentry>
0520 
0521          <varlistentry>
0522             <term><menuchoice>
0523             <guimenu>File</guimenu>
0524             <guimenuitem>Create a New Map...</guimenuitem></menuchoice></term>
0525             <listitem><para><action>Displays</action> the <guilabel>&marble; Map Theme Creation Wizard</guilabel> dialog to create a new map using Web Map Service data, your own image file or Open Street Map indexed tiles.</para></listitem>
0526           </varlistentry>
0527 
0528           <varlistentry>
0529             <term><menuchoice>
0530             <guimenu>File</guimenu>
0531             <guimenuitem>Download Region...</guimenuitem></menuchoice></term>
0532             <listitem><para><action>Displays</action> the <guilabel>Download Region</guilabel> dialog to download map data in different zoom levels for offline usage. See <link linkend="download-region">Download Map Regions</link> for details.</para></listitem>
0533           </varlistentry>
0534 
0535           <varlistentry>
0536             <term><menuchoice>
0537             <shortcut><keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> </shortcut>
0538             <guimenu>File</guimenu>
0539             <guimenuitem>Export Map...</guimenuitem></menuchoice></term>
0540             <listitem><para><action>Exports</action> a screenshot of &marble;'s map to an image file.</para></listitem>
0541           </varlistentry>
0542 
0543           <varlistentry>
0544             <term><menuchoice>
0545             <shortcut><keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo> </shortcut>
0546             <guimenu>File</guimenu>
0547             <guimenuitem>Print...</guimenuitem></menuchoice></term>
0548             <listitem><para><action>Prints</action> a screenshot of &marble;'s map.</para></listitem>
0549           </varlistentry>
0550 
0551           <varlistentry>
0552             <term><menuchoice>
0553             <guimenu>File</guimenu>
0554             <guimenuitem>Print Preview</guimenuitem></menuchoice></term>
0555             <listitem><para>Opens a window that shows a preview of the printed map.</para></listitem>
0556           </varlistentry>
0557 
0558           <varlistentry>
0559             <term><menuchoice>
0560             <guimenu>File</guimenu>
0561             <guimenuitem>Work Offline</guimenuitem></menuchoice></term>
0562             <listitem><para>If this option is selected &marble; will no longer download map data from the Internet. The search feature gets restricted to the local database. New routes cannot be retrieved.</para></listitem>
0563           </varlistentry>
0564 
0565           <varlistentry>
0566             <term><menuchoice>
0567             <shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> </shortcut>
0568             <guimenu>File</guimenu>
0569             <guimenuitem>Quit</guimenuitem></menuchoice></term>
0570             <listitem><para><action>Quits</action> &marble;.</para></listitem>
0571           </varlistentry>
0572         </variablelist>
0573       </sect2>
0574 
0575       <sect2>
0576       <title>The Edit Menu</title>
0577 
0578         <variablelist>
0579           <varlistentry>
0580             <term><menuchoice>
0581             <shortcut><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo> </shortcut>
0582             <guimenu>Edit</guimenu>
0583             <guimenuitem>Copy Map</guimenuitem></menuchoice></term>
0584             <listitem><para><action>Copies</action> a screenshot of &marble;'s map to the global clipboard.</para></listitem>
0585           </varlistentry>
0586 
0587           <varlistentry>
0588             <term><menuchoice>
0589             <guimenu>Edit</guimenu>
0590             <guimenuitem>Copy Coordinates</guimenuitem></menuchoice></term>
0591             <listitem><para><action>Copies</action> the current coordinates to the global clipboard.</para></listitem>
0592           </varlistentry>
0593 
0594           <varlistentry>
0595             <term><menuchoice>
0596             <shortcut><keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo> </shortcut>
0597             <guimenu>Edit</guimenu>
0598             <guimenuitem>Edit Map...</guimenuitem></menuchoice></term>
0599             <listitem><para><action>Allows</action> you to open the current map in the external map editor. The current version supports <application>Potlatch</application> (in a web browser), <application>Merkaartor</application> and <application>JOSM</application> map editors.</para></listitem>
0600           </varlistentry>
0601 
0602           <varlistentry>
0603             <term><menuchoice>
0604             <shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>R</keycap></keycombo> </shortcut>
0605             <guimenu>Edit</guimenu>
0606             <guimenuitem>Record Movie</guimenuitem></menuchoice></term>
0607             <listitem><para><action>Records</action> a movie with &marble;.</para></listitem>
0608           </varlistentry>
0609 
0610           <varlistentry>
0611             <term><menuchoice>
0612             <guimenu>Edit</guimenu>
0613             <guimenuitem>Stop Recording</guimenuitem></menuchoice></term>
0614             <listitem><para><action>Stops</action> the current recording of movie.</para></listitem>
0615           </varlistentry>
0616         </variablelist>
0617       </sect2>
0618 
0619       <sect2>
0620       <title>The View Menu</title>
0621 
0622         <variablelist>
0623           <varlistentry>
0624             <term><menuchoice>
0625             <guimenu>View</guimenu>
0626             <guimenuitem>Current Location</guimenuitem></menuchoice></term>
0627             <listitem><para><action>Toggle</action> the display of the location page in the left panel. If a GPS device is connected with your computer, &marble; displays longitude and latitude of your current location.</para></listitem>
0628           </varlistentry>
0629 
0630           <varlistentry>
0631             <term><menuchoice>
0632             <guimenu>View</guimenu>
0633             <guimenuitem>Crosshairs</guimenuitem></menuchoice></term>
0634             <listitem><para><action>Toggle</action> the display of a simple crosshair in the center of the map.</para></listitem>
0635           </varlistentry>
0636 
0637           <varlistentry>
0638             <term><menuchoice>
0639             <shortcut><keycap>F5</keycap></shortcut>
0640             <guimenu>View</guimenu>
0641             <guimenuitem>Refresh</guimenuitem></menuchoice></term>
0642             <listitem><para>The currently visible part of the map is downloaded again and refreshed on the screen.</para></listitem>
0643           </varlistentry>
0644 
0645           <varlistentry>
0646             <term><menuchoice>
0647             <guimenu>View</guimenu>
0648             <guisubmenu>Info Boxes</guisubmenu></menuchoice></term>
0649             <listitem><para>In this submenu you can to lock the position of the infoboxes and show or hide the plugins you have enabled in the <link linkend="configplugins">Plugins</link> page of &marble;s configuration dialog.</para></listitem>
0650           </varlistentry>
0651 
0652           <varlistentry>
0653             <term><menuchoice>
0654             <guimenu>View</guimenu>
0655             <guimenuitem>Online Services</guimenuitem></menuchoice></term>
0656             <listitem><para>The <guimenuitem>Wikipedia</guimenuitem> plugin displays georeferenced Wikipedia articles as an icon on the map. A click onto the icon launches a browser window that displays the referenced site. The data is provided through a webservice via GeoNames.org. Likewise a <guimenuitem>Photos</guimenuitem> plugin currently provides photos via the FlickR photo sharing site.</para></listitem>
0657           </varlistentry>
0658 
0659           <varlistentry>
0660             <term><menuchoice>
0661             <guimenu>View</guimenu>
0662             <guimenuitem>Clouds</guimenuitem></menuchoice></term>
0663             <listitem><para><action>Show</action> real-time cloud cover. A real-time cloud map that gets updated every 3 hours. It uses GOES, METEOSAT, and GMS satellite imagery downloaded from the Geostationary Satellite Imagery page at Dundee University.  Credits: Hari Nair, Xplanet Project.</para></listitem>
0664           </varlistentry>
0665 
0666           <varlistentry>
0667             <term><menuchoice>
0668             <guimenu>View</guimenu>
0669             <guimenuitem>Atmosphere</guimenuitem></menuchoice></term>
0670             <listitem><para><action>Show</action> the diffuse reflection of the atmosphere around the Earth.</para></listitem>
0671           </varlistentry>
0672 
0673           <varlistentry>
0674             <term><menuchoice>
0675             <guimenu>View</guimenu>
0676             <guimenuitem>Stars</guimenuitem></menuchoice></term>
0677             <listitem><para><action>Show</action> the star map as seen from the Solar System.</para></listitem>
0678           </varlistentry>
0679 
0680           <varlistentry>
0681             <term><menuchoice>
0682             <guimenu>View</guimenu>
0683             <guimenuitem>Sun Control...</guimenuitem></menuchoice></term>
0684             <listitem><para><action>Displays</action> the <guilabel>Sun Control</guilabel> where you can set the <guilabel>Sun Shading</guilabel> and center the map on subsolar point position.</para></listitem>
0685           </varlistentry>
0686 
0687           <varlistentry>
0688             <term><menuchoice>
0689             <guimenu>View</guimenu>
0690             <guimenuitem>Time Control...</guimenuitem></menuchoice></term>
0691             <listitem><para><action>Displays</action> the <guilabel>Time Control</guilabel> dialog where you can set date and time and the simulation time speed.</para></listitem>
0692           </varlistentry>
0693 
0694           <varlistentry>
0695             <term><menuchoice>
0696             <guimenu>View</guimenu>
0697             <guisubmenu>Eclipses in <replaceable>year</replaceable></guisubmenu></menuchoice></term>
0698             <listitem><para><action>Displays</action> the list of the eclipses for the year chosen using <menuchoice><guimenu>View</guimenu> <guimenuitem>Browse Eclipses...</guimenuitem></menuchoice> menu item.</para>
0699 
0700             <para>This menu item will be shown only when <link linkend="eclipsesplugin">Eclipses</link> plugin is enabled.</para></listitem>
0701           </varlistentry>
0702 
0703           <varlistentry>
0704             <term><menuchoice>
0705             <guimenu>View</guimenu>
0706             <guimenuitem>Browse Eclipses...</guimenuitem></menuchoice></term>
0707             <listitem><para><action>Displays</action> the <guilabel>Eclipse Browser</guilabel> dialog where you can set the year to show eclipses for, open plugin settings dialog, view data on eclipse start, end, type and magnitude. Choose some eclipse item from the list and press the <guibutton>Go To Selected Eclipse</guibutton> to view the location of the eclipse on the globe.</para>
0708 
0709             <para>This menu item will be shown only when <link linkend="eclipsesplugin">Eclipses</link> plugin is enabled.</para></listitem>
0710           </varlistentry>
0711         </variablelist>
0712       </sect2>
0713 
0714       <sect2>
0715       <title>The Bookmarks Menu</title>
0716         <variablelist>
0717           <varlistentry>
0718             <term><menuchoice>
0719             <shortcut><keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo> </shortcut>
0720             <guimenu>Bookmarks</guimenu>
0721             <guimenuitem>Add Bookmark...</guimenuitem></menuchoice></term>
0722             <listitem><para><action>Open the <guilabel>Edit Bookmark</guilabel> dialog</action> to manage a bookmark.</para></listitem>
0723           </varlistentry>
0724 
0725           <varlistentry>
0726             <term><menuchoice>
0727             <guimenu>Bookmarks</guimenu>
0728             <guimenuitem>Show Bookmarks</guimenuitem></menuchoice></term>
0729             <listitem><para>A check box for <action>enable the bookmarks visualization on the map.</action></para></listitem>
0730           </varlistentry>
0731 
0732           <varlistentry>
0733             <term><menuchoice>
0734             <guimenu>Bookmarks</guimenu>
0735             <guimenuitem>Set Home Location</guimenuitem></menuchoice></term>
0736             <listitem><para><action>Set the current position as your house.</action></para></listitem>
0737           </varlistentry>
0738 
0739           <varlistentry>
0740             <term><menuchoice>
0741             <guimenu>Bookmarks</guimenu>
0742             <guimenuitem>Manage Bookmarks...</guimenuitem></menuchoice></term>
0743             <listitem><para><action>Open the <guilabel>Manage Bookmarks</guilabel> dialog</action> to manage all bookmarks.</para></listitem>
0744           </varlistentry>
0745 
0746           <varlistentry>
0747             <term><menuchoice>
0748             <guimenu>Bookmarks</guimenu>
0749             <guisubmenu>Default</guisubmenu></menuchoice></term>
0750             <listitem><para><action>This submenu shows your default locations.</action></para></listitem>
0751           </varlistentry>
0752         </variablelist>
0753       </sect2>
0754 
0755       <sect2>
0756       <title>The Settings Menu</title>
0757 
0758         <variablelist>
0759           <varlistentry>
0760             <term><menuchoice>
0761             <guimenu>Settings</guimenu>
0762             <guimenuitem>Show Toolbar</guimenuitem></menuchoice></term>
0763             <listitem><para><action>Toggle</action> the display of the toolbar.</para></listitem>
0764           </varlistentry>
0765 
0766           <varlistentry>
0767             <term><menuchoice>
0768             <guimenu>Settings</guimenu>
0769             <guimenuitem>Show Statusbar</guimenuitem></menuchoice></term>
0770             <listitem><para><action>Toggle</action> the display of the status bar.</para></listitem>
0771           </varlistentry>
0772 
0773           <varlistentry>
0774             <term><menuchoice>
0775             <guimenu>Settings</guimenu>
0776             <guisubmenu>Panels</guisubmenu></menuchoice></term>
0777             <listitem><para><action>Toggle</action> the display of the &marble; panels.</para>
0778 
0779             <tip><para>You can make &marble; hide all panels or show them by selecting the <menuchoice><guimenu>Settings</guimenu> <guisubmenu>Panels</guisubmenu> <guimenuitem>Hide All Panels/Show All Panels</guimenuitem></menuchoice> menu item or pressing <keycap>F9</keycap> key on your keyboard.</para></tip></listitem>
0780           </varlistentry>
0781 
0782           <varlistentry>
0783             <term><menuchoice>
0784             <guimenu>Settings</guimenu>
0785             <guisubmenu>View Size</guisubmenu></menuchoice></term>
0786             <listitem><para><action>Switches between various sizes of &marble; map area.</action> You can choose one of the sizes that are suitable for capturing frames for screencast or keep &marble; map area resizable (<guimenuitem>Default (resizable)</guimenuitem> item).</para></listitem>
0787           </varlistentry>
0788 
0789           <varlistentry>
0790             <term><menuchoice>
0791             <shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>F</keycap></keycombo> </shortcut>
0792             <guimenu>Settings</guimenu>
0793             <guimenuitem>Full Screen Mode</guimenuitem></menuchoice></term>
0794             <listitem><para><action>Switches between normal view and full screen view.</action> In full screen view, the titlebar is hidden and the actual application window is resized to the entire screen.</para></listitem>
0795           </varlistentry>
0796 
0797           <varlistentry>
0798             <term><menuchoice>
0799             <guimenu>Settings</guimenu>
0800             <guimenuitem>Configure &marble; Virtual Globe...</guimenuitem></menuchoice></term>
0801             <listitem><para><action>Display</action> the <link linkend="configure">&marble; configuration</link> dialog.</para></listitem>
0802           </varlistentry>
0803 
0804         </variablelist>
0805 
0806       </sect2>
0807 
0808       <sect2>
0809       <title>The Help Menu</title>
0810 
0811         <para>&marble; has the common &kde; <guimenu>Help</guimenu> menu item, for more information read the section about the <ulink url="help:/fundamentals/menus.html#menus-help">Help Menu</ulink> of the &kde; Fundamentals.
0812         </para>
0813       </sect2>
0814     </sect1>
0815   </chapter>
0816 
0817   <chapter id="configure">
0818   <title>Configuring &marble;</title>
0819 
0820     <sect1 id="configview">
0821     <title>View Configuration</title>
0822 
0823       <screenshot>
0824         <screeninfo>The View configuration dialog</screeninfo>
0825         <mediaobject>
0826           <imageobject><imagedata fileref="configure-view.png" format="PNG" /></imageobject>
0827           <textobject><phrase>The View configuration dialog</phrase></textobject>
0828         </mediaobject>
0829       </screenshot>
0830 
0831       <variablelist>
0832         <varlistentry>
0833           <term><guilabel>Distance:</guilabel></term>
0834           <listitem><para>The unit that gets used to measure altitude, lengths and distances (&eg; km, mi, ft).</para></listitem>
0835         </varlistentry>
0836 
0837         <varlistentry>
0838           <term><guilabel>Angle:</guilabel></term>
0839           <listitem><para>Specifies the notation of angles in coordinates: By default the Degree-Minute-Second notation (&eg; 54°30'00" ) gets used. As an alternative you can choose decimal degrees (&eg; 54.5°).</para></listitem>
0840         </varlistentry>
0841 
0842         <varlistentry>
0843           <term><guilabel>Still image:</guilabel></term>
0844           <listitem><para>Specifies the map quality that gets displayed while there is no user input. Usually this allows for high map quality as speed is no concern.</para></listitem>
0845         </varlistentry>
0846 
0847         <varlistentry>
0848           <term><guilabel>During animations:</guilabel></term>
0849           <listitem><para>Specifies the map quality that gets displayed during map animations (&eg; while dragging the globe). Especially on slow machines it is advisable to set this option to <guilabel>Low Quality</guilabel> as this will give better speed.</para></listitem>
0850         </varlistentry>
0851 
0852 <!--         <varlistentry>
0853           <term><guilabel>Place names:</guilabel></term>
0854           <listitem><para>Places often have different names in different languages. The label on the map can show the name in the user's language. Alternatively it can display the name in the official language and glyphs of that place.</para></listitem>
0855         </varlistentry>-->
0856 
0857         <varlistentry>
0858           <term><guilabel>Default map font:</guilabel></term>
0859           <listitem><para>The default font that gets used on the map.</para></listitem>
0860         </varlistentry>
0861       </variablelist>
0862     </sect1>
0863 
0864     <sect1 id="confignavigation">
0865     <title>Navigation Configuration</title>
0866 
0867       <screenshot>
0868         <screeninfo>The Navigation configuration dialog</screeninfo>
0869         <mediaobject>
0870           <imageobject><imagedata fileref="configure-navigation.png" format="PNG" /></imageobject>
0871           <textobject><phrase>The Navigation configuration dialog</phrase></textobject>
0872         </mediaobject>
0873       </screenshot>
0874 
0875       <variablelist>
0876 <!--        <varlistentry>
0877           <term><guilabel>Drag location:</guilabel></term>
0878           <listitem><para>While dragging the mouse there are two standard behaviors when dealing with a virtual globe: The location below mouse pointer will follow the cursor exactly: As a result &eg; the north pole will not stay at the top which can lead to confusion. By default &marble; makes sure that north is always up which results in a dragging behavior where the location below the mouse pointer slightly "detaches" from the cursor.</para></listitem>
0879         </varlistentry>-->
0880 
0881         <varlistentry>
0882           <term><guilabel>Inertial globe rotation</guilabel></term>
0883           <listitem><para>By default &marble; will use kinetic spinning while dragging the map. You can turn this behavior off using this check box.</para></listitem>
0884         </varlistentry>
0885 
0886         <varlistentry>
0887           <term><guilabel>Animate voyage to the target</guilabel></term>
0888           <listitem><para>When searching for a location &marble; can either move instantly to the new location or it can show a travel animation from the previous place to the new place.</para></listitem>
0889         </varlistentry>
0890 
0891         <varlistentry>
0892           <term><guilabel>Mouse view rotation</guilabel></term>
0893           <listitem><para>The map and mouse movement is aligned while panning.</para></listitem>
0894         </varlistentry>
0895 
0896         <varlistentry>
0897           <term><guilabel>On Startup:</guilabel></term>
0898           <listitem><para>By default &marble; will display the home location immediately after the application has started. As an alternative it can also show the last position that was active when the user left the application.</para></listitem>
0899         </varlistentry>
0900 
0901         <varlistentry>
0902           <term><guilabel>External editor:</guilabel></term>
0903           <listitem><para>Here, you can define the default editor for the maps or choose <guilabel>Always ask</guilabel> if &marble; should ask you to choose before starting the external editor.</para></listitem>
0904         </varlistentry>
0905       </variablelist>
0906     </sect1>
0907 
0908     <sect1 id="configcacheproxy">
0909     <title>Cache &amp; Proxy Configuration</title>
0910 
0911       <screenshot>
0912         <screeninfo>The Cache &amp; Proxy configuration dialog</screeninfo>
0913         <mediaobject>
0914           <imageobject><imagedata fileref="configure-cacheproxy.png" format="PNG" /></imageobject>
0915           <textobject><phrase>The Cache &amp; Proxy configuration dialog</phrase></textobject>
0916         </mediaobject>
0917       </screenshot>
0918 
0919       <variablelist>
0920         <varlistentry>
0921           <term><guilabel>Cache</guilabel></term>
0922           <listitem><para>There are two caches being used for &marble;: The <guilabel>Physical memory:</guilabel> which is needed to keep map data in the computer's memory. Increasing the value will make the application more responsive. The <guilabel>Hard disc:</guilabel> memory cache is used by download contents from the Internet (&eg; Wikipedia data or map data). Decrease this value if you want to save space on the hard disc and if high usage of the Internet is not an issue.</para></listitem>
0923         </varlistentry>
0924 
0925         <varlistentry>
0926           <term><guilabel>Proxy</guilabel></term>
0927           <listitem><para>Proxy settings for your local intranet. Please leave empty if there is no proxy.</para></listitem>
0928         </varlistentry>
0929       </variablelist>
0930     </sect1>
0931 
0932     <sect1 id="configdatetime">
0933     <title>Date &amp; Time Configuration</title>
0934 
0935       <screenshot>
0936         <screeninfo>The Date &amp; Time configuration dialog</screeninfo>
0937         <mediaobject>
0938           <imageobject><imagedata fileref="configure-dateandtime.png" format="PNG" /></imageobject>
0939           <textobject><phrase>The Date &amp; Time configuration dialog</phrase></textobject>
0940         </mediaobject>
0941       </screenshot>
0942 
0943       <variablelist>
0944         <varlistentry>
0945           <term><guilabel>Time Zone</guilabel></term>
0946           <listitem><para>Here, you can choose a time zone for &marble;: <ulink url="https://en.wikipedia.org/wiki/Coordinated_Universal_Time">UTC</ulink>, system time zone or choose custom time zone. The chosen option changes the map view only if the map can show the light conditions on the surface.</para></listitem>
0947         </varlistentry>
0948 
0949         <varlistentry>
0950           <term><guilabel>When &marble; starts</guilabel></term>
0951           <listitem><para>Here, you can choose the date and time which will be used on &marble; start: system time or the last session time.</para></listitem>
0952         </varlistentry>
0953       </variablelist>
0954     </sect1>
0955 
0956     <sect1 id="configsynchronization">
0957     <title>Synchronization Configuration</title>
0958 
0959       <para>&marble; can upload route and bookmark data to <ulink url="https://en.wikipedia.org/wiki/OwnCloud">ownCloud</ulink> server and synchronize them between &marble; instances installed on different devices.
0960       </para>
0961 
0962       <screenshot>
0963         <screeninfo>The Synchronization configuration dialog</screeninfo>
0964         <mediaobject>
0965           <imageobject><imagedata fileref="configure-synchronization.png" format="PNG" /></imageobject>
0966           <textobject><phrase>The Synchronization configuration dialog</phrase></textobject>
0967         </mediaobject>
0968       </screenshot>
0969 
0970       <variablelist>
0971         <varlistentry>
0972           <term><guilabel>Enable synchronization</guilabel></term>
0973           <listitem><para>The synchronization can be enabled or disabled using this item. When the synchronization is enabled you can choose whether to synchronize route and bookmark data using the corresponding check boxes or press the <guibutton>Sync now</guibutton> button to initiate synchronization immediately.</para></listitem>
0974         </varlistentry>
0975 
0976         <varlistentry>
0977           <term><guilabel>Credentials</guilabel></term>
0978           <listitem><para>Here, you can enter your ownClowd credentials. More information on ownClowd configuration can be found on the <ulink url="https://owncloud.com/">ownClowd official website</ulink>.</para></listitem>
0979         </varlistentry>
0980       </variablelist>
0981     </sect1>
0982 
0983     <sect1 id="configrouting">
0984     <title>Routing Configuration</title>
0985 
0986       <screenshot>
0987         <screeninfo>The Routing configuration dialog</screeninfo>
0988         <mediaobject>
0989           <imageobject><imagedata fileref="configure-routing.png" format="PNG" /></imageobject>
0990           <textobject><phrase>The Routing configuration dialog</phrase></textobject>
0991         </mediaobject>
0992       </screenshot>
0993 
0994       <variablelist>
0995         <varlistentry>
0996           <term><guibutton>Add...</guibutton></term>
0997           <listitem><para>Opens a window where you can add a new routing profile.</para></listitem>
0998         </varlistentry>
0999 
1000         <varlistentry>
1001           <term><guibutton>Configure...</guibutton></term>
1002           <listitem><para>Opens a window where the currently selected routing profile can be configured.</para></listitem>
1003         </varlistentry>
1004 
1005         <varlistentry>
1006           <term><guibutton>Remove</guibutton></term>
1007           <listitem><para>Deletes the selected routing profile.</para></listitem>
1008         </varlistentry>
1009 
1010         <varlistentry>
1011           <term><guibutton>Move Up</guibutton></term>
1012           <listitem><para>The selected routing profile is moved up one step. It will appear before the one that was previously on top of it.</para></listitem>
1013         </varlistentry>
1014 
1015         <varlistentry>
1016           <term><guibutton>Move Down</guibutton></term>
1017           <listitem><para>The selected routing profile is moved down one step. It will appear after the one that was previously below of it.</para></listitem>
1018         </varlistentry>
1019       </variablelist>
1020     </sect1>
1021 
1022     <sect1 id="configplugins">
1023     <title>Plugins Configuration</title>
1024 
1025       <para>The <guilabel>Plugin Configuration</guilabel> widget is the place to activate (or deactivate) Info Boxes, Online Services and other plugins that affect the look of &marble;. Active plugins appear in the <guilabel>View</guilabel> menu where you can toggle their visibility.
1026       </para>
1027 
1028       <screenshot>
1029         <screeninfo>The Plugins configuration dialog</screeninfo>
1030         <mediaobject>
1031           <imageobject><imagedata fileref="configure-plugins.png" format="PNG" /></imageobject>
1032           <textobject><phrase>The Plugins configuration dialog</phrase></textobject>
1033         </mediaobject>
1034       </screenshot>
1035 
1036       <para>Each plugin can be activated and deactivated using the check box on the left. Some plugins provide further configuration options which are accessible by clicking on the tool icon on the right.
1037       </para>
1038 
1039       <variablelist>
1040         <varlistentry>
1041           <term><guilabel>Amateur Radio Aprs Plugin</guilabel></term>
1042           <listitem><para>Retrieves data from the Automatic Packet Reporting System via the Internet, a file or a serial device. The position and status of data senders is displayed in the map and updated in real-time.</para></listitem>
1043         </varlistentry>
1044 
1045         <varlistentry>
1046           <term><guilabel>Annotation</guilabel></term>
1047           <listitem><para>Allows you to add annotations on the maps.</para></listitem>
1048         </varlistentry>
1049 
1050         <varlistentry>
1051           <term><guilabel>Atmosphere</guilabel></term>
1052           <listitem><para>Displays atmosphere effects.</para></listitem>
1053         </varlistentry>
1054 
1055         <varlistentry>
1056           <term><guilabel>Compass</guilabel></term>
1057           <listitem><para>Shows a compass in the map.</para></listitem>
1058         </varlistentry>
1059 
1060         <varlistentry>
1061           <term><guilabel>Coordinate Grid</guilabel></term>
1062           <listitem><para>Displays a coordinate grid (you can choose the colors of the grid lines).</para></listitem>
1063         </varlistentry>
1064 
1065         <varlistentry>
1066           <term><guilabel>Crosshairs</guilabel></term>
1067           <listitem><para>Enable this to display a small crosshair in the center of the map.</para></listitem>
1068         </varlistentry>
1069 
1070         <varlistentry>
1071           <term><guilabel>Download Progress Indicator</guilabel></term>
1072           <listitem><para>A pie chart on top of the map that shows the progress of ongoing downloads.</para></listitem>
1073         </varlistentry>
1074 
1075         <varlistentry>
1076           <term><guilabel>Earthquakes</guilabel></term>
1077           <listitem><para>Displays the earthquake markers on the map.</para></listitem>
1078         </varlistentry>
1079 
1080         <varlistentry id="eclipsesplugin">
1081           <term><guilabel>Eclipses</guilabel></term>
1082           <listitem><para>Displays the data about Solar and Moon eclipses.</para></listitem>
1083         </varlistentry>
1084 
1085         <varlistentry>
1086           <term><guilabel>Elevation Profile</guilabel></term>
1087           <listitem><para>Displays the elevation profile overlay for <link linkend="routing">the routes on the map</link>.</para></listitem>
1088         </varlistentry>
1089 
1090         <varlistentry>
1091           <term><guilabel>Elevation Profile Marker</guilabel></term>
1092           <listitem><para>Marks the current elevation of the elevation profile on the map.</para></listitem>
1093         </varlistentry>
1094 
1095         <varlistentry>
1096           <term><guilabel>GpsInfo</guilabel></term>
1097           <listitem><para>Displays a float item that provides <ulink url="https://en.wikipedia.org/wiki/Global_Positioning_System">GPS</ulink> information.</para></listitem>
1098         </varlistentry>
1099 
1100         <varlistentry>
1101           <term><guilabel>License</guilabel></term>
1102           <listitem><para>Displays a float item that provides copyright information.</para></listitem>
1103         </varlistentry>
1104 
1105         <varlistentry id="measure-tool-config">
1106           <term><guilabel>Measure Tool</guilabel></term>
1107           <listitem><para>The plugin to <link linkend="measure-distances">measure distances between two or more points</link>.</para>
1108 
1109           <para>Displaying of the distance and the bearing between the points can be configured after pressing the tool icon. It is enough to check the corresponding item to make &marble; show the labels or uncheck the item to hide the labels.</para></listitem>
1110         </varlistentry>
1111 
1112         <varlistentry>
1113           <term><guilabel>Navigation</guilabel></term>
1114           <listitem><para>Displays the mouse control to zoom and move as float item on the map.</para></listitem>
1115         </varlistentry>
1116 
1117         <varlistentry>
1118           <term><guilabel>OSM Mapper Notes</guilabel></term>
1119           <listitem><para>Implementation of geocoding notes.</para></listitem>
1120         </varlistentry>
1121 
1122 <!--        <varlistentry>
1123           <term><guilabel>OpenCaching.com</guilabel></term>
1124           <listitem><para>Displays the <ulink url="https://en.wikipedia.org/wiki/Geocaching">geocaching</ulink> markers on the map.</para></listitem>
1125         </varlistentry>-->
1126 
1127         <varlistentry>
1128           <term><guilabel>OpenDesktop Items</guilabel></term>
1129           <listitem><para>Shows <ulink url="https://opendesktop.org/">OpenDesktop</ulink> users' avatars and some extra information about them on the map.</para></listitem>
1130         </varlistentry>
1131 
1132         <varlistentry>
1133           <term><guilabel>Overview Map</guilabel></term>
1134           <listitem><para>This is a float item that provides an overview map.</para></listitem>
1135         </varlistentry>
1136 
1137         <varlistentry>
1138           <term><guilabel>Photos</guilabel></term>
1139           <listitem><para>Automatically downloads images from around the world in preference to their popularity.</para></listitem>
1140         </varlistentry>
1141 
1142         <varlistentry>
1143           <term><guilabel>Places</guilabel></term>
1144           <listitem><para>Displays trending <ulink url="https://foursquare.com/">Foursquare</ulink> places.</para></listitem>
1145         </varlistentry>
1146 
1147         <varlistentry>
1148           <term><guilabel>Position Marker</guilabel></term>
1149           <listitem><para>Draws a marker at the current <ulink url="https://en.wikipedia.org/wiki/Global_Positioning_System">GPS</ulink> position.</para></listitem>
1150         </varlistentry>
1151 
1152         <varlistentry>
1153           <term><guilabel>Postal Codes</guilabel></term>
1154           <listitem><para>Shows <ulink url="https://en.wikipedia.org/wiki/Postal_code">postal codes</ulink> of the area on the map.</para></listitem>
1155         </varlistentry>
1156 
1157         <varlistentry>
1158           <term><guilabel>Routing</guilabel></term>
1159           <listitem><para>Displays the <link linkend="routing">routing information</link> and navigation controls.</para></listitem>
1160         </varlistentry>
1161 
1162         <varlistentry>
1163           <term><guilabel>Satellites</guilabel></term>
1164           <listitem><para>Displays the Earth and other planets natural and artificial satellites and their orbits.</para></listitem>
1165         </varlistentry>
1166 
1167         <varlistentry>
1168           <term><guilabel>Scale Bar</guilabel></term>
1169           <listitem><para>This is a float item that provides a map scale.</para></listitem>
1170         </varlistentry>
1171 
1172         <varlistentry>
1173           <term><guilabel>Speedometer</guilabel></term>
1174           <listitem><para>Displays the current cruising speed. Needs some <ulink url="https://en.wikipedia.org/wiki/Global_Positioning_System">GPS</ulink> data.</para></listitem>
1175         </varlistentry>
1176 
1177         <varlistentry>
1178           <term><guilabel>Stars</guilabel></term>
1179           <listitem><para>A plugin that shows the Starry Sky.</para></listitem>
1180         </varlistentry>
1181 
1182         <varlistentry>
1183           <term><guilabel>Sun</guilabel></term>
1184           <listitem><para>A plugin that shows the Sun.</para></listitem>
1185         </varlistentry>
1186 
1187         <varlistentry>
1188           <term><guilabel>Weather</guilabel></term>
1189           <listitem><para>Downloads current weather information of cities and displays them in the map.</para></listitem>
1190         </varlistentry>
1191 
1192         <varlistentry>
1193           <term><guilabel>Wikipedia Articles</guilabel></term>
1194           <listitem><para>Automatically downloads Wikipedia articles and shows them on the right position on the map.</para></listitem>
1195         </varlistentry>
1196       </variablelist>
1197     </sect1>
1198   </chapter>
1199 
1200   <chapter id="faq">
1201   <title>Questions and Answers</title>
1202 
1203     <qandaset id="faqlist">
1204       <qandaentry>
1205         <question>
1206           <para>I cannot see my house on the map / Why should I use &marble; if there is <application>Google Earth</application> already?</para>
1207         </question>
1208         <answer>
1209           <para>&marble; aims to be a lightweight fast educational geographical browser that easily runs on any platform that is supported by &Qt;. While higher resolution maps would be nice to have they aren't necessary for every user and every use case (just like you don't use a full blown text processor each time you just need a simple editor). Also notice &marble; is free software and is based on data that can be freely redistributed in the same way that applies to Free Software.</para>
1210         </answer>
1211       </qandaentry>
1212 
1213       <qandaentry>
1214         <question>
1215           <para>Why is &marble; so fast although I don't have hardware acceleration enabled? / Why doesn't &marble; run smoothly on my expensive 3D graphics card?</para>
1216         </question>
1217         <answer>
1218           <para>Despite depicting the earth as a globe &marble; doesn't make use of any 3D hardware acceleration. This has the advantage of running at a decent speed on any platform and hardware supported by &Qt;. However it has the disadvantage that it doesn't run as smoothly as it could if it used hardware accelerated OpenGL. &marble; just uses plain 2D graphics and therefore requires a graphics adapter that is fast at drawing 2D graphics. We plan to add an optional OpenGL backend in the future.</para>
1219         </answer>
1220       </qandaentry>
1221 
1222       <qandaentry>
1223         <question>
1224           <para>Will I ever have to pay for &marble;?</para>
1225         </question>
1226         <answer>
1227           <para>No, never. But the authors always welcome feedback. &marble; is licensed under the <ulink url="https://www.gnu.org/licenses/licenses.html#LGPL">LGPL</ulink>, so you will never have to pay for this program.</para>
1228         </answer>
1229       </qandaentry>
1230 
1231       <qandaentry>
1232         <question>
1233           <para>How can I contribute?</para>
1234         </question>
1235         <answer>
1236           <para>&marble; is not only an application but also a Free Software project. As such it's easy to join: just contact us via the marble-devel mailing list (marble-devel@kde.org).</para>
1237         </answer>
1238       </qandaentry>
1239     </qandaset>
1240   </chapter>
1241 
1242   <chapter id="credits">
1243   <title>Credits and License</title>
1244 
1245     <para>&marble;</para>
1246 
1247     <para>Program Copyright, 2005-2007 &Torsten.Rahn; &Torsten.Rahn.mail;</para>
1248 
1249     <para>Contributors:</para>
1250 
1251     <itemizedlist>
1252       <listitem><para>&Torsten.Rahn; &Torsten.Rahn.mail;</para></listitem>
1253       <listitem><para>Inge Wallin <email>inge@lysator.liu.se</email></para></listitem>
1254     </itemizedlist>
1255 
1256     <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
1257     &underFDL;           <!-- FDL: do not remove -->
1258     &underLGPL;           <!-- LGPL License -->
1259   </chapter>
1260 
1261   &documentation.index;
1262 </book>
1263 <!--
1264 Local Variables:
1265 mode: sgml
1266 sgml-minimize-attributes:nil
1267 sgml-general-insert-case:lower
1268 sgml-indent-step:0
1269 sgml-indent-data:nil
1270 End:
1271 
1272 // vim:ts=2:sw=2:tw=78:noet:noai
1273 -->