man pages

git-svn-id: file:///home/lennart/svn/public/waproamd/trunk@19 022f378f-78c4-0310-b860-d162c87e6274

5 files changed, 474 insertions, 0 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 0000000..0ff9a4d
--- /dev/null
+++ b/man/Makefile.am
@@ -0,0 +1,43 @@
+# $Id$
+
+# This file is part of waproamd.
+#
+# waproamd is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# waproamd is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with waproamd; if not, write to the Free Software Foundation,
+# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
+
+man_MANS = waproamd.8 waproamd.conf.5
+
+noinst_DATA = waproamd.8.xml waproamd.conf.5.xml
+
+EXTRA_DIST = $(man_MANS) waproamd.8.xml.in waproamd.conf.5.xml.in man.css man.xsl
+
+CLEANFILES = waproamd.8.xml waproamd.conf.5.xml
+
+waproamd.8.xml: waproamd.8.xml.in Makefile
+	sed -e 's,@sysconfdir\@,$(sysconfdir),g' -e 's,@sbindir\@,$(sbindir),g' -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@
+
+waproamd.conf.5.xml: waproamd.conf.5.xml.in Makefile
+	sed -e 's,@sysconfdir\@,$(sysconfdir),g' -e 's,@sbindir\@,$(sbindir),g' -e 's,@PACKAGE_BUGREPORT\@,$(PACKAGE_BUGREPORT),g' -e 's,@PACKAGE_URL\@,$(PACKAGE_URL),g' $< > $@
+
+if USE_XMLTOMAN
+
+CLEANFILES += $(man_MANS)
+
+waproamd.conf.5: waproamd.conf.5.xml Makefile
+	xmltoman $< > $@
+
+waproamd.8: waproamd.8.xml Makefile
+	xmltoman $< > $@
+
+endif
diff --git a/man/waproamd.8.xml.in b/man/waproamd.8.xml.in
new file mode 100644
index 0000000..73ff3ea
--- /dev/null
+++ b/man/waproamd.8.xml.in
@@ -0,0 +1,203 @@
+<?xml version="1.0" standalone='no'?>
+<!DOCTYPE manpage SYSTEM "xmltoman.dtd">
+<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>
+
+<!-- $Id$ -->
+
+<!-- 
+  This file is part of waproamd.
+
+  waproamd is free software; you can redistribute it and/or modify it under
+  the terms of the GNU General Public License as published by the Free
+  Software Foundation; either version 2 of the License, or (at your
+  option) any later version.
+
+  waproamd is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+  for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with waproamd; if not, write to the Free Software Foundation,
+  Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 
+-->
+
+  <manpage name="waproamd" section="8" desc="Wireless Access Point Roaming Daemon for WLAN IEEE 802.11">
+
+	<synopsis>
+	  <cmd>waproamd [<arg>options</arg>]</cmd>
+	</synopsis>
+	
+	<description> <p>waproamd is a roaming daemon for wireless NICs
+	  supporting the Linux wireless extensions. It is intended to
+	  configure the WEP keys according to the networks found.</p>
+
+      <p>As long as the local NIC is not associated to any wireless
+      network waproamd scans iteratively for them. If one is detected,
+      a script in <file>@sysconfdir@/waproamd/scripts/</file> named
+      after the MAC address of the access point is called. If this
+      script is not existent,
+      <file>@sysconfdir@/waproamd/scripts/default</file> is called
+      instead. The first argument to this script is "start". If the
+      association is lost, the same script is run with the argument
+      "stop". While the NIC is associated no scans are issued.</p>
+
+      <p>waproamd is intended to be used together with
+      	ifplugd. Whenever an association succeeds, ifplugd detects it
+      	and runs further configuration commands for it.</p>
+
+      <p>If multiple WLANs are detected at the same time, the network
+	which is detected by the hardware first is selected. However,
+	networks where a matching script exists take precedence.</p>
+
+      <p>waproamd requires a network driver supporting the Linux
+	wireless extensions v15 or newer. The driver needs to support
+	scanning for wireless networks, which may be tested by running
+	"iwlist scan". If the driver supports the wireless event
+	subsystem, waproamd may use it to improve latency
+	behaviour. It is not required, however.</p>
+
+
+    </description>
+	
+	<options>
+	  
+	  <option>
+		<p><opt>-n | --no-daemon</opt></p>
+		<optdesc><p>
+			Do not daemonize (for debugging) (default: off)
+		  </p></optdesc>
+	  </option>
+	  
+	  <option>
+		<p><opt>-s | --no-syslog</opt></p>
+		<optdesc><p>
+			Do not use syslog, use stdout instead (for debugging) (default: off).
+		  </p></optdesc>
+	  </option>
+	  
+	  <option>
+		<p><opt>-i | --iface=</opt><arg>IFACE</arg></p>
+		<optdesc><p>
+			Specify the wireless network interface (default: wlan0)
+		  </p></optdesc>
+	  </option>
+	  
+	  <option>
+		<p><opt>-w | --wait-on-fork</opt></p> 
+
+		<optdesc><p> When daemonizing, wait until the background
+		process finished with the initial association detection.
+		</p></optdesc>
+	  </option>
+
+      <option> <p><opt>-M | --monitor</opt></p> <optdesc><p>Don't fail
+       when the network interface is not available, instead use
+       NETLINK to monitor device avaibility. The is useful for PCMCIA
+       devices and similar.</p></optdesc> </option>
+
+      <option> <p><opt>-e | --no-event</opt></p> <optdesc><p>Don't use
+       the wireless event API (as used by <manref name="iwevent"
+       section="8"/>), instead poll for association information. Some
+       network drivers do not support this relatively new feature of
+       the Linux wireless extension. Sadly the support of this feature
+       cannot be detected automatically.</p></optdesc> </option>
+
+      <option>
+       <p><opt>-t | --scan-interval=</opt><arg>SECS</arg></p>
+       <optdesc><p>Specify the time between scans for wireless networks.</p></optdesc>
+      </option>
+
+      <option>
+       <p><opt>-p | --poll-intervall=</opt><arg>SECS</arg></p>
+       <optdesc><p>When using -e, specify the time between association status polls.</p></optdesc>
+      </option>
+
+	  <option>
+		<p><opt>-h | --help</opt></p>
+		<optdesc><p>
+			Show help
+		  </p></optdesc>
+	  </option>
+	  
+	  <option>
+		<p><opt>-k | --kill</opt></p>
+		<optdesc><p>
+			Kill a running daemon (Specify -i to select the daemon instance to kill)
+		  </p></optdesc>
+	  </option>
+
+	  <option>
+		<p><opt>-c | --check-running</opt></p>
+		<optdesc><p>
+			Check if a daemon is running for a given network interface. Sets the return value to 0 if a daemon is already running or to 255 if not.
+		  </p></optdesc>
+	  </option>
+	  
+	  <option>
+		<p><opt>-v | --version</opt></p>
+		<optdesc><p>
+			Show version
+		  </p></optdesc>
+	  </option>
+	  
+	</options>
+	
+	<section name="Files">
+	  
+	  <p><file>@sysconfdir@/waproamd/waproamd.conf</file>: this file is sourced
+		by the init script <file>@sysconfdir@/init.d/waproamd</file> and
+		contains the interface to be monitored and the options to be
+		used.</p>
+
+      <p><file>@sysconfdir@/waproamd/scripts/&lt;AP MAC
+      address&gt;</file>: this is called whenever a wireless network
+      controlled by an AP with a matching address is detected. The MAC
+      address is formatted lowercase. Takes the same arguments as the
+      following script:</p>
+	  
+	  <p><file>@sysconfdir@/waproamd/scripts/default</file>: this is
+		the script which is called whenever no script named after the
+		AP MAC address is found. It takes a single argument: either
+		"start" or "stop". An environment variable AP is set to the
+		MAC address of the access point found. An environment variable
+		IFACE is set to the network interface name. The default
+		implementation of this script looks for a file
+		<file>@sysconfdir@/waproamd/keys/&lt;AP MAC
+		address&gt;.wep</file>. If it exists its contents is used to
+		set the WEP key of the NIC. Otherwise the script looks for a
+		file <file>@sysconfdir@/waproamd/keys/&lt;AP
+		MAC address&gt;.aes</file>. If it exists the AES WEP rekeying daemon
+		<manref name="aeswepd" section="8"/> is called. Otherwise WEP
+		encryption is disabled.</p>
+
+		
+	  <p><file>/var/run/waproamd.&lt;iface&gt;.pid</file>: the pid file
+	  for waproamd.</p>
+	  
+	</section>
+    <section name="Signals">
+      <p><arg>SIGINT, SIGTERM, SIGTQUIT</arg> waproamd will quit. This is issued by passing -k to waproamd.</p>
+      <p><arg>SIGHUP</arg> waproamd will rescan for available networks immediately.</p>
+    </section>
+
+	<section name="Author">
+	  <p>waproamd was written by Lennart Poettering
+		&lt;@PACKAGE_BUGREPORT@&gt;. waproamd is available
+		at <url
+		href="@PACKAGE_URL@"/>
+	  </p>
+	</section>
+	
+	<section name="See also">
+	  <p>
+		<manref name="ifplugd" section="8"/>, <manref name="aeswepd" section="8"/>, <manref name="iwconfig" section="8"/>, <manref name="iwlist" section="8"/>
+	  </p>
+	</section>
+	
+	<section name="Comments">
+	  <p>This man page was written using <manref name="xmltoman" section="1"
+		  href="http://masqmail.cx/xml2man/"/> by Oliver Kurth.</p>
+	</section>
+	
+  </manpage>
diff --git a/man/waproamd.conf.5.xml.in b/man/waproamd.conf.5.xml.in
new file mode 100644
index 0000000..91e629b
--- /dev/null
+++ b/man/waproamd.conf.5.xml.in
@@ -0,0 +1,78 @@
+<?xml version="1.0" standalone='no'?>
+<!DOCTYPE manpage SYSTEM "xmltoman.dtd">
+<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>
+
+<!-- $Id$ -->
+
+<!-- 
+  This file is part of waproamd.
+
+  waproamd is free software; you can redistribute it and/or modify it under
+  the terms of the GNU General Public License as published by the Free
+  Software Foundation; either version 2 of the License, or (at your
+  option) any later version.
+
+  waproamd is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+  for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with waproamd; if not, write to the Free Software Foundation,
+  Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 
+-->
+
+  <manpage name="waproamd.conf" section="5" desc="waproamd configuration file">
+
+	<synopsis>
+	  <cmd>@sysconfdir@/waproamd/waproamd.conf</cmd>
+	</synopsis>
+	
+	<description>
+	  <p>waproamd.conf is the configuration file for waproamd. It is a
+	  shell script that is sourced by the init script starting
+	  the daemon. It shall be used to set environment variables which
+	  are interpreted by the init script:</p>
+	</description>
+	
+	<options>
+
+	  <option>
+		<p><opt>INTERFACES</opt></p> <optdesc><p>Specifies the
+		wireless network interfaces to monitor. It has to contain a space
+		seperated list of network interfaces names. Most users will
+		probably use "wlan0" or "eth0" here, however you may add additional
+		interfaces for monitoring more than one device. A special
+		value is supported as well: "auto" will enable a more or less
+		working automatic detection of available network devices. This
+		won't make you happy when using network module auto loading,
+		since it cannot detect currently unloaded network
+		devices.</p></optdesc>
+	  </option>
+
+	  <option>
+		<p><opt>ARGS</opt></p> <optdesc><p>Additional command line
+		arguments for waproamd invocation. See <manref name="waproamd"
+		section="8"/> for further information.</p></optdesc>
+	  </option>
+
+
+	  <option>
+	       <p><opt>ARGS_</opt><arg>iface</arg></p>
+                  
+	       <optdesc><p>If specified for an interface this variable takes precedence over ARGS. This may be useful if more than one network device is present.</p></optdesc>
+	  </option>
+	</options>
+	
+	<section name="See also">
+	  <p>
+		<manref name="waproamd" section="8"/>
+	  </p>
+	</section>
+	
+	<section name="Comments">
+	  <p>This man page was written using <manref name="xmltoman" section="1"
+		  href="http://masqmail.cx/xml2man/"/> by Oliver Kurth.</p>
+	</section>
+	
+  </manpage>
diff --git a/man/xmltoman.css b/man/xmltoman.css
new file mode 100644
index 0000000..e96806b
--- /dev/null
+++ b/man/xmltoman.css
@@ -0,0 +1,30 @@
+/* $Id$ */
+
+/***
+  This file is part of waproamd.
+
+  waproamd is free software; you can redistribute it and/or modify it under
+  the terms of the GNU General Public License as published by the Free
+  Software Foundation; either version 2 of the License, or (at your
+  option) any later version.
+
+  waproamd is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+  for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with waproamd; if not, write to the Free Software Foundation,
+  Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 
+***/
+
+body { color: black; background-color: white; margin: 0.5cm; } 
+a:link, a:visited { color: #900000; }       
+h1 { text-transform:uppercase; font-size: 18pt; color: #00009F; }
+p { margin-left:1cm; margin-right:1cm; }
+.cmd { font-family:monospace; }
+.file { font-family:monospace; }
+.arg { text-transform:uppercase; font-family:monospace; font-style: italic; }
+.opt { font-family:monospace; font-weight: bold;  }
+.manref { font-family:monospace; }
+.option .optdesc { margin-left:2cm; }
diff --git a/man/xmltoman.xsl b/man/xmltoman.xsl
new file mode 100644
index 0000000..5e556f8
--- /dev/null
+++ b/man/xmltoman.xsl
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
+
+<!-- 
+  This file is part of waproamd.
+
+  waproamd is free software; you can redistribute it and/or modify it under
+  the terms of the GNU General Public License as published by the Free
+  Software Foundation; either version 2 of the License, or (at your
+  option) any later version.
+
+  waproamd is distributed in the hope that it will be useful, but WITHOUT
+  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+  for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with waproamd; if not, write to the Free Software Foundation,
+  Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 
+-->
+
+<xsl:template match="/manpage">
+    <xsl:text disable-output-escaping="yes">
+    &lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"&gt;
+    </xsl:text>
+    <html>
+
+    <head>
+      <title>
+        <xsl:value-of select="@name"/>(<xsl:value-of select="@section"/>) 
+      </title>
+      <link rel="stylesheet" type="text/css" href="xmltoman.css"/>
+    </head>
+    <body>
+      <h1>Name</h1>
+      <p><xsl:value-of select="@name"/>
+        <xsl:if test="string-length(@desc) &gt; 0">
+          - <xsl:value-of select="@desc"/>
+        </xsl:if>
+      </p>
+      <xsl:apply-templates />
+    </body>
+  </html>
+</xsl:template>
+
+<xsl:template match="p">
+ <p>
+  <xsl:apply-templates/>
+ </p>
+</xsl:template>
+
+<xsl:template match="cmd">
+ <p class="cmd">
+  <xsl:apply-templates/>
+ </p>
+</xsl:template>
+
+<xsl:template match="arg">
+  <span class="arg"><xsl:apply-templates/></span>
+</xsl:template>
+
+<xsl:template match="opt">
+  <span class="opt"><xsl:apply-templates/></span>
+</xsl:template>
+
+<xsl:template match="file">
+  <span class="file"><xsl:apply-templates/></span>
+</xsl:template>
+
+<xsl:template match="optdesc">
+  <div class="optdesc">
+    <xsl:apply-templates/>
+  </div>
+</xsl:template>
+
+<xsl:template match="synopsis">
+  <h1>Synopsis</h1>
+  <xsl:apply-templates/>
+</xsl:template>
+
+<xsl:template match="seealso">
+  <h1>Synopsis</h1>
+  <xsl:apply-templates/>
+</xsl:template>
+
+<xsl:template match="description">
+  <h1>Description</h1>
+  <xsl:apply-templates/>
+</xsl:template>
+
+<xsl:template match="options">
+  <h1>Options</h1>
+  <xsl:apply-templates/>
+</xsl:template>
+
+<xsl:template match="section">
+  <h1><xsl:value-of select="@name"/></h1>
+  <xsl:apply-templates/>
+</xsl:template>
+
+<xsl:template match="option">
+  <div class="option"><xsl:apply-templates/></div>
+</xsl:template>
+
+<xsl:template match="manref">
+  <xsl:choose>
+    <xsl:when test="string-length(@href) &gt; 0">
+    <a class="manref"><xsl:attribute name="href"><xsl:value-of select="@href"/></xsl:attribute><xsl:value-of select="@name"/>(<xsl:value-of select="@section"/>)</a>
+    </xsl:when>
+    <xsl:otherwise>
+    <span class="manref"><xsl:value-of select="@name"/>(<xsl:value-of select="@section"/>)</span>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+<xsl:template match="url">
+  <a class="url"><xsl:attribute name="href"><xsl:value-of select="@href"/></xsl:attribute><xsl:value-of select="@href"/></a>
+</xsl:template>
+
+</xsl:stylesheet>