=== modified file 'TODO'
--- TODO	2008-09-02 15:02:37 +0000
+++ TODO	2008-09-02 17:42:53 +0000
@@ -9,8 +9,6 @@
 
 * password-request
 ** [#A] Man page: man8/password-request.8mandos
-*** SYNOPSIS
-    Document short options
 *** DESCRIPTION
     State that this command is not meant to be invoked directly, but
     is run as a plugin from mandos-client(8) and only run in the

=== modified file 'mandos-options.xml'
--- mandos-options.xml	2008-08-30 18:45:41 +0000
+++ mandos-options.xml	2008-09-02 17:42:53 +0000
@@ -5,6 +5,8 @@
 <!--
 This file is used by both mandos(8) and mandos.conf(5), since these
 options can be used both on the command line and in the config file.
+
+It is also used for some texts by password-request(8mandos).
 -->
 
 <section>

=== modified file 'mandos.xml'
--- mandos.xml	2008-09-01 08:29:23 +0000
+++ mandos.xml	2008-09-02 17:42:53 +0000
@@ -3,7 +3,7 @@
 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 <!ENTITY VERSION "1.0">
 <!ENTITY COMMANDNAME "mandos">
-<!ENTITY TIMESTAMP "2008-09-01">
+<!ENTITY TIMESTAMP "2008-09-02">
 ]>
 
 <refentry xmlns:xi="http://www.w3.org/2001/XInclude">
@@ -115,24 +115,20 @@
       Any authenticated client is then given the stored pre-encrypted
       password for that specific client.
     </para>
-
   </refsect1>
   
   <refsect1 id="purpose">
     <title>PURPOSE</title>
-
     <para>
       The purpose of this is to enable <emphasis>remote and unattended
       rebooting</emphasis> of client host computer with an
       <emphasis>encrypted root file system</emphasis>.  See <xref
       linkend="overview"/> for details.
     </para>
-    
   </refsect1>
   
   <refsect1 id="options">
     <title>OPTIONS</title>
-    
     <variablelist>
       <varlistentry>
 	<term><option>--help</option></term>

