doc/viking.xml

   1 <?xml version='1.0' encoding='ISO-8859-1'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4
   5 <!--
   6
   7 Process this file with an XSLT processor: `xsltproc \
   8 -''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
   9 manpages/docbook.xsl manpage.dbk'.  A manual page
  10 <package>.<section> will be generated.  You may view the
  11 manual page with: nroff -man <package>.<section> | less'.  A
  12 typical entry in a Makefile or Makefile.am is:
  13
  14 DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
  15 manpages/docbook.xsl
  16 XP=xsltproc -''-nonet
  17
  18 manpage.1: manpage.dbk
  19         $(XP) $(DB2MAN) $<
  20
  21 The xsltproc binary is found in the xsltproc package.  The
  22 XSL files are in docbook-xsl.  Please remember that if you
  23 create the nroff version in one of the debian/rules file
  24 targets (such as build), you will need to include xsltproc
  25 and docbook-xsl in your Build-Depends control field.
  26
  27 -->
  28
  29   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  30   <!ENTITY dhfirstname "<firstname>Ralf</firstname>">
  31   <!ENTITY dhsurname   "<surname>Meyer</surname>">
  32   <!-- Please adjust the date whenever revising the manpage. -->
  33   <!ENTITY dhdate      "<date>2012-11-24</date>">
  34   <!-- Would be nice if the version could auto-update. -->
  35   <!ENTITY dhsource      "Viking">
  36   <!ENTITY dhversion     "1.3.2">
  37   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
  38        allowed: see man(7), man(1). -->
  39   <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  40   <!ENTITY dhemail     "<email>ranfyy@gmail.com</email>">
  41   <!ENTITY dhusername  "Ralf Meyer">
  42   <!ENTITY dhucpackage "<refentrytitle>VIKING</refentrytitle>">
  43   <!ENTITY dhpackage   "viking">
  44
  45   <!ENTITY debian      "<productname>Debian</productname>">
  46   <!ENTITY gnu         "<acronym>GNU</acronym>">
  47   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  48 ]>
  49
  50 <reference>
  51 <title>&dhsource; &dhversion;</title>
  52
  53 <refentry xmlns:xi="http://www.w3.org/2001/XInclude">
  54   <refentryinfo>
  55     <address>
  56       &dhemail;
  57     </address>
  58     <copyright>
  59       <year>2007</year>
  60       <holder>&dhusername;</holder>
  61     </copyright>
  62     <copyright>
  63       <year>2010</year>
  64       <holder>Guilhem Bonnefille</holder>
  65     </copyright>
  66     &dhdate;
  67   </refentryinfo>
  68   <refmeta>
  69     &dhucpackage;
  70     &dhsection;
  71     <refmiscinfo CLASS="source">&dhsource;</refmiscinfo>
  72     <refmiscinfo CLASS="version">&dhversion;</refmiscinfo>
  73   </refmeta>
  74   <refnamediv>
  75     <refname>&dhpackage;</refname>
  76
  77     <refpurpose>program to manage GPS data</refpurpose>
  78   </refnamediv>
  79   <refsynopsisdiv>
  80     <cmdsynopsis>
  81       <command>&dhpackage;</command>
  82       <group choice="opt">
  83         <arg choice="plain"><option>-d</option></arg>
  84         <arg choice="plain"><option>--debug</option></arg>
  85       </group>
  86       <group choice="opt">
  87         <arg choice="plain"><option>-V</option></arg>
  88         <arg choice="plain"><option>--verbose</option></arg>
  89       </group>
  90       <arg rep="repeat"><replaceable>file</replaceable></arg>
  91     </cmdsynopsis>
  92     <cmdsynopsis>
  93       <command>&dhpackage;</command>
  94       <group choice="opt">
  95         <arg choice="plain"><option>-h</option></arg>
  96         <arg choice="plain"><option>--help</option></arg>
  97       </group>
  98     </cmdsynopsis>
  99     <cmdsynopsis>
 100       <command>&dhpackage;</command>
 101       <group choice="opt">
 102         <arg choice="plain"><option>-v</option></arg>
 103         <arg choice="plain"><option>--version</option></arg>
 104       </group>
 105     </cmdsynopsis>
 106   </refsynopsisdiv>
 107   <refsect1>
 108     <title>DESCRIPTION</title>
 109
 110     <para>
 111   Viking is a free/open source program to manage GPS data. You can
 112   import and plot tracks and waypoints, show OpenStreetMap (OSM) maps and/or
 113   Terraserver maps under it, add coordinate lines, make new tracks
 114   and waypoints, hide different things, etc. It is written in C
 115   with the GTK+ 2 toolkit, available for Linux, other POSIX
 116   operating systems, and Windows, and is licensed under the GNU GPL.
 117     </para>
 118     <para>
 119   Homepage: <ulink type="http" url="http://viking.sf.net">http://viking.sf.net</ulink>
 120     </para>
 121
 122   </refsect1>
 123   <refsect1>
 124     <title>OPTIONS</title>
 125
 126     <variablelist>
 127       <varlistentry>
 128         <term><option>file</option></term>
 129         <listitem>
 130           <para>Specify file to load at start.</para>
 131         </listitem>
 132       </varlistentry>
 133       <varlistentry>
 134         <term><option>-d</option></term>
 135         <term><option>--debug</option></term>
 136         <listitem>
 137           <para>Enable debug output.</para>
 138         </listitem>
 139       </varlistentry>
 140       <varlistentry>
 141         <term><option>-V</option></term>
 142         <term><option>--verbose</option></term>
 143         <listitem>
 144           <para>Enable verbose output.</para>
 145         </listitem>
 146       </varlistentry>
 147       <varlistentry>
 148         <term><option>-?</option></term>
 149         <term><option>--help</option></term>
 150         <listitem>
 151           <para>Show help options.</para>
 152         </listitem>
 153       </varlistentry>
 154       <varlistentry>
 155         <term><option>-v</option></term>
 156         <term><option>--version</option></term>
 157         <listitem>
 158           <para>Show version.</para>
 159         </listitem>
 160       </varlistentry>
 161     </variablelist>
 162
 163   </refsect1>
 164   <refsect1>
 165     <title>Extending Viking</title>
 166
 167       <para>Currently, &dhpackage; has some extention points based on configuration files. The file format is heavily inspired by the GtkBuilder file format: you specify the class of the GObject to build and set its properties. Technically, it is a XML file containing a "objects" root element. Inside this element, you set a collection of "object".</para>
 168       <para>Here is an example:
 169 <literallayout><![CDATA[
 170 <objects>
 171   <object class="ClassName">
 172     <property name="property_name1">Property value</property>
 173     <property name="property_name2">Property value</property>
 174   </object>
 175   ...
 176 <objects>
 177 ]]>
 178 </literallayout>
 179 </para>
 180       <para>You can find more examples in the documentation part of the distribution.</para>
 181       <formalpara>
 182         <title>Map Source</title>
 183         <para>It is possible to add new map's sources. The file is <filename>~/.viking/maps.xml</filename>.</para>
 184         <para>An example of the file in the distribution <filename>doc/examples/maps.xml</filename>.</para>
 185         <para>The VikSlippyMapSource allows to declare any map's source working like OpenStreetMap. It supports the following properties:
 186           <variablelist>
 187             <varlistentry>
 188               <term>id</term>
 189               <listitem><para>this is an integer and should be unique as it used to identify the map source</para></listitem>
 190             </varlistentry>
 191             <varlistentry>
 192               <term>label</term>
 193               <listitem><para>the text displayed in the map's source selection dialog</para></listitem>
 194             </varlistentry>
 195             <varlistentry>
 196               <term>hostname</term>
 197               <listitem><para>the server's hostname (eg. "tile.openstreetmap.org")</para></listitem>
 198             </varlistentry>
 199             <varlistentry>
 200               <term>url</term>
 201               <listitem><para>the parametrized address of the tile, in the spirit of C printf format, with 3 "%d" fields for X, Y and Z (zoom level) (eg. "/%d/%d/%d.png")</para></listitem>
 202             </varlistentry>
 203           </variablelist>
 204         </para>
 205         <para>The VikTmsMapSource allows to declare any TMS service. It supports the following properties:
 206           <variablelist>
 207             <varlistentry>
 208               <term>id</term>
 209               <listitem><para>this is an integer and should be unique as it used to identify the map source</para></listitem>
 210             </varlistentry>
 211             <varlistentry>
 212               <term>label</term>
 213               <listitem><para>the text displayed in the map's source selection dialog</para></listitem>
 214             </varlistentry>
 215             <varlistentry>
 216               <term>hostname</term>
 217               <listitem><para>the server's hostname (eg. "tile.openstreetmap.org")</para></listitem>
 218             </varlistentry>
 219             <varlistentry>
 220               <term>url</term>
 221               <listitem><para>the parametrized address of the tile, in the spirit of C printf format, with 3 "%d" fields for X, Y and Z (zoom level) (eg. "/%d/%d/%d.png")</para></listitem>
 222             </varlistentry>
 223           </variablelist>
 224         </para>
 225         <para>The VikWmscMapSource allows to declare any WMS or WMS-C service. It supports the following properties:
 226           <variablelist>
 227             <varlistentry>
 228               <term>id</term>
 229               <listitem><para>this is an integer and should be unique as it used to identify the map source</para></listitem>
 230             </varlistentry>
 231             <varlistentry>
 232               <term>label</term>
 233               <listitem><para>the text displayed in the map's source selection dialog</para></listitem>
 234             </varlistentry>
 235             <varlistentry>
 236               <term>hostname</term>
 237               <listitem><para>the server's hostname (eg. "tile.openstreetmap.org")</para></listitem>
 238             </varlistentry>
 239             <varlistentry>
 240               <term>url</term>
 241               <listitem><para>the parametrized address of the tile, in the spirit of C printf format, with 4 "%s" fields for bounding box coordinates (eg. "/coord=%s,%s,%s,%s")</para></listitem>
 242             </varlistentry>
 243           </variablelist>
 244         </para>
 245       </formalpara>
 246
 247       <formalpara>
 248         <title>Go-to search engines</title>
 249         <para>It is possible to add new new search engines for the "Go-To" feature. The file is <filename>~/.viking/goto_tools.xml</filename>.</para>
 250         <para>An example of the file in the distribution <filename>doc/examples/goto_tools.xml</filename>.</para>
 251         <para>Currently, there is a single object class available: VikGotoXmlTool. Such feature allows to declare any search engine using a XML format as result.</para>
 252         <para>The related properties are:
 253           <variablelist>
 254             <varlistentry>
 255               <term>label</term>
 256               <listitem><para>the text displayed in the <guilabel>Go-To</guilabel> dialog</para></listitem>
 257             </varlistentry>
 258             <varlistentry>
 259               <term>url-format</term>
 260               <listitem><para>the parametrized address of the query, in the spirit of C <function>printf</function> format, with a single "%s" field (replaced by the query string)</para></listitem>
 261             </varlistentry>
 262             <varlistentry>
 263               <term>lat-path</term>
 264               <listitem><para>XML path of the latitude (eg. <literal>/root/parent/elem</literal>)</para></listitem>
 265             </varlistentry>
 266             <varlistentry>
 267               <term>lat-attr (optional)</term>
 268               <listitem><para>name of the attribute (of previous element) containing the latitude</para></listitem>
 269             </varlistentry>
 270             <varlistentry>
 271               <term>lon-path</term>
 272               <listitem><para>XML path of the longitude (eg. <literal>/root/parent/elem</literal>)</para></listitem>
 273             </varlistentry>
 274             <varlistentry>
 275               <term>lon-attr (optional)</term>
 276               <listitem><para>name of the attribute (of previous element) containing the longiude</para></listitem>
 277             </varlistentry>
 278           </variablelist>
 279         </para>
 280         <para>As a facility (or readability) it is possible to set both path and attribute name in a single property, like an XPath expression. To do so, simply set both info in lat-path (or lon-path) in the following format: <literal>/root/parent/elem@attribute</literal>.</para>
 281       </formalpara>
 282
 283       <formalpara>
 284         <title>External tools</title>
 285         <para>It is possible to add new external tools. The file is <filename>~/.viking/external_tools.xml</filename>.</para>
 286         <para>An example of the file in the distribution <filename>doc/examples/external_tools.xml</filename>.</para>
 287         <para>The VikWebtoolCenter allows to declare any Webtool using a logic based on center coordinates and zoom level value.</para>
 288         <para>The related properties are:
 289           <variablelist>
 290             <varlistentry>
 291               <term>id</term>
 292               <listitem><para>this is an integer and should be unique as it used to identify the tool</para></listitem>
 293             </varlistentry>
 294             <varlistentry>
 295               <term>label</term>
 296               <listitem><para>the text displayed in the menu entry</para></listitem>
 297             </varlistentry>
 298             <varlistentry>
 299               <term>url</term>
 300               <listitem><para>the parametrized URL to open, in the spirit of C printf format, with 2 "%s" and a "%d" fields for X, Y and Z (zoom level) (eg. "http://hostname/?lat=%s&amp;lon=%s&amp;zoom=%d")</para></listitem>
 301             </varlistentry>
 302           </variablelist>
 303         </para>
 304         <para>The VikWebtoolBounds allows to declare any Webtool using a logic based on bounds coordinates.</para>
 305         <para>The related properties are:
 306           <variablelist>
 307             <varlistentry>
 308               <term>id</term>
 309               <listitem><para>this is an integer and should be unique as it used to identify the tool</para></listitem>
 310             </varlistentry>
 311             <varlistentry>
 312               <term>label</term>
 313               <listitem><para>the text displayed in the menu entry</para></listitem>
 314             </varlistentry>
 315             <varlistentry>
 316               <term>url</term>
 317               <listitem><para>the parametrized address of the tile, in the spirit of C printf format, with 4 "%s" fields for left, right, bottom and top (eg. "http://hostname:8111/load_and_zoom?left=%s&amp;right=%s&amp;bottom=%s&amp;top=%s")</para></listitem>
 318             </varlistentry>
 319           </variablelist>
 320         </para>
 321       </formalpara>
 322
 323   </refsect1>
 324   <refsect1>
 325     <title>FILES</title>
 326
 327     <variablelist>
 328       <varlistentry>
 329         <term><filename>~/.viking/maps.xml</filename></term>
 330         <listitem>
 331           <para>File containing definition of map sources.</para>
 332           <para>See previous section for details.</para>
 333        </listitem>
 334       </varlistentry>
 335       <varlistentry>
 336         <term><filename>~/.viking/goto_tools.xml</filename></term>
 337         <listitem>
 338           <para>File containing definition of "Go-to" services.</para>
 339           <para>See previous section for details.</para>
 340        </listitem>
 341       </varlistentry>
 342       <varlistentry>
 343         <term><filename>~/.viking/external_tools.xml</filename></term>
 344         <listitem>
 345           <para>File containing definition of external tools.</para>
 346           <para>See previous section for details.</para>
 347        </listitem>
 348       </varlistentry>
 349       <varlistentry>
 350         <term><filename>~/.viking/viking.prefs</filename></term>
 351         <listitem>
 352           <para>Preferences for &dhpackage;.</para>
 353         </listitem>
 354       </varlistentry>
 355       <varlistentry>
 356         <term><filename>~/.viking/cookies.txt</filename></term>
 357         <listitem>
 358           <para>File hosting cookies used by &dhpackage;.</para>
 359         </listitem>
 360       </varlistentry>
 361       <varlistentry>
 362         <term><filename>~/.viking-maps/</filename></term>
 363         <listitem>
 364           <para>Map cache of tiles downloaded by &dhpackage;.</para>
 365         </listitem>
 366       </varlistentry>
 367     </variablelist>
 368
 369         <para>Extension files (<filename>maps.xml</filename>,
 370         <filename>goto_tools.xml</filename>,
 371         <filename>external_tools.xml</filename>)
 372         are also searched in <filename>/etc/viking</filename> and
 373         <filename>/usr/share/viking</filename> directories (or related in your system).</para>
 374
 375   </refsect1>
 376   <refsect1>
 377     <title>ENVIRONMENT</title>
 378
 379     <variablelist>
 380       <varlistentry>
 381         <term><envar>XDG_DATA_HOME</envar></term>
 382         <listitem>
 383           <para>Optional directory to look for extension files
 384           (<filename>maps.xml</filename>, <filename>goto_tools.xml</filename>,
 385           <filename>external_tools.xml</filename>).</para>
 386        </listitem>
 387       </varlistentry>
 388       <varlistentry>
 389         <term><envar>XDG_DATA_DIRS</envar></term>
 390         <listitem>
 391           <para>Path used to change the directories scanned for extension files
 392           (<filename>maps.xml</filename>, <filename>goto_tools.xml</filename>,
 393           <filename>external_tools.xml</filename>).</para>
 394        </listitem>
 395       </varlistentry>
 396     </variablelist>
 397
 398   </refsect1>
 399   <refsect1>
 400     <title>AUTHOR</title>
 401
 402     <para>This manual page was written by &dhusername; &dhemail; for
 403       the &debian; system (but may be used by others).  Permission is
 404       granted to copy, distribute and/or modify this document under
 405       the terms of the &gnu; General Public License, Version 2 any
 406           later version published by the Free Software Foundation.
 407     </para>
 408         <para>
 409           On Debian systems, the complete text of the GNU General Public
 410           License can be found in /usr/share/common-licenses/GPL.
 411         </para>
 412
 413   </refsect1>
 414 </refentry>
 415 </reference>