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>
  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 Google 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>Currently, there is a single object class available: VikSlippyMapSource. Such feature allows to declare any map's source working like OpenStreetMap.</para>
 185         <para>The related properties are:
 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       </formalpara>
 206
 207       <formalpara>
 208         <title>Go-to search engines</title>
 209         <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>
 210         <para>An example of the file in the distribution <filename>doc/examples/goto_tools.xml</filename>.</para>
 211         <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>
 212         <para>The related properties are:
 213           <variablelist>
 214             <varlistentry>
 215               <term>label</term>
 216               <listitem><para>the text displayed in the <guilabel>Go-To</guilabel> dialog</para></listitem>
 217             </varlistentry>
 218             <varlistentry>
 219               <term>url-format</term>
 220               <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>
 221             </varlistentry>
 222             <varlistentry>
 223               <term>lat-path</term>
 224               <listitem><para>XML path of the latitude (eg. <literal>/root/parent/elem</literal>)</para></listitem>
 225             </varlistentry>
 226             <varlistentry>
 227               <term>lat-attr (optional)</term>
 228               <listitem><para>name of the attribute (of previous element) containing the latitude</para></listitem>
 229             </varlistentry>
 230             <varlistentry>
 231               <term>lon-path</term>
 232               <listitem><para>XML path of the longitude (eg. <literal>/root/parent/elem</literal>)</para></listitem>
 233             </varlistentry>
 234             <varlistentry>
 235               <term>lon-attr (optional)</term>
 236               <listitem><para>name of the attribute (of previous element) containing the longiude</para></listitem>
 237             </varlistentry>
 238           </variablelist>
 239         </para>
 240         <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>
 241       </formalpara>
 242
 243       <formalpara>
 244         <title>External tools</title>
 245         <para>It is possible to add new external tools. The file is <filename>~/.viking/external_tools.xml</filename>.</para>
 246         <para>An example of the file in the distribution <filename>doc/examples/external_tools.xml</filename>.</para>
 247         <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>
 248         <para>The related properties are:
 249           <variablelist>
 250             <varlistentry>
 251               <term>id</term>
 252               <listitem><para>this is an integer and should be unique as it used to identify the tool</para></listitem>
 253             </varlistentry>
 254             <varlistentry>
 255               <term>label</term>
 256               <listitem><para>the text displayed in the menu entry</para></listitem>
 257             </varlistentry>
 258             <varlistentry>
 259               <term>url</term>
 260               <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>
 261             </varlistentry>
 262           </variablelist>
 263         </para>
 264       </formalpara>
 265
 266   </refsect1>
 267   <refsect1>
 268     <title>FILES</title>
 269
 270     <variablelist>
 271       <varlistentry>
 272         <term><filename>~/.viking/maps.xml</filename></term>
 273         <listitem>
 274           <para>File containing definition of map sources.</para>
 275           <para>See previous section for details.</para>
 276        </listitem>
 277       </varlistentry>
 278       <varlistentry>
 279         <term><filename>~/.viking/goto_tools.xml</filename></term>
 280         <listitem>
 281           <para>File containing definition of "Go-to" services.</para>
 282           <para>See previous section for details.</para>
 283        </listitem>
 284       </varlistentry>
 285       <varlistentry>
 286         <term><filename>~/.viking/external_tools.xml</filename></term>
 287         <listitem>
 288           <para>File containing definition of external tools.</para>
 289           <para>See previous section for details.</para>
 290        </listitem>
 291       </varlistentry>
 292       <varlistentry>
 293         <term><filename>~/.viking/viking.prefs</filename></term>
 294         <listitem>
 295           <para>Preferences for &dhpackage;.</para>
 296         </listitem>
 297       </varlistentry>
 298       <varlistentry>
 299         <term><filename>~/.viking/cookies.txt</filename></term>
 300         <listitem>
 301           <para>File hosting cookies used by &dhpackage;.</para>
 302         </listitem>
 303       </varlistentry>
 304       <varlistentry>
 305         <term><filename>~/.viking-maps/</filename></term>
 306         <listitem>
 307           <para>Map cache of tiles downloaded by &dhpackage;.</para>
 308         </listitem>
 309       </varlistentry>
 310     </variablelist>
 311
 312   </refsect1>
 313   <refsect1>
 314     <title>SEE ALSO</title>
 315
 316     <para>viking-remote (1).</para>
 317   </refsect1>
 318   <refsect1>
 319     <title>AUTHOR</title>
 320
 321     <para>This manual page was written by &dhusername; &dhemail; for
 322       the &debian; system (but may be used by others).  Permission is
 323       granted to copy, distribute and/or modify this document under
 324       the terms of the &gnu; General Public License, Version 2 any
 325           later version published by the Free Software Foundation.
 326     </para>
 327         <para>
 328           On Debian systems, the complete text of the GNU General Public
 329           License can be found in /usr/share/common-licenses/GPL.
 330         </para>
 331
 332   </refsect1>
 333 </refentry>
 334