=== modified file 'plugins.d/password-request.c'
--- plugins.d/password-request.c	2008-08-24 10:49:09 +0000
+++ plugins.d/password-request.c	2008-09-02 17:42:53 +0000
@@ -774,7 +774,8 @@
     const char *pubkeyname = "pubkey.txt";
     const char *seckeyname = "seckey.txt";
     mandos_context mc = { .simple_poll = NULL, .server = NULL,
-			  .dh_bits = 1024, .priority = "SECURE256"};
+			  .dh_bits = 1024, .priority = "SECURE256"
+			  ":!CTYPE-X.509:+CTYPE-OPENPGP" };
     bool gnutls_initalized = false;
     
     {
@@ -817,25 +818,25 @@
 	/* Get the INPUT argument from `argp_parse', which we know is
 	   a pointer to our plugin list pointer. */
 	switch (key) {
-	case 128:
+	case 128:		/* --debug */
 	  debug = true;
 	  break;
-	case 'c':
+	case 'c':		/* --connect */
 	  connect_to = arg;
 	  break;
-	case 'i':
+	case 'i':		/* --interface */
 	  interface = arg;
 	  break;
-	case 'd':
+	case 'd':		/* --keydir */
 	  keydir = arg;
 	  break;
-	case 's':
+	case 's':		/* --seckey */
 	  seckeyname = arg;
 	  break;
-	case 'p':
+	case 'p':		/* --pubkey */
 	  pubkeyname = arg;
 	  break;
-	case 129:
+	case 129:		/* --dh-bits */
 	  errno = 0;
 	  mc.dh_bits = (unsigned int) strtol(arg, NULL, 10);
 	  if (errno){
@@ -843,7 +844,7 @@
 	    exit(EXIT_FAILURE);
 	  }
 	  break;
-	case 130:
+	case 130:		/* --priority */
 	  mc.priority = arg;
 	  break;
 	case ARGP_KEY_ARG:

=== modified file 'plugins.d/password-request.xml'
--- plugins.d/password-request.xml	2008-08-31 15:06:39 +0000
+++ plugins.d/password-request.xml	2008-09-02 17:42:53 +0000
@@ -3,7 +3,7 @@
 	"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
 <!ENTITY VERSION "1.0">
 <!ENTITY COMMANDNAME "password-request">
-<!ENTITY TIMESTAMP "2008-08-31">
+<!ENTITY TIMESTAMP "2008-09-02">
 ]>
 
 <refentry xmlns:xi="http://www.w3.org/2001/XInclude">
@@ -124,21 +124,67 @@
   <refsect1 id="description">
     <title>DESCRIPTION</title>
     <para>
-      <command>&COMMANDNAME;</command> is a mandos plugin that works
-      like a client program that through avahi detects mandos servers,
-      sets up a gnutls connect and request a encrypted password. Any
-      passwords given is automaticly decrypted and passed to
-      cryptsetup.
+      <command>&COMMANDNAME;</command> is a client program that
+      communicates with <citerefentry><refentrytitle
+      >mandos</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      to get a password.  It uses IPv6 link-local addresses to get
+      network connectivity, Zeroconf to find the server, and TLS with
+      an OpenPGP key to ensure authenticity and confidentiality.  It
+      keeps running, trying all servers on the network, until it
+      receives a satisfactory reply.
+    </para>
+    <para>
+      This program is not meant to be run directly; it is really meant
+      to run as a plugin of the <application>Mandos</application>
+      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
+      <manvolnum>8mandos</manvolnum></citerefentry>, which in turn
+      runs as a <quote>keyscript</quote> specified in the
+      <citerefentry><refentrytitle>crypttab</refentrytitle>
+      <manvolnum>5</manvolnum></citerefentry> file.
+    </para>
+  </refsect1>
+  
+  <refsect1 id="purpose">
+    <title>PURPOSE</title>
+    <para>
+      The purpose of this is to enable <emphasis>remote and unattended
+      rebooting</emphasis> of client host computer with an
+      <emphasis>encrypted root file system</emphasis>.  See <xref
+      linkend="overview"/> for details.
+    </para>
+  </refsect1>
+  
+  <refsect1 id="overview">
+    <title>OVERVIEW</title>
+    <xi:include href="overview.xml"/>
+    <para>
+      This program is the client part.  It is a plugin started by
+      <citerefentry><refentrytitle>plugin-runner</refentrytitle>
+      <manvolnum>8mandos</manvolnum></citerefentry> which will run in
+      an initial <acronym>RAM</acronym> disk environment.
+    </para>
+    <para>
+      This program could, theoretically, be used as a keyscript in
+      <filename>/etc/crypttab</filename>, but it would then be
+      impossible to enter the encrypted root disk password at the
+      console, since this program does not read from the console at
+      all.  This is why a separate plugin does that, which will be run
+      in parallell to this one.
     </para>
   </refsect1>
   
   <refsect1 id="options">
     <title>OPTIONS</title>
     <para>
-      Commonly not invoked as command lines but from configuration
-      file of plugin runner.
+      This program is commonly not invoked from the command line; it
+      is normally started by the <application>Mandos</application>
+      plugin runner, see <citerefentry><refentrytitle
+      >plugin-runner</refentrytitle><manvolnum>8mandos</manvolnum>
+      </citerefentry>.  Any command line options this program accepts
+      are therefore normally provided by the plugin runner, and not
+      directly.
     </para>
-
+    
     <variablelist>
       <varlistentry>
 	<term><option>--connect=<replaceable
@@ -149,11 +195,18 @@
 	><replaceable>PORT</replaceable></option></term>
 	<listitem>
 	  <para>
-	    Connect directly to a specified mandos server
+	    Do not use Zeroconf to locate servers.  Connect directly
+	    to only one specified <application>Mandos</application>
+	    server.  Note that an IPv6 address has colon characters in
+	    it, so the <emphasis>last</emphasis> colon character is
+	    assumed to separate the address from the port number.
+	  </para>
+	  <para>
+	    This option is normally only useful for debugging.
 	  </para>
 	</listitem>
       </varlistentry>
-
+      
       <varlistentry>
 	<term><option>--keydir=<replaceable
 	>DIRECTORY</replaceable></option></term>
@@ -161,7 +214,11 @@
 	<replaceable>DIRECTORY</replaceable></option></term>
 	<listitem>
 	  <para>
-	    Directory where the openpgp keyring is
+	    Directory to read the OpenPGP key files
+	    <filename>pubkey.txt</filename> and
+	    <filename>seckey.txt</filename> from.  The default is
+	    <filename>/conf/conf.d/mandos</filename> (in the initial
+	    <acronym>RAM</acronym> disk environment).
 	  </para>
 	</listitem>
       </varlistentry>
@@ -173,11 +230,13 @@
 	<replaceable>NAME</replaceable></option></term>
 	<listitem>
 	  <para>
-	    Interface that Avahi will connect through
+	    Network interface that will be brought up and scanned for
+	    Mandos servers to connect to.  The default it
+	    <quote><literal>eth0</literal></quote>.
 	  </para>
 	</listitem>
       </varlistentry>
-
+      
       <varlistentry>
 	<term><option>--pubkey=<replaceable
 	>FILE</replaceable></option></term>
@@ -185,7 +244,10 @@
 	<replaceable>FILE</replaceable></option></term>
 	<listitem>
 	  <para>
-	    Public openpgp key for gnutls authentication
+	    OpenPGP public key file name.  This will be combined with
+	    the directory from the <option>--keydir</option> option to
+	    form an absolute file name.  The default name is
+	    <quote><literal>pubkey.txt</literal></quote>.
 	  </para>
 	</listitem>
       </varlistentry>
@@ -197,7 +259,10 @@
 	<replaceable>FILE</replaceable></option></term>
 	<listitem>
 	  <para>
-	    Secret OpenPGP key for GnuTLS authentication
+	    OpenPGP secret key file name.  This will be combined with
+	    the directory from the <option>--keydir</option> option to
+	    form an absolute file name.  The default name is
+	    <quote><literal>seckey.txt</literal></quote>.
 	  </para>
 	</listitem>
       </varlistentry>
@@ -206,9 +271,7 @@
 	<term><option>--priority=<replaceable
 	>STRING</replaceable></option></term>
 	<listitem>
-	  <para>
-	    GnuTLS priority
-	  </para>
+	  <xi:include href="mandos-options.xml" xpointer="priority"/>
 	</listitem>
       </varlistentry>
 
@@ -217,7 +280,8 @@
 	>BITS</replaceable></option></term>
 	<listitem>
 	  <para>
-	    DH bits to use in gnutls communication
+	    Sets the number of bits to use for the prime number in the
+	    TLS Diffie-Hellman key exchange.  Default is 1024.
 	  </para>
 	</listitem>
       </varlistentry>
@@ -226,7 +290,14 @@
 	<term><option>--debug</option></term>
 	<listitem>
 	  <para>
-	    Debug mode
+	    Enable debug mode.  This will enable a lot of output to
+	    standard error about what the program is doing.  The
+	    program will still perform all other functions normally.
+	  </para>
+	  <para>
+	    It will also enable debug mode in the Avahi and GnuTLS
+	    libraries, making them print large amounts of debugging
+	    output.
 	  </para>
 	</listitem>
       </varlistentry>
@@ -236,7 +307,7 @@
 	<term><option>-?</option></term>
 	<listitem>
 	  <para>
-	    Gives a help message
+	    Gives a help message about options and their meanings.
 	  </para>
 	</listitem>
       </varlistentry>
@@ -245,7 +316,7 @@
 	<term><option>--usage</option></term>
 	<listitem>
 	  <para>
-	    Gives a short usage message
+	    Gives a short usage message.
 	  </para>
 	</listitem>
       </varlistentry>
@@ -255,7 +326,7 @@
 	<term><option>-V</option></term>
 	<listitem>
 	  <para>
-	    Prints the program version
+	    Prints the program version.
 	  </para>
 	</listitem>
       </varlistentry>
@@ -265,15 +336,23 @@
   <refsect1 id="exit_status">
     <title>EXIT STATUS</title>
     <para>
-    </para>
-  </refsect1>
-
-  <refsect1 id="environment">
-    <title>ENVIRONMENT</title>
-    <para>
-    </para>
-  </refsect1>
-
+      This program will exit with a successful (zero) exit status if a
+      server could be found and the password received from it could be
+      successfully decrypted and output on standard output.  The
+      program will exit with a non-zero exit status only if a critical
+      error occurs.  Otherwise, it will forever connect to new
+      <application>Mandosservers</application> servers as they appear,
+      trying to get a decryptable password.
+    </para>
+  </refsect1>
+  
+<!--   <refsect1 id="environment"> -->
+<!--     <title>ENVIRONMENT</title> -->
+<!--     <para> -->
+<!--       This program does not use any environment variables. -->
+<!--     </para> -->
+<!--   </refsect1> -->
+  
   <refsect1 id="file">
     <title>FILES</title>
     <para>