Add user documentations

- Use an AsciiDoc file to generate a man page and a html page.

- Add Help->Contents menu which opens the HTML page in the default
  browser.

diff --git a/data/main.ui.in b/data/main.ui.in
index edcc377dae0c3fa260717a7444c5fb72f7cdd8d6..986c02966520e37de99d144601bc17dda04e9db6 100644 (file)
--- a/data/main.ui.in
+++ b/data/main.ui.in
@@ -50,15 +50,15 @@
                       <object class="GtkCheckMenuItem" id="main_menu_file_offline">
                         <property name="visible">True</property>
                         <property name="tooltip_text" translatable="yes">Work offline</property>
-                        <property name="related_action">offline</property>
                         <property name="use_action_appearance">True</property>
+                        <property name="related_action">offline</property>
                       </object>
                     </child>
                     <child>
                       <object class="GtkImageMenuItem" id="main_menu_file_prefs">
                         <property name="visible">True</property>
-                        <property name="related_action">prefs</property>
                         <property name="use_action_appearance">True</property>
+                        <property name="related_action">prefs</property>
                         <property name="use_underline">True</property>
                         <property name="use_stock">True</property>
                       </object>
@@ -71,8 +71,8 @@
                     <child>
                       <object class="GtkImageMenuItem" id="main_menu_file_quit">
                         <property name="visible">True</property>
-                        <property name="related_action">quit</property>
                         <property name="use_action_appearance">True</property>
+                        <property name="related_action">quit</property>
                         <property name="use_underline">True</property>
                         <property name="use_stock">True</property>
                       </object>
@@ -92,8 +92,8 @@
                     <child>
                       <object class="GtkImageMenuItem" id="main_menu_view_zoomin">
                         <property name="visible">True</property>
-                        <property name="related_action">zoomin</property>
                         <property name="use_action_appearance">True</property>
+                        <property name="related_action">zoomin</property>
                         <property name="use_underline">True</property>
                         <property name="use_stock">True</property>
                       </object>
@@ -101,8 +101,8 @@
                     <child>
                       <object class="GtkImageMenuItem" id="main_menu_view_zoomout">
                         <property name="visible">True</property>
-                        <property name="related_action">zoomout</property>
                         <property name="use_action_appearance">True</property>
+                        <property name="related_action">zoomout</property>
                         <property name="use_underline">True</property>
                         <property name="use_stock">True</property>
                       </object>
@@ -115,8 +115,8 @@
                     <child>
                       <object class="GtkImageMenuItem" id="main_menu_view_refresh">
                         <property name="visible">True</property>
-                        <property name="related_action">refresh</property>
                         <property name="use_action_appearance">True</property>
+                        <property name="related_action">refresh</property>
                         <property name="use_underline">True</property>
                         <property name="use_stock">True</property>
                       </object>
@@ -133,11 +133,26 @@
                 <child type="submenu">
                   <object class="GtkMenu" id="main_menu_help_menu">
                     <property name="visible">True</property>
+                    <child>
+                      <object class="GtkImageMenuItem" id="main_menu_help_contents">
+                        <property name="visible">True</property>
+                        <property name="use_action_appearance">True</property>
+                        <property name="related_action">contents</property>
+                        <property name="use_underline">True</property>
+                        <property name="use_stock">True</property>
+                        <signal name="activate" handler="on_help_contents"/>
+                      </object>
+                    </child>
+                    <child>
+                      <object class="GtkSeparatorMenuItem" id="separatormenuitem1">
+                        <property name="visible">True</property>
+                      </object>
+                    </child>
                     <child>
                       <object class="GtkImageMenuItem" id="main_menu_help_about">
                         <property name="visible">True</property>
-                        <property name="related_action">about</property>
                         <property name="use_action_appearance">True</property>
+                        <property name="related_action">about</property>
                         <property name="use_underline">True</property>
                         <property name="use_stock">True</property>
                       </object>
@@ -159,8 +174,8 @@
             <child>
               <object class="GtkToolButton" id="main_tb_zoomin">
                 <property name="visible">True</property>
