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>2008-05-02</date>">
  34   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
  35        allowed: see man(7), man(1). -->
  36   <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  37   <!ENTITY dhemail     "<email>ranfyy@gmail.com</email>">
  38   <!ENTITY dhusername  "Ralf Meyer">
  39   <!ENTITY dhucpackage "<refentrytitle>VIKING</refentrytitle>">
  40   <!ENTITY dhpackage   "viking">
  41
  42   <!ENTITY debian      "<productname>Debian</productname>">
  43   <!ENTITY gnu         "<acronym>GNU</acronym>">
  44   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  45 ]>
  46
  47 <refentry xmlns:xi="http://www.w3.org/2001/XInclude">
  48   <refentryinfo>
  49     <address>
  50       &dhemail;
  51     </address>
  52     <copyright>
  53       <year>2007</year>
  54       <holder>&dhusername;</holder>
  55     </copyright>
  56     <copyright>
  57       <year>2010</year>
  58       <holder>Guilhem Bonnefille</holder>
  59     </copyright>
  60     &dhdate;
  61   </refentryinfo>
  62   <refmeta>
  63     &dhucpackage;
  64
  65     &dhsection;
  66   </refmeta>
  67   <refnamediv>
  68     <refname>&dhpackage;</refname>
  69
  70     <refpurpose>program to manage GPS data</refpurpose>
  71   </refnamediv>
  72   <refsynopsisdiv>
  73     <cmdsynopsis>
  74       <command>&dhpackage;</command>
  75       <group choice="opt">
  76         <arg choice="plain"><option>-d</option></arg>
  77         <arg choice="plain"><option>--debug</option></arg>
  78       </group>
  79       <group choice="opt">
  80         <arg choice="plain"><option>-V</option></arg>
  81         <arg choice="plain"><option>--verbose</option></arg>
  82       </group>
  83       <arg rep="repeat"><replaceable>file</replaceable></arg>
  84     </cmdsynopsis>
  85     <cmdsynopsis>
  86       <command>&dhpackage;</command>
  87       <group choice="opt">
  88         <arg choice="plain"><option>-h</option></arg>
  89         <arg choice="plain"><option>--help</option></arg>
  90       </group>
  91     </cmdsynopsis>
  92     <cmdsynopsis>
  93       <command>&dhpackage;</command>
  94       <group choice="opt">
  95         <arg choice="plain"><option>-v</option></arg>
  96         <arg choice="plain"><option>--version</option></arg>
  97       </group>
  98     </cmdsynopsis>
  99   </refsynopsisdiv>
 100   <refsect1>
 101     <title>DESCRIPTION</title>
 102
 103     <para>
 104   Viking is a free/open source program to manage GPS data. You can
 105   import and plot tracks and waypoints, show OpenStreetMap (OSM) maps and/or
 106   Terraserver maps under it, add coordinate lines, make new tracks
 107   and waypoints, hide different things, etc. It is written in C
 108   with the GTK+ 2 toolkit, available for Linux, other POSIX
 109   operating systems, and Windows, and is licensed under the GNU GPL.
 110     </para>
 111     <para>
 112   Homepage: <ulink type="http" url="http://viking.sf.net">http://viking.sf.net</ulink>
 113     </para>
 114
 115     <para>This manual page was written for the &debian; distribution
 116       because the original program does not have a manual page.
 117     </para>
 118
 119     <para><command>&dhpackage;</command> is a program to manage GPS data</para>
 120
 121   </refsect1>
 122   <refsect1>
 123     <title>OPTIONS</title>
 124
 125     <variablelist>
 126       <varlistentry>
 127         <term><option>file</option></term>
 128         <listitem>
 129           <para>Specify file to load at start.</para>
 130         </listitem>
 131       </varlistentry>
 132       <varlistentry>
 133         <term><option>-d</option></term>
 134         <term><option>--debug</option></term>
 135         <listitem>
 136           <para>Enable debug output.</para>
 137         </listitem>
 138       </varlistentry>
 139       <varlistentry>
 140         <term><option>-V</option></term>
 141         <term><option>--verbose</option></term>
 142         <listitem>
 143           <para>Enable verbose output.</para>
 144         </listitem>
 145       </varlistentry>
 146       <varlistentry>
 147         <term><option>-?</option></term>
 148         <term><option>--help</option></term>
 149         <listitem>
 150           <para>Show help options.</para>
 151         </listitem>
 152       </varlistentry>
 153       <varlistentry>
 154         <term><option>-v</option></term>
 155         <term><option>--version</option></term>
 156         <listitem>
 157           <para>Show version.</para>
 158         </listitem>
 159       </varlistentry>
 160     </variablelist>
 161
 162   </refsect1>
 163   <refsect1>
 164     <title>Extending Viking</title>
 165
 166       <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>
 167       <para>Here is an example:
 168 <literallayout><![CDATA[
 169 <objects>
 170   <object class="ClassName">
 171     <property name="property_name1">Property value</property>
 172     <property name="property_name2">Property value</property>
 173   </object>
 174   ...
 175 <objects>
 176 ]]>
 177 </literallayout>
 178 </para>
 179       <para>You can find more examples in the documentation part of the distribution.</para>
 180       <formalpara>
 181         <title>Map Source</title>
 182         <para>It is possible to add new map's sources. The file is <filename>~/.viking/maps.xml</filename>.</para>
 183         <para>An example of the file in the distribution <filename>doc/examples/maps.xml</filename>.</para>
 184         <para>The VikSlippyMapSource allows to declare any map's source working like OpenStreetMap. It supports the following properties:
 185           <variablelist>
 186             <varlistentry>
 187               <term>id</term>
 188               <listitem><para>this is an integer and should be unique as it used to identify the map source</para></listitem>
 189             </varlistentry>
 190             <varlistentry>
 191               <term>label</term>
 192               <listitem><para>the text displayed in the map's source selection dialog</para></listitem>
 193             </varlistentry>
 194             <varlistentry>
 195               <term>hostname</term>
 196               <listitem><para>the server's hostname (eg. "tile.openstreetmap.org")</para></listitem>
 197             </varlistentry>
 198             <varlistentry>
 199               <term>url</term>
 200               <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>
 201             </varlistentry>
 202           </variablelist>
 203         </para>
 204         <para>The VikTmsMapSource allows to declare any TMS service. It supports the following properties:
 205           <variablelist>
 206             <varlistentry>
 207               <term>id</term>
 208               <listitem><para>this is an integer and should be unique as it used to identify the map source</para></listitem>
 209             </varlistentry>
 210             <varlistentry>
 211               <term>label</term>
 212               <listitem><para>the text displayed in the map's source selection dialog</para></listitem>
 213             </varlistentry>
 214             <varlistentry>
 215               <term>hostname</term>
 216               <listitem><para>the server's hostname (eg. "tile.openstreetmap.org")</para></listitem>
 217             </varlistentry>
 218             <varlistentry>
 219               <term>url</term>
 220               <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>
 221             </varlistentry>
 222           </variablelist>
 223         </para>
 224         <para>The VikWmscMapSource allows to declare any WMS or WMS-C service. It supports the following properties:
 225           <variablelist>
 226             <varlistentry>
 227               <term>id</term>
 228               <listitem><para>this is an integer and should be unique as it used to identify the map source</para></listitem>
 229             </varlistentry>
 230             <varlistentry>
 231               <term>label</term>
 232               <listitem><para>the text displayed in the map's source selection dialog</para></listitem>
 233             </varlistentry>
 234             <varlistentry>
 235               <term>hostname</term>
 236               <listitem><para>the server's hostname (eg. "tile.openstreetmap.org")</para></listitem>
 237             </varlistentry>
 238             <varlistentry>
 239               <term>url</term>
 240               <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>
 241             </varlistentry>
 242           </variablelist>
 243         </para>
 244       </formalpara>
 245
 246       <formalpara>
 247         <title>Go-to search engines</title>
 248         <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>
 249         <para>An example of the file in the distribution <filename>doc/examples/goto_tools.xml</filename>.</para>
 250         <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>
 251         <para>The related properties are:
 252           <variablelist>
 253             <varlistentry>
 254               <term>label</term>
 255               <listitem><para>the text displayed in the <guilabel>Go-To</guilabel> dialog</para></listitem>
 256             </varlistentry>
 257             <varlistentry>
 258               <term>url-format</term>
 259               <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>
 260             </varlistentry>
 261             <varlistentry>
 262               <term>lat-path</term>
 263               <listitem><para>XML path of the latitude (eg. <literal>/root/parent/elem</literal>)</para></listitem>
 264             </varlistentry>
 265             <varlistentry>
 266               <term>lat-attr (optional)</term>
 267               <listitem><para>name of the attribute (of previous element) containing the latitude</para></listitem>
 268             </varlistentry>
 269             <varlistentry>
 270               <term>lon-path</term>
 271               <listitem><para>XML path of the longitude (eg. <literal>/root/parent/elem</literal>)</para></listitem>
 272             </varlistentry>
 273             <varlistentry>
 274               <term>lon-attr (optional)</term>
 275               <listitem><para>name of the attribute (of previous element) containing the longiude</para></listitem>
 276             </varlistentry>
 277           </variablelist>
 278         </para>
 279         <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>
 280       </formalpara>
 281
 282       <formalpara>
 283         <title>External tools</title>
 284         <para>It is possible to add new external tools. The file is <filename>~/.viking/external_tools.xml</filename>.</para>
 285         <para>An example of the file in the distribution <filename>doc/examples/external_tools.xml</filename>.</para>
 286         <para>Currently, there is a single object class available: VikWebtoolCenter. Such feature allows to declare any Webtool using a logic based on center coordinates and zoom level value.</para>
 287         <para>The related properties are:
 288           <variablelist>
 289             <varlistentry>
 290               <term>id</term>
 291               <listitem><para>this is an integer and should be unique as it used to identify the tool</para></listitem>
 292             </varlistentry>
 293             <varlistentry>
 294               <term>label</term>
 295               <listitem><para>the text displayed in the menu entry</para></listitem>
 296             </varlistentry>
 297             <varlistentry>
 298               <term>url</term>
 299               <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. "http://hostname/%d/%d/%d.png")</para></listitem>
 300             </varlistentry>
 301           </variablelist>
 302         </para>
 303       </formalpara>
 304
 305   </refsect1>
 306   <refsect1>
 307     <title>FILES</title>
 308
 309     <variablelist>
 310       <varlistentry>
 311         <term><filename>~/.viking/maps.xml</filename></term>
 312         <listitem>
 313           <para>File containing definition of map sources.</para>
 314           <para>See previous section for details.</para>
 315        </listitem>
 316       </varlistentry>
 317       <varlistentry>
 318         <term><filename>~/.viking/goto_tools.xml</filename></term>
 319         <listitem>
 320           <para>File containing definition of "Go-to" services.</para>
 321           <para>See previous section for details.</para>
 322        </listitem>
 323       </varlistentry>
 324       <varlistentry>
 325         <term><filename>~/.viking/external_tools.xml</filename></term>
 326         <listitem>
 327           <para>File containing definition of external tools.</para>
 328           <para>See previous section for details.</para>
 329        </listitem>
 330       </varlistentry>
 331       <varlistentry>
 332         <term><filename>~/.viking/viking.prefs</filename></term>
 333         <listitem>
 334           <para>Preferences for &dhpackage;.</para>
 335         </listitem>
 336       </varlistentry>
 337       <varlistentry>
 338         <term><filename>~/.viking/cookies.txt</filename></term>
 339         <listitem>
 340           <para>File hosting cookies used by &dhpackage;.</para>
 341         </listitem>
 342       </varlistentry>
 343       <varlistentry>
 344         <term><filename>~/.viking-maps/</filename></term>
 345         <listitem>
 346           <para>Map cache of tiles downloaded by &dhpackage;.</para>
 347         </listitem>
 348       </varlistentry>
 349     </variablelist>
 350
 351   </refsect1>
 352   <refsect1>
 353     <title>SEE ALSO</title>
 354
 355     <para>viking-remote (1).</para>
 356   </refsect1>
 357   <refsect1>
 358     <title>AUTHOR</title>
 359
 360     <para>This manual page was written by &dhusername; &dhemail; for
 361       the &debian; system (but may be used by others).  Permission is
 362       granted to copy, distribute and/or modify this document under
 363       the terms of the &gnu; General Public License, Version 2 any
 364           later version published by the Free Software Foundation.
 365     </para>
 366         <para>
 367           On Debian systems, the complete text of the GNU General Public
 368           License can be found in /usr/share/common-licenses/GPL.
 369         </para>
 370
 371   </refsect1>
 372 </refentry>
 373