From 1a358f701ff063d3dc0f1ae87fcc70f3dd12660a Mon Sep 17 00:00:00 2001
From: Rob Norris <rw_norris@hotmail.com>
Date: Mon, 8 Sep 2014 01:43:54 +0100
Subject: [PATCH 1/1] [DOC] Add manual section about the command line options.

---
 help/C/commandline.xml | 76 ++++++++++++++++++++++++++++++++++++++++++
 help/C/viking.xml      |  2 ++
 help/Makefile.am       |  4 ++-
 3 files changed, 81 insertions(+), 1 deletion(-)
 create mode 100644 help/C/commandline.xml

diff --git a/help/C/commandline.xml b/help/C/commandline.xml
new file mode 100644
index 00000000..2f1cdf2a
--- /dev/null
+++ b/help/C/commandline.xml
@@ -0,0 +1,76 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
+   [<!ENTITY appname          "Viking">]
+>
+<section id="commandline">
+<title>Command Line</title>
+<para>
+&appname; being a Graphical User Interface program only has a few command line options.
+</para>
+
+<para>
+<screen>viking [OPTIONS...] files+</screen>
+</para>
+
+<para>
+Note that the ordering of files can be important depending on their file type.
+Subsequent non Viking project files are loaded into the previous Viking project, with the files being processed left to right.
+Some examples:
+</para>
+<itemizedlist>
+<listitem><para><literal>viking file1.gpx file2.gpx file3.gpx</literal></para><para> Here all GPX files are loaded into a new &appname; project in one window.</para></listitem>
+<listitem><para><literal>viking file1.vik file2.vik</literal></para><para> Each &appname; project file is opened in a new window.</para></listitem>
+<listitem><para><literal>viking file1.vik file2.gpx file3.gpx</literal></para><para> The GPX files are loaded into the &appname; project in one window.</para></listitem>
+<listitem><para><literal>viking file2.gpx file3.gpx file1.vik</literal></para><para> The GPX files are loaded into a new &appname; project in a one window and the &appname; project is loaded seperately in a seperate window.</para></listitem>
+</itemizedlist>
+
+<table frame='all'><title>Command Line Reference</title>
+<tgroup cols='3' align='left' colsep='1' rowsep='1'>
+<thead>
+<row>
+  <entry>Short Option</entry>
+  <entry>Long Option</entry>
+  <entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+  <entry>-h</entry>
+  <entry>--help</entry>
+  <entry>Show the command line options and then exit.</entry>
+</row>
+<row>
+  <entry>-V</entry>
+  <entry>--verbose</entry>
+  <entry>Run in verbose mode. Some information about what &appname; is doing is shown in stdout.</entry>
+</row>
+<row>
+  <entry>-d</entry>
+  <entry>--debug</entry>
+  <entry>Run in debug mode. Even more information about what &appname; is doing is shown in stdout.
+This also enables some extra information features in the GUI itself, primarily of interest to developers.
+  </entry>
+</row>
+<row>
+  <entry>-v</entry>
+  <entry>--version</entry>
+  <entry>Show the version and then exit.</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<note>
+<para>
+As a special combination when both <emphasis>-V and -d</emphasis> are both enabled at the same time, &appname; will not delete some of the temporary files created during the program run.
+This is especially useful to monitor results of download requests (which need to be interpreted) if they suddenly start failing, as the file will have often more detailed information about the failure mode.
+</para>
+</note>
+
+<para>
+&appname; being a GTK+ program means some options are processed by GTK+ itself such as --display. Use the following to find out what they are for your system:
+<screen>viking --help-gtk</screen>
+</para>
+
+</section>
diff --git a/help/C/viking.xml b/help/C/viking.xml
index 2d0e31a0..221d27ca 100644
--- a/help/C/viking.xml
+++ b/help/C/viking.xml
@@ -3319,6 +3319,8 @@ Accept: */*
 </formalpara>
 </section>
 
+<xi:include href="commandline.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
 <xi:include href="attribution.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
 
 </article>
diff --git a/help/Makefile.am b/help/Makefile.am
index db0f5681..f6c1cfd9 100644
--- a/help/Makefile.am
+++ b/help/Makefile.am
@@ -12,7 +12,9 @@ get-icons:
 dist-hook: get-icons doc-dist-hook
 
 DOC_MODULE = viking
-DOC_ENTITIES = legal.xml attribution.xml
+DOC_ENTITIES = legal.xml \
+    attribution.xml \
+    commandline.xml
 DOC_INCLUDES =
 DOC_FIGURES = \
     figures/addtr_18.png \
-- 
2.39.5