-                <property name="related_action">zoomin</property>
                 <property name="use_action_appearance">True</property>
+                <property name="related_action">zoomin</property>
               </object>
               <packing>
                 <property name="expand">False</property>
@@ -170,8 +185,8 @@
             <child>
               <object class="GtkToolButton" id="main_tb_zoomout">
                 <property name="visible">True</property>
-                <property name="related_action">zoomout</property>
                 <property name="use_action_appearance">True</property>
+                <property name="related_action">zoomout</property>
               </object>
               <packing>
                 <property name="expand">False</property>
@@ -190,8 +205,8 @@
             <child>
               <object class="GtkToggleToolButton" id="main_tb_offline">
                 <property name="visible">True</property>
-                <property name="related_action">offline</property>
                 <property name="use_action_appearance">True</property>
+                <property name="related_action">offline</property>
                 <property name="label" translatable="yes">toolbutton3</property>
                 <property name="use_underline">True</property>
               </object>
@@ -203,8 +218,8 @@
             <child>
               <object class="GtkToolButton" id="main_tb_refresh">
                 <property name="visible">True</property>
-                <property name="related_action">refresh</property>
                 <property name="use_action_appearance">True</property>
+                <property name="related_action">refresh</property>
                 <property name="use_underline">True</property>
               </object>
               <packing>
@@ -224,8 +239,8 @@
             <child>
               <object class="GtkToolButton" id="main_tb_prefs">
                 <property name="visible">True</property>
-                <property name="related_action">prefs</property>
                 <property name="use_action_appearance">True</property>
+                <property name="related_action">prefs</property>
                 <property name="label" translatable="yes">toolbutton1</property>
                 <property name="use_underline">True</property>
               </object>
@@ -900,13 +915,19 @@ The hypothetical commands `show w' and `show c' should show the appropriate part
   </object>
   <object class="GtkSizeGroup" id="prefs_general_size">
     <widgets>
-      <widget name="prefs_general_log_label"/>
-      <widget name="prefs_general_url_label"/>
       <widget name="prefs_general_site_label"/>
+      <widget name="prefs_general_url_label"/>
+      <widget name="prefs_general_log_label"/>
     </widgets>
   </object>
   <object class="GtkAdjustment" id="prefs_general_log_adj">
     <property name="upper">8</property>
     <property name="step_increment">1</property>
   </object>
+  <object class="GtkAction" id="contents">
+    <property name="label">Contents</property>
+    <property name="short_label">Contents</property>
+    <property name="tooltip">AWeather Reference Manual</property>
+    <property name="stock_id">gtk-help</property>
+  </object>
 </interface>

diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644 (file)
index 0000000..d0a941d
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,3 @@
+*.1
+*.html
+*.xml

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 2b6c15785a28184dee9c4404ea55dd939a9f143b..03af3ec79664c26590b5ba48298c5712f9afdb43 100644 (file)
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,4 +1,14 @@
-# TODO: write man pages
+man1_MANS = aweather.1
+html_DATA = aweather.html
+
+%.html: %.ad
+       asciidoc $<
+
+%.1: %.ad
+       a2x -f manpage $<
+
+test: $(man1_MANS)
+       nroff -man $(man1_MANS)
 
 maintainer-clean-local:
        rm -f Makefile.in

diff --git a/docs/aweather.ad b/docs/aweather.ad
new file mode 100644 (file)
index 0000000..c21c097
--- /dev/null
+++ b/docs/aweather.ad
@@ -0,0 +1,98 @@
+aweather(1)
+===========
+Andy Spencer <andy753421@gmail.com>
+
+NAME
+----
+aweather - Advanced weather reporting program
+
+SYNOPSIS
+--------
+*aweather* [*-aho*] [-d 'level'] [-s 'site']
+
+DESCRIPTION
+-----------
+AWeather is a advanced weather reporting program which is designed to be used
+by weather enthusiasts. AWeather is not another weather dockapp that simply
+displays a pre-computed forecast. It is designed to be an easy to use program
+that integrates a variety of weather data in simple unified interface; see
+features for more details.
+
+OPTIONS
+-------
+*-a*, *--auto*::
+       Auto update radar (todo)
+
+*-h*, *--help*::
+       Show usage.
+
+*-d*, *--debug*='level'::
+       Change default log level*, a debug level ranges from 0 to 7. A debug
+       level of 7 is recommended only for debugging purposes.
+
+*-s*, *--site*='site'::
+       Set initial site. The site should be given as a WSR88D site code such
+       as KLSX. 
+
+*-o*, *--offline*::
+       Run in offline mode, AWeather will not attempt to connect to the
+       internet to download radar files but will show the closest matching
+       cached file.
+
+KEY BINDINGS
+------------
+*h*, *j*, *k*, *l*::
+*Left*, *Down*, *Up*, *Right*::
+       Pan the surface of the earth left, down, up, or right.
+
+*i*, *o*::
+*+*, *-*::
+*Scroll up*, *Scroll down*::
+       Zoom towards or away from the surface of the earth.
+
+*J*, *K*::
+       Zoom
+       Rotate the camera back or forward. If looking across the surface of the
+       earth, J will point the camera towards ground while K will point the
+       camera towards the sky.
+
+*H*, *L*::
+       Rotate the counter clockwise or clockwise around the vertical axes. If
+       looking across the surface of the earth, H will pan to the left while L
+       will pan to the right.
+
+*w*::
+       Draw a wire frame of the earth for debugging purposes.
+
+*q*::
+       Exit AWeather.
+
+*Tab*::
+       Cycle through available plugins.
+
+*CTRL-R*::
+       Refresh all map data.
+
+MOUSE MOTION
+------------
+*Left-click and drag*::
+       Pan the surface of the earth.
+
+*Middle-click and drag*::
+       Zoom towards (up) or away (down) from the surface of the earth.
+
+*Right-click and drag*::
+       Rotate the camera around the vertical and horizontal axes.
+
+EXAMPLES
+--------
+Start AWeather in offline mode and center the map on the St. Louis radar.::
+`$ aweather -s KLSX -o`
+
+SEE ALSO
+--------
+gis-demo(1)
+
+BUGS
+----
+Many

diff --git a/src/Makefile.am b/src/Makefile.am
index 535b1d052f7b3c887197800a2154cb93dbd32014..7bba88f8b6bc0714e886754d2ece864f2c9e2e8a 100644 (file)
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -8,6 +8,7 @@ aweather_SOURCES  = main.c \
        aweather-gui.c      aweather-gui.h \
        aweather-location.c aweather-location.h
 aweather_CPPFLAGS = \
+       -DHTMLDIR="\"$(dots)$(htmldir)\"" \
        -DPKGDATADIR="\"$(dots)$(pkgdatadir)\"" \
        -DPLUGINSDIR="\"$(dots)$(pkglibdir)\""
 aweather_LDADD    = $(GIS_LIBS)

diff --git a/src/aweather-gui.c b/src/aweather-gui.c
index 5c2558fe914e101d33cbd761870d57a9144a4e77..42f65af660fd5dbb16bfb585b4eca50f1c4819ee 100644 (file)
--- a/src/aweather-gui.c
+++ b/src/aweather-gui.c
@@ -49,6 +49,16 @@ G_MODULE_EXPORT gboolean on_gui_key_press(GtkWidget *widget, GdkEventKey *event,
        return FALSE;
 }
 
+G_MODULE_EXPORT void on_help_contents(GtkMenuItem *menu, AWeatherGui *self)
+{
+       GError *err = NULL;
+       const gchar *uri = "file://" HTMLDIR "/aweather.html";
+       gtk_show_uri(NULL, uri, GDK_CURRENT_TIME, &err);
+       if (err)
+               g_warning("Unable to open help page: %s - %s", uri, err->message);
+       g_error_free(err);
+}
+
 G_MODULE_EXPORT void on_quit(GtkMenuItem *menu, AWeatherGui *self)
 {
        gtk_widget_destroy(GTK_WIDGET(self));