* Update manual pages.

* sbuild/sbuild-lock.h: Add missing virtual specifier from virtual
  methods in derived lock classes.
* sbuild/sbuild-session.cc: Remove use of excess braces when
  throwing exceptions.
  (get_shell): Use log_exception_warning.
* Remove incorrect and misplaced comments.
* Update translator comments.
* Update API reference to document all missing and incomplete
  documentation.

52 files changed, 404 insertions, 170 deletions

diff --git a/ChangeLog b/ChangeLog
index 7b8c8b38..276d6416 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,21 @@
+2006-07-29  Roger Leigh  <rleigh@debian.org>
+
+	* Update manual pages.
+
+	* sbuild/sbuild-lock.h: Add missing virtual specifier from virtual
+	methods in derived lock classes.
+
+	* sbuild/sbuild-session.cc: Remove use of excess braces when
+	throwing exceptions.
+	(get_shell): Use log_exception_warning.
+
+	* Remove incorrect and misplaced comments.
+
+	* Update translator comments.
+
+	* Update API reference to document all missing and incomplete
+	documentation.
+
 2006-07-28  Roger Leigh  <rleigh@debian.org>
 
 	* NEWS: Update for 1.0.0.
diff --git a/HACKING b/HACKING
index 34cfe9a8..b2513e75 100644
--- a/HACKING
+++ b/HACKING
@@ -5,6 +5,37 @@ This document is a short guide to the conventions used in the schroot
 project.
 
 
+Coding
+------
+
+The style should be apparent from the source.  It is the default Emacs
+c++-mode style, with paired brackets aligned vertically.
+
+* Use 0 rather than NULL.
+* Use C++ casts rather than C-style casts.
+* Don't use void * unless there is no alternative.
+* Add doxygen comments for everything; use EXTRACT_ALL = NO in
+  doc/schroot.dox to check for missing or incomplete documentation.
+
+
+Format strings
+--------------
+
+The sources use boost::format for type-safe formatted output.  Make
+sure that the maximum number of options passed is the same as the
+highest %n% in the format string.
+
+The following styles are used
+
+  Style                  Formatting                Syntax
+  --------------------------------------------------------------------
+  Values                 Single quotes             '
+  Example text           Double quotes             \"
+  User input             Double quotes             \"
+
+These are transformed into proper UTF-8 quotes with gettext.
+
+
 Documentation
 -------------
 
@@ -32,24 +63,6 @@ The following styles are used:
   Verbatim user input    Courier bold              \f[CB]
 
 
-Format strings
---------------
-
-The sources use boost::format for type-safe formatted output.  Make
-sure that the maximum number of options passed is the same as the
-highest %n% in the format string.
-
-The following styles are used
-
-  Style                  Formatting                Syntax
-  --------------------------------------------------------------------
-  Values                 Single quotes             '
-  Example text           Double quotes             \"
-  User input             Double quotes             \"
-
-These are transformed into proper UTF-8 quotes with gettext.
-
-
 Releasing
 ---------
 
diff --git a/README b/README
index 71fcb32b..fcf4a278 100644
--- a/README
+++ b/README
@@ -3,12 +3,13 @@ schroot
 
 Securely enter a chroot and run a command or login shell.
 
-Note that giving untrusted users root access to chroots is a bad idea.
-Although they will only have root access to files inside the chroot,
-in practice there are many obvious ways of breaking out of the chroot
-or disrupting services on the host system.  As always, this boils down
-to trust.  Don't give root access to chroots to users you would not
-trust with root access to the host system.
+Note that giving untrusted users root access to chroots is a serious
+security risk!.  Although the untrusted user will only have root
+access to files inside the chroot, in practice there are many obvious
+ways of breaking out of the chroot and of disrupting services on the
+host system.  As always, this boils down to trust.  Don't give chroot
+root access to users you would not trust with root access to the host
+system.
 
 For compatibility with existing tools and scripts, wrapper binaries
 for dchroot and DSA dchroot are provided.
diff --git a/dchroot-dsa/dchroot-dsa-main.cc b/dchroot-dsa/dchroot-dsa-main.cc
index 2faa180b..5a8d4157 100644
--- a/dchroot-dsa/dchroot-dsa-main.cc
+++ b/dchroot-dsa/dchroot-dsa-main.cc
@@ -40,7 +40,8 @@ using namespace dchroot_dsa;
 
 main::main (schroot::options_base::ptr& options):
   main_base("dchroot-dsa",
-	    // TRANSLATORS: Please use an ellipsis e.g. U+2026
+	    // TRANSLATORS: '...' is an ellipsis e.g. U+2026, and '-'
+	    // is an em-dash.
 	    N_("[OPTION...] chroot [COMMAND] - run command or shell in a chroot"),
 	    options)
 {
diff --git a/dchroot-dsa/dchroot-dsa.1.in b/dchroot-dsa/dchroot-dsa.1.in
index 52aebed9..11ddbcea 100644
--- a/dchroot-dsa/dchroot-dsa.1.in
+++ b/dchroot-dsa/dchroot-dsa.1.in
@@ -16,7 +16,7 @@
 .\" MA  02111-1307  USA
 .TH DCHROOT-DSA 1 "@RELEASE_DATE@" "Version @VERSION@" "Debian sbuild"
 .SH NAME
-dchroot\-dsa \- enter a chroot environment
+dchroot\-dsa \[em] enter a chroot environment
 .SH SYNOPSIS
 .B dchroot\-dsa
 .RB [ \-h \[or] \-\-help " \[or] " \-V \[or] \-\-version
diff --git a/dchroot/dchroot-main-base.h b/dchroot/dchroot-main-base.h
index 504d8d56..fca92bdc 100644
--- a/dchroot/dchroot-main-base.h
+++ b/dchroot/dchroot-main-base.h
@@ -47,6 +47,10 @@ namespace dchroot
     virtual ~main_base ();
 
   protected:
+    /**
+     * Check dchroot.conf exists.  If it exists, and using verbose
+     * messages, print a warning about upgrading to schroot.conf.
+     */
     void
     check_dchroot_conf();
 
@@ -59,6 +63,7 @@ namespace dchroot
     virtual void
     action_list ();
 
+    /// Use dchroot.conf as the configuration file.
     bool use_dchroot_conf;
   };
 
diff --git a/dchroot/dchroot-main.cc b/dchroot/dchroot-main.cc
index 05a48297..6dcf261c 100644
--- a/dchroot/dchroot-main.cc
+++ b/dchroot/dchroot-main.cc
@@ -41,7 +41,8 @@ using namespace dchroot;
 
 main::main (schroot::options_base::ptr& options):
   main_base("dchroot",
-	    // TRANSLATORS: Please use an ellipsis e.g. U+2026
+	    // TRANSLATORS: '...' is an ellipsis e.g. U+2026, and '-'
+	    // is an em-dash.
 	    N_("[OPTION...] [COMMAND] - run command or shell in a chroot"),
 	    options)
 {
diff --git a/dchroot/dchroot.1.in b/dchroot/dchroot.1.in
index 0f1a06c3..38b7b1c8 100644
--- a/dchroot/dchroot.1.in
+++ b/dchroot/dchroot.1.in
@@ -16,7 +16,7 @@
 .\" MA  02111-1307  USA
 .TH DCHROOT 1 "@RELEASE_DATE@" "Version @VERSION@" "Debian sbuild"
 .SH NAME
-dchroot \- enter a chroot environment
+dchroot \[em] enter a chroot environment
 .SH SYNOPSIS
 .B dchroot
 .RB [ \-h \[or] \-\-help " \[or] " \-V \[or] \-\-version
diff --git a/doc/schroot.dox.in b/doc/schroot.dox.in
index ab2990f8..6c798e6f 100644
--- a/doc/schroot.dox.in
+++ b/doc/schroot.dox.in
@@ -802,7 +802,7 @@ PDF_HYPERLINKS         = NO
 # plain latex in the generated Makefile. Set this option to YES to get a 
 # higher quality PDF documentation.
 
-USE_PDFLATEX           = NO
+USE_PDFLATEX           = YES
 
 # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode. 
 # command to the generated LaTeX files. This will instruct LaTeX to keep 
@@ -1160,7 +1160,7 @@ CALL_GRAPH             = YES
 # So in most cases it will be better to enable caller graphs for selected 
 # functions only using the \callergraph command.
 
-CALLER_GRAPH           = NO
+CALLER_GRAPH           = YES
 
 # If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen 
 # will graphical hierarchy of all classes instead of a textual one.
diff --git a/sbuild/sbuild-auth-conv-tty.cc b/sbuild/sbuild-auth-conv-tty.cc
index e714b28c..e7110e2d 100644
--- a/sbuild/sbuild-auth-conv-tty.cc
+++ b/sbuild/sbuild-auth-conv-tty.cc
@@ -275,7 +275,7 @@ auth_conv_tty::read_string (std::string message,
 }
 
 void
-auth_conv_tty::conversation (message_list& messages)
+auth_conv_tty::conversation (auth_conv::message_list& messages)
 {
   log_debug(DEBUG_NOTICE) << "PAM TTY conversation handler started" << endl;
 
diff --git a/sbuild/sbuild-auth-conv-tty.h b/sbuild/sbuild-auth-conv-tty.h
index 0c15eb7d..209f0b5a 100644
--- a/sbuild/sbuild-auth-conv-tty.h
+++ b/sbuild/sbuild-auth-conv-tty.h
@@ -74,7 +74,7 @@ namespace sbuild
     set_fatal_timeout (time_t timeout);
 
     virtual void
-    conversation (message_list& messages);
+    conversation (auth_conv::message_list& messages);
 
   private:
     /**
diff --git a/sbuild/sbuild-auth-conv.h b/sbuild/sbuild-auth-conv.h
index 6ebf89e2..b4719591 100644
--- a/sbuild/sbuild-auth-conv.h
+++ b/sbuild/sbuild-auth-conv.h
@@ -31,7 +31,7 @@ namespace sbuild
 {
 
   /**
-   * @brief Authentication conversation handler interface.
+   * Authentication conversation handler interface.
    *
    * This interface should be implemented by objects which handle
    * interaction with the user during authentication.
@@ -61,7 +61,7 @@ namespace sbuild
     virtual ~auth_conv ();
 
     /**
-     * @brief Get the time at which the user will be warned.
+     * Get the time at which the user will be warned.
      *
      * @returns the time.
      */
@@ -69,7 +69,7 @@ namespace sbuild
     get_warning_timeout () = 0;
 
     /**
-     * @brief Set the time at which the user will be warned.
+     * Set the time at which the user will be warned.
      *
      * @param timeout the time to set.
      */
@@ -77,8 +77,8 @@ namespace sbuild
     set_warning_timeout (time_t timeout) = 0;
 
     /**
-     * @brief Get the time at which the conversation will be
-     * terminated with an error.
+     * Get the time at which the conversation will be terminated with
+     * an error.
      *
      * @returns the time.
      */
@@ -86,8 +86,8 @@ namespace sbuild
     get_fatal_timeout () = 0;
 
     /**
-     * @brief Set the time at which the conversation will be
-     * terminated with an error.
+     * Set the time at which the conversation will be terminated with
+     * an error.
      *
      * @param timeout the time to set.
      */
@@ -95,7 +95,7 @@ namespace sbuild
     set_fatal_timeout (time_t timeout) = 0;
 
     /**
-     * @brief Hold a conversation with the user.
+     * Hold a conversation with the user.
      *
      * Each of the messages detailed in messages should be displayed
      * to the user, asking for input where required.  The type of
diff --git a/sbuild/sbuild-auth.h b/sbuild/sbuild-auth.h
index 98f075ad..eac01905 100644
--- a/sbuild/sbuild-auth.h
+++ b/sbuild/sbuild-auth.h
@@ -40,7 +40,7 @@ namespace sbuild
 {
 
   /**
-   * @brief Authentication handler.
+   * Authentication handler.
    *
    * auth handles user authentication, authorisation and session
    * management using the Pluggable authentication Modules (PAM)
@@ -68,7 +68,7 @@ namespace sbuild
    * The run method will handle all this.  The run_impl virtual
    * function should be used to provide a session handler to open and
    * close the session for the user.  open_session and close_session
-   * must still be used.
+   * must still be called.
    */
   class auth
   {
diff --git a/sbuild/sbuild-chroot-block-device.cc b/sbuild/sbuild-chroot-block-device.cc
index 7ec6d578..0859305a 100644
--- a/sbuild/sbuild-chroot-block-device.cc
+++ b/sbuild/sbuild-chroot-block-device.cc
@@ -119,13 +119,13 @@ chroot_block_device::setup_env (environment& env)
 }
 
 void
-chroot_block_device::setup_lock (setup_type type,
-				 bool       lock,
-				 int        status)
+chroot_block_device::setup_lock (chroot::setup_type type,
+				 bool               lock,
+				 int                status)
 {
   struct stat statbuf;
 
-  /* Only lock during setup, not run. */
+  /* Only lock during setup, not exec. */
   if (type == EXEC_START || type == EXEC_STOP)
     return;
 
diff --git a/sbuild/sbuild-chroot-block-device.h b/sbuild/sbuild-chroot-block-device.h
index 2dc3f5be..bb0885de 100644
--- a/sbuild/sbuild-chroot-block-device.h
+++ b/sbuild/sbuild-chroot-block-device.h
@@ -26,8 +26,9 @@ namespace sbuild
 {
 
   /**
-   * A chroot stored on an unmounted block device.  The device will be
-   * mounted on demand.
+   * A chroot stored on an unmounted block device.
+   *
+   * The device will be mounted on demand.
    */
   class chroot_block_device : virtual public chroot
   {
@@ -111,9 +112,9 @@ namespace sbuild
 
   protected:
     virtual void
-    setup_lock (setup_type type,
-		bool       lock,
-		int        status);
+    setup_lock (chroot::setup_type type,
+		bool               lock,
+		int                status);
 
     virtual void
     get_details (format_detail& detail) const;
diff --git a/sbuild/sbuild-chroot-directory.cc b/sbuild/sbuild-chroot-directory.cc
index f5eab287..c7750f51 100644
--- a/sbuild/sbuild-chroot-directory.cc
+++ b/sbuild/sbuild-chroot-directory.cc
@@ -82,9 +82,9 @@ chroot_directory::get_chroot_type () const
 }
 
 void
-chroot_directory::setup_lock (setup_type type,
-			      bool       lock,
-			      int        status)
+chroot_directory::setup_lock (chroot::setup_type type,
+			      bool               lock,
+			      int                status)
 {
   /* By default, directory chroots do no locking. */
   /* Create or unlink session information. */
diff --git a/sbuild/sbuild-chroot-directory.h b/sbuild/sbuild-chroot-directory.h
index b47469e3..50ac9094 100644
--- a/sbuild/sbuild-chroot-directory.h
+++ b/sbuild/sbuild-chroot-directory.h
@@ -26,7 +26,7 @@ namespace sbuild
 {
 
   /**
-   * A chroot located on a mounted filesystem.
+   * A chroot located in the filesystem.
    */
   class chroot_directory : virtual public chroot
   {
@@ -70,9 +70,9 @@ namespace sbuild
 
   protected:
     virtual void
-    setup_lock (setup_type type,
-		bool       lock,
-		int        status);
+    setup_lock (chroot::setup_type type,
+		bool               lock,
+		int                status);
 
     virtual void
     get_details (format_detail& detail) const;
diff --git a/sbuild/sbuild-chroot-file.cc b/sbuild/sbuild-chroot-file.cc
index f56dc816..11a71a44 100644
--- a/sbuild/sbuild-chroot-file.cc
+++ b/sbuild/sbuild-chroot-file.cc
@@ -114,9 +114,9 @@ chroot_file::setup_env (environment& env)
 }
 
 void
-chroot_file::setup_lock (setup_type type,
-			 bool       lock,
-			 int        status)
+chroot_file::setup_lock (chroot::setup_type type,
+			 bool               lock,
+			 int                status)
 {
   // Check ownership and permissions.
   if (type == SETUP_START && lock == true)
diff --git a/sbuild/sbuild-chroot-file.h b/sbuild/sbuild-chroot-file.h
index 1127fe38..a1d830f6 100644
--- a/sbuild/sbuild-chroot-file.h
+++ b/sbuild/sbuild-chroot-file.h
@@ -95,9 +95,9 @@ namespace sbuild
 
   protected:
     virtual void
-    setup_lock (setup_type type,
-		bool       lock,
-		int        status);
+    setup_lock (chroot::setup_type type,
+		bool               lock,
+		int                status);
 
     virtual void
     get_details (format_detail& detail) const;
diff --git a/sbuild/sbuild-chroot-lvm-snapshot.cc b/sbuild/sbuild-chroot-lvm-snapshot.cc
index 76c51792..38a279bb 100644
--- a/sbuild/sbuild-chroot-lvm-snapshot.cc
+++ b/sbuild/sbuild-chroot-lvm-snapshot.cc
@@ -120,9 +120,9 @@ chroot_lvm_snapshot::setup_env (environment& env)
 }
 
 void
-chroot_lvm_snapshot::setup_lock (setup_type type,
-				 bool       lock,
-				 int        status)
+chroot_lvm_snapshot::setup_lock (chroot::setup_type type,
+				 bool               lock,
+				 int                status)
 {
   std::string device;
   struct stat statbuf;
diff --git a/sbuild/sbuild-chroot-lvm-snapshot.h b/sbuild/sbuild-chroot-lvm-snapshot.h
index dc48b136..8dce0da9 100644
--- a/sbuild/sbuild-chroot-lvm-snapshot.h
+++ b/sbuild/sbuild-chroot-lvm-snapshot.h
@@ -27,8 +27,9 @@ namespace sbuild
 {
 
   /**
-   * A chroot stored on an LVM logical volume (LV).  A snapshot LV
-   * will be created and mounted on demand.
+   * A chroot stored on an LVM logical volume (LV).
+   *
+   * A snapshot LV will be created and mounted on demand.
    */
   class chroot_lvm_snapshot : public chroot_block_device,
 			      public chroot_source
@@ -99,9 +100,9 @@ namespace sbuild
 
   protected:
     virtual void
-    setup_lock (setup_type type,
-		bool       lock,
-		int        status);
+    setup_lock (chroot::setup_type type,
+		bool               lock,
+		int                status);
 
     virtual void
     get_details (format_detail& detail) const;
diff --git a/sbuild/sbuild-chroot-plain.h b/sbuild/sbuild-chroot-plain.h
index ea958b86..b166d3eb 100644
--- a/sbuild/sbuild-chroot-plain.h
+++ b/sbuild/sbuild-chroot-plain.h
@@ -26,7 +26,7 @@ namespace sbuild
 {
 
   /**
-   * A chroot located on a mounted filesystem (mounts disabled).
+   * A chroot located in the filesystem (mounts disabled).
    */
   class chroot_plain : public chroot_directory
   {
diff --git a/sbuild/sbuild-chroot-source.h b/sbuild/sbuild-chroot-source.h
index 1b187859..f416dde3 100644
--- a/sbuild/sbuild-chroot-source.h
+++ b/sbuild/sbuild-chroot-source.h
@@ -52,6 +52,11 @@ namespace sbuild
     /// The destructor.
     virtual ~chroot_source ();
 
+    /**
+     * Create a source chroot.
+     *
+     * @returns a source chroot.
+     */
     virtual chroot::ptr
     clone_source () const = 0;
 
diff --git a/sbuild/sbuild-chroot.h b/sbuild/sbuild-chroot.h
index 06810e62..979f120b 100644
--- a/sbuild/sbuild-chroot.h
+++ b/sbuild/sbuild-chroot.h
@@ -177,7 +177,7 @@ namespace sbuild
      * of the chroot, and is typically the same as the mount location,
      * but is overridden by the chroot type if required.
      *
-     * @returns the mount location.
+     * @param location the mount location.
      */
     virtual void
     set_location (std::string const& location);
diff --git a/sbuild/sbuild-custom-error.h b/sbuild/sbuild-custom-error.h
index fe3c161e..21837d2b 100644
--- a/sbuild/sbuild-custom-error.h
+++ b/sbuild/sbuild-custom-error.h
@@ -33,6 +33,7 @@ namespace sbuild
   class custom_error : public error<T>
   {
   public:
+    /// The enum type providing the error codes for this type.
     typedef typename error<T>::error_type error_type;
 
     /**
diff --git a/sbuild/sbuild-dirstream.cc b/sbuild/sbuild-dirstream.cc
index 5f8c4759..ecff919b 100644
--- a/sbuild/sbuild-dirstream.cc
+++ b/sbuild/sbuild-dirstream.cc
@@ -115,14 +115,12 @@ dirstream::read(int quantity)
     }
 }
 
-// close the directory
-// this also clears all the direntry data
 void
 dirstream::close()
 {
   if (this->dir)
-    closedir(this->dir); // don't throw an exception on failure -- it could
-		   // be called in the destructor
+    closedir(this->dir); // don't throw an exception on failure -- it
+			 // could be called in the destructor
   this->dir = 0;
   this->data.clear();    // clear all data
   this->dirname.clear();
diff --git a/sbuild/sbuild-dirstream.h b/sbuild/sbuild-dirstream.h
index ea346857..cfe84af8 100644
--- a/sbuild/sbuild-dirstream.h
+++ b/sbuild/sbuild-dirstream.h
@@ -34,14 +34,9 @@ namespace sbuild
 
   /**
    * An entry in a dirstream.  It is a wrapper around the dirent
-   * structure declared in dirent.h
-   *
-   * The direntry is only valid during the lifetime of an open
-   * dirstream.  Once the directory is closed, when the dirstream
-   * is destroyed, or its close() method called, the direntry can
-   * no longer be safely used.  On many systems, including Linux,
-   * this does not matter, but the Single UNIX Specification makes
-   * no garuantees about this.
+   * structure declared in dirent.h.  Unlike a dirent pointer returned
+   * by readdir(3), a direntry does not become invalid when the
+   * dirstream it was extracted from is destroyed.
    */
   class direntry
   {
@@ -232,6 +227,10 @@ namespace sbuild
   /**
    * The overloaded extraction operator.  This is used to pull
    * direntries from a dirstream.
+   *
+   * @param stream the dirstream to get input from.
+   * @param entry the direntry to set.
+   * @returns the dirstream.
    */
   dirstream&
   operator >> (dirstream& stream,
diff --git a/sbuild/sbuild-error.h b/sbuild/sbuild-error.h
index 573f63c6..bd5d07dd 100644
--- a/sbuild/sbuild-error.h
+++ b/sbuild/sbuild-error.h
@@ -111,7 +111,9 @@ namespace sbuild
   class error : public error_base
   {
   public:
+    /// The enum type providing the error codes for this type.
     typedef T error_type;
+    /// Mapping between error code and error description.
     typedef std::map<error_type,const char *> map_type;
 
     /**
@@ -232,6 +234,12 @@ namespace sbuild
     template<typename A, bool b>
     struct add_detail_helper
     {
+      /**
+       * The constructor.
+       *
+       * @param fmt the format string to add to.
+       * @param value the value to add.
+       */
       add_detail_helper(boost::format& fmt,
 			A const&       value)
       {
@@ -246,6 +254,12 @@ namespace sbuild
     template<typename A>
     struct add_detail_helper<A, true>
     {
+      /**
+       * The constructor.
+       *
+       * @param fmt the format string to add to.
+       * @param value the exception to add.
+       */
       add_detail_helper(boost::format& fmt,
 			A const&       value)
       {
@@ -271,6 +285,12 @@ namespace sbuild
     template<typename A, bool b>
     struct add_reason_helper
     {
+      /**
+       * The constructor.
+       *
+       * @param reason the reason to add to.
+       * @param value the value to add.
+       */
       add_reason_helper(std::string& reason,
 			A const&     value)
       {
@@ -284,6 +304,12 @@ namespace sbuild
     template<typename A>
     struct add_reason_helper<A, true>
     {
+      /**
+       * The constructor.
+       *
+       * @param reason the reason to add to.
+       * @param value the exception to add.
+       */
       add_reason_helper(std::string& reason,
 			A const&     value)
       {
diff --git a/sbuild/sbuild-format-detail.h b/sbuild/sbuild-format-detail.h
index 2e997979..7a9ee3b0 100644
--- a/sbuild/sbuild-format-detail.h
+++ b/sbuild/sbuild-format-detail.h
@@ -50,18 +50,46 @@ namespace sbuild
 
     virtual ~format_detail ();
 
+    /**
+     * Add a name-value pair (string specialisation).
+     *
+     * @param name the name.
+     * @param value the string value.
+     * @returns a reference to the format_detail object.
+     */
     format_detail&
     add (std::string const& name,
 	 std::string const& value);
 
+    /**
+     * Add a name-value pair (bool specialisation).
+     *
+     * @param name the name.
+     * @param value the bool value.
+     * @returns a reference to the format_detail object.
+     */
     format_detail&
     add (std::string const& name,
 	 bool               value);
 
+    /**
+     * Add a name-value pair (string_list specialisation).
+     *
+     * @param name the name.
+     * @param value the string_list value.
+     * @returns a reference to the format_detail object.
+     */
     format_detail&
     add (std::string const& name,
 	 string_list const& value);
 
+    /**
+     * Add a name-value pair.
+     *
+     * @param name the name.
+     * @param value the value.
+     * @returns a reference to the format_detail object.
+     */
     template<typename T>
     format_detail&
     add (std::string const& name,
@@ -141,10 +169,8 @@ namespace sbuild
 
     /// The title of the items to format.
     std::string title;
-
     /// The locale to use for output.
     std::locale locale;
-
     /// The items to format;
     list_type   items;
   };
diff --git a/sbuild/sbuild-keyfile.h b/sbuild/sbuild-keyfile.h
index adc422d3..3f50c981 100644
--- a/sbuild/sbuild-keyfile.h
+++ b/sbuild/sbuild-keyfile.h
@@ -41,8 +41,8 @@ namespace sbuild
   /**
    * Configuration file parser.  This class loads an INI-style
    * configuration file from a file or stream.  The format is
-   * documented in schroot.conf(5).  It is based upon the Glib
-   * GKeyFile class, which it is intended to replace.
+   * documented in schroot.conf(5).  It is an independent
+   * reimplementation of the Glib GKeyFile class, which it replaces.
    */
   class keyfile
   {
@@ -632,6 +632,10 @@ namespace sbuild
 
     /**
      * keyfile initialisation from an istream.
+     *
+     * @param stream the stream to input from.
+     * @param kf the keyfile to set.
+     * @returns the stream.
      */
     template <class charT, class traits>
     friend
@@ -713,6 +717,10 @@ namespace sbuild
 
     /**
      * keyfile output to an ostream.
+     *
+     * @param stream the stream to output to.
+     * @param kf the keyfile to output.
+     * @returns the stream.
      */
     template <class charT, class traits>
     friend
diff --git a/sbuild/sbuild-lock.cc b/sbuild/sbuild-lock.cc
index 5a91de81..7a33b8f6 100644
--- a/sbuild/sbuild-lock.cc
+++ b/sbuild/sbuild-lock.cc
@@ -156,7 +156,7 @@ file_lock::~file_lock ()
 }
 
 void
-file_lock::set_lock (type         lock_type,
+file_lock::set_lock (lock::type   lock_type,
 		     unsigned int timeout)
 {
   try
@@ -217,7 +217,7 @@ device_lock::~device_lock ()
 }
 
 void
-device_lock::set_lock (type         lock_type,
+device_lock::set_lock (lock::type   lock_type,
 		       unsigned int timeout)
 {
   try
diff --git a/sbuild/sbuild-lock.h b/sbuild/sbuild-lock.h
index f41f7465..ce2cac89 100644
--- a/sbuild/sbuild-lock.h
+++ b/sbuild/sbuild-lock.h
@@ -145,11 +145,11 @@ namespace sbuild
     /// The destructor.
     virtual ~file_lock ();
 
-    void
-    set_lock (type         lock_type,
+    virtual void
+    set_lock (lock::type   lock_type,
 	      unsigned int timeout);
 
-    void
+    virtual void
     unset_lock ();
 
   private:
@@ -176,11 +176,11 @@ namespace sbuild
     /// The destructor.
     virtual ~device_lock ();
 
-    void
-    set_lock (type         lock_type,
+    virtual void
+    set_lock (lock::type   lock_type,
 	      unsigned int timeout);
 
-    void
+    virtual void
     unset_lock ();
 
   private:
diff --git a/sbuild/sbuild-null.h b/sbuild/sbuild-null.h
index 763225ea..a1c6a505 100644
--- a/sbuild/sbuild-null.h
+++ b/sbuild/sbuild-null.h
@@ -36,17 +36,26 @@ namespace sbuild
     public:
       /**
        * Null output to an ostream.
+       *
+       * @param stream the stream to output to.
+       * @param rhs the null to output.
+       * @returns the stream.
        */
       template <class charT, class traits>
       friend
       std::basic_ostream<charT,traits>&
       operator << (std::basic_ostream<charT,traits>& stream,
-		   null const&                       n)
+		   null const&                       rhs)
       {
 	return stream << null_output();
       }
 
     private:
+      /**
+       * Get a string for output.
+       *
+       * @returns the word "unknown" (translated).
+       */
       static const char *
       null_output ();
   };
diff --git a/sbuild/sbuild-run-parts.cc b/sbuild/sbuild-run-parts.cc
index 72331bdf..255bc92b 100644
--- a/sbuild/sbuild-run-parts.cc
+++ b/sbuild/sbuild-run-parts.cc
@@ -68,7 +68,6 @@ run_parts::run_parts (std::string const& directory,
   umask(umask),
   verbose(false),
   reverse(false),
-  //  restricted(true),
   directory(directory),
   programs()
 {
diff --git a/sbuild/sbuild-run-parts.h b/sbuild/sbuild-run-parts.h
index 1b5def29..c49306bb 100644
--- a/sbuild/sbuild-run-parts.h
+++ b/sbuild/sbuild-run-parts.h
@@ -50,7 +50,20 @@ namespace sbuild
     /// Exception type.
     typedef custom_error<error_code> error;
 
-    /// The constructor.
+    /**
+     *  The constructor.
+     *
+     * @param directory the directory to run scripts from.
+     * @param lsb_mode use Linux Standard Base filename requirements.
+     * If true, the following patterns are permitted: LANANA
+     * ("^[a-z0-9]+$"), LSB ("^_?([a-z0-9_.]+-)+[a-z0-9]+$"), and
+     * Debian cron ("^[a-z0-9][a-z0-9-]*$").  Debian dpkg conffile
+     * backups are not permitted ("dpkg-(old|dist|new|tmp)$").  If
+     * false, the traditional run-parts pattern is used
+     * ("^[a-zA-Z0-9_-]$").
+     * @param abort_on_error stop executing scripts if one returns an error.
+     * @param umask the umask to set when running scripts.
+     */
     run_parts (std::string const& directory,
 	       bool               lsb_mode = true,
 	       bool               abort_on_error = true,
@@ -91,11 +104,19 @@ namespace sbuild
     void
     set_reverse (bool reverse);
 
+    /**
+     * Run all scripts in the specified directory.  If abort_on_error
+     * is true, execution will stop at the first script to fail.
+     *
+     * @param command the command to run.
+     * @param env the environment to use.
+     * @returns the exit status of the scripts.  This will be 0 on
+     * success, or the exit status of the last failing script.
+     */
     int
     run(string_list const& command,
 	environment const& env);
 
-
     /**
      * Output the environment to an ostream.
      *
@@ -127,27 +148,57 @@ namespace sbuild
     }
 
   private:
+    /**
+     * Run the command specified by file (an absolute pathname), using
+     * command and env as the argv and environment, respectively.
+     *
+     * @param file the program to execute.
+     * @param command the arguments to pass to the executable.
+     * @param env the environment.
+     * @returns the return value of the execve system call on failure.
+     */
     int
     run_child(std::string const& file,
 	      string_list const& command,
 	      environment const& env);
 
+    /**
+     * Wait for a child process to complete, and check its exit status.
+     *
+     * An error will be thrown on failure.
+     *
+     * @param pid the pid to wait for.
+     * @param child_status the place to store the child exit status.
+     */
     void
     wait_for_child (pid_t pid,
 		    int&  child_status);
 
+    /**
+     * Check a filename matches the allowed pattern(s).
+     *
+     * @param name the filename to check.
+     * @returns true if it matches, false if not.
+     */
     bool
     check_filename (std::string const& name);
 
+    /// A sorted set of filenames to use.
     typedef std::set<std::string> program_set;
 
+    /// The LSB mode for allowed filenames.
     bool        lsb_mode;
+    /// Whether to abort on script execution error.
     bool        abort_on_error;
+    /// The umask to run scripts with.
     mode_t      umask;
+    /// Verbose logging.
     bool        verbose;
+    /// Execute scripts in reverse order.
     bool        reverse;
-    //    bool        restricted;
+    /// The directory to run scripts from.
     std::string directory;
+    /// The list of scripts to run.
     program_set programs;
   };
 
diff --git a/sbuild/sbuild-session.cc b/sbuild/sbuild-session.cc
index a4032535..33a13683 100644
--- a/sbuild/sbuild-session.cc
+++ b/sbuild/sbuild-session.cc
@@ -705,10 +705,10 @@ session::get_shell () const
       if (shell != "/bin/sh")
 	{
 	  error e1(shell, SHELL, strerror(errno));
-	  log_warning() << e1.what() << endl;
+	  log_exception_warning(e1);
 	  shell = "/bin/sh";
 	  error e2(SHELL_FB, shell);
-	  log_warning() << e2.what() << endl;
+	  log_exception_warning(e2);
 	}
     }
 
@@ -963,7 +963,7 @@ session::setup_chroot (sbuild::chroot::ptr&       session_chroot,
 		setup_type == chroot::SETUP_RECOVER ||
 		setup_type == chroot::SETUP_STOP)
 	       ? SCHROOT_CONF_SETUP_D // Setup directory
-	       : SCHROOT_CONF_EXEC_D, // Run directory
+	       : SCHROOT_CONF_EXEC_D, // Execution directory
 	       true, true, 022);
   rp.set_reverse((setup_type == chroot::SETUP_STOP ||
 		  setup_type == chroot::EXEC_STOP));
@@ -1039,14 +1039,10 @@ session::run_child (sbuild::chroot::ptr& session_chroot)
 
   /* Set group ID and supplementary groups */
   if (setgid (get_gid()))
-    {
-      throw error(get_gid(), GROUP_SET, strerror(errno));
-    }
+    throw error(get_gid(), GROUP_SET, strerror(errno));
   log_debug(DEBUG_NOTICE) << "Set GID=" << get_gid() << std::endl;
   if (initgroups (get_user().c_str(), get_gid()))
-    {
-      throw error(GROUP_SET_SUP, strerror(errno));
-    }
+    throw error(GROUP_SET_SUP, strerror(errno));
   log_debug(DEBUG_NOTICE) << "Set supplementary groups" << std::endl;
 
   /* Set the process execution domain. */
@@ -1057,26 +1053,18 @@ session::run_child (sbuild::chroot::ptr& session_chroot)
 
   /* Enter the chroot */
   if (chdir (location.c_str()))
-    {
-      throw error(location, CHDIR, strerror(errno));
-    }
+    throw error(location, CHDIR, strerror(errno));
   log_debug(DEBUG_NOTICE) << "Changed directory to " << location << std::endl;
   if (::chroot (location.c_str()))
-    {
-      throw error(location, CHROOT, strerror(errno));
-    }
+    throw error(location, CHROOT, strerror(errno));
   log_debug(DEBUG_NOTICE) << "Changed root to " << location << std::endl;
 
   /* Set uid and check we are not still root */
   if (setuid (get_uid()))
-    {
-      throw error(get_uid(), USER_SET, strerror(errno));
-    }
+    throw error(get_uid(), USER_SET, strerror(errno));
   log_debug(DEBUG_NOTICE) << "Set UID=" << get_uid() << std::endl;
   if (!setuid (0) && get_uid())
-    {
-      throw error(ROOT_DROP);
-    }
+    throw error(ROOT_DROP);
   if (get_uid())
     log_debug(DEBUG_NOTICE) << "Dropped root privileges" << std::endl;
 
@@ -1143,9 +1131,7 @@ session::run_child (sbuild::chroot::ptr& session_chroot)
 
   /* Execute */
   if (exec (file, full_command, env))
-    {
-      throw error(file, EXEC, strerror(errno));
-    }
+    throw error(file, EXEC, strerror(errno));
 
   /* This should never be reached */
   _exit(EXIT_FAILURE);
@@ -1187,9 +1173,7 @@ session::wait_for_child (pid_t pid,
 	  if (errno == EINTR && (sighup_called || sigterm_called))
 	    continue; // Kill child and wait again.
 	  else
-	    {
-	      throw error(CHILD_WAIT, strerror(errno));
-	    }
+	    throw error(CHILD_WAIT, strerror(errno));
 	}
       else if (sighup_called)
 	{
@@ -1208,9 +1192,7 @@ session::wait_for_child (pid_t pid,
   if (!WIFEXITED(status))
     {
       if (WIFSIGNALED(status))
-	{
-	  throw error(CHILD_SIGNAL, strsignal(WTERMSIG(status)));
-	}
+	throw error(CHILD_SIGNAL, strsignal(WTERMSIG(status)));
       else if (WCOREDUMP(status))
 	throw error(CHILD_CORE);
       else
@@ -1287,9 +1269,7 @@ session::set_signal_handler (int                signal,
   new_sa.sa_handler = handler;
 
   if (sigaction(signal, &new_sa, saved_signal) != 0)
-    {
-      throw error(SIGNAL_SET, strsignal(signal), strerror(errno));
-    }
+    throw error(SIGNAL_SET, strsignal(signal), strerror(errno));
 }
 
 void
diff --git a/sbuild/sbuild-tr1types.h b/sbuild/sbuild-tr1types.h
index 3d7a887e..b6cd3ae6 100644
--- a/sbuild/sbuild-tr1types.h
+++ b/sbuild/sbuild-tr1types.h
@@ -17,6 +17,12 @@
  *
  *********************************************************************/
 
+/**
+ * @file sbuild-tr1types.h TR1 type substitution.  This header
+ * substitutes Boost types as TR1 types when the Standard Library does
+ * not support TR1.
+ */
+
 #ifndef SBUILD_TR1TYPES_H
 #define SBUILD_TR1TYPES_H
 
diff --git a/sbuild/sbuild-types.h b/sbuild/sbuild-types.h
index 78933d44..6a65ba8d 100644
--- a/sbuild/sbuild-types.h
+++ b/sbuild/sbuild-types.h
@@ -32,21 +32,38 @@ namespace sbuild
   /// A string vector.
   typedef std::vector<std::string> string_list;
 
-  /// A date representation.
+  /**
+   * A date representation.
+   */
   class date_base
   {
   public:
+    /// Function pointer to split time into a std::tm.
     typedef std::tm *(*break_time_func)(const time_t *timep, std:: tm *result);
 
+    /**
+     * The constructor.
+     *
+     * @param unix_time the time.
+     * @param break_time the function to split up the time.
+     */
     date_base (time_t          unix_time,
 	       break_time_func break_time):
       unix_time(unix_time),
       break_time(break_time)
     {}
 
+    /// The destructor.
     ~date_base ()
     {}
 
+    /**
+     * Output the date to an ostream.
+     *
+     * @param stream the stream to output to.
+     * @param dt the date to output.
+     * @returns the stream.
+     */
     template <class charT, class traits>
     friend
     std::basic_ostream<charT,traits>&
@@ -107,28 +124,48 @@ namespace sbuild
     }
 
   private:
+    /// The time.
     time_t          unix_time;
+    /// The function to split up the time.
     break_time_func break_time;
   };
 
+  /**
+   * A date representation in UTC.
+   */
   class gmdate : public date_base
   {
   public:
+    /**
+     * The constructor.
+     *
+     * @param unix_time the time in UTC.
+     */
     gmdate (time_t          unix_time):
       date_base(unix_time, gmtime_r)
     {}
 
+    /// The destructor.
     ~gmdate ()
     {}
   };
 
+  /**
+   * A date representation in local time.
+   */
   class date : public date_base
   {
   public:
+    /**
+     * The constructor.
+     *
+     * @param unix_time the time in the local timezone.
+     */
     date (time_t          unix_time):
       date_base(unix_time, localtime_r)
     {}
 
+    /// The destructor.
     ~date ()
     {}
   };
diff --git a/schroot/schroot-base-main.cc b/schroot/schroot-base-main.cc
index 35405f50..738128c7 100644
--- a/schroot/schroot-base-main.cc
+++ b/schroot/schroot-base-main.cc
@@ -62,6 +62,7 @@ main::action_version (std::ostream& stream)
 
   stream << fmt
 	 << _("Written by Roger Leigh") << '\n' << '\n'
+    // TRANSLATORS: '(C)' is a copyright symbol and '-' is an en-dash.
 	 << _("Copyright (C) 2004-2006 Roger Leigh") << '\n'
 	 << _("This is free software; see the source for copying conditions.  There is NO\n"
 	      "warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n")
diff --git a/schroot/schroot-base-options.h b/schroot/schroot-base-options.h
index e8404153..fe436608 100644
--- a/schroot/schroot-base-options.h
+++ b/schroot/schroot-base-options.h
@@ -57,6 +57,12 @@ namespace schroot_base
     /// The destructor.
     virtual ~options ();
 
+    /**
+     * Parse the command-line options.
+     *
+     * @param argc the number of arguments
+     * @param argv argument vector
+     */
     void
     parse (int   argc,
 	   char *argv[]);
@@ -66,27 +72,51 @@ namespace schroot_base
     /// Verbose messages.
     bool verbose;
 
+    /**
+     * Get the visible options group.  This options group contains all
+     * the options visible to the user.
+     *
+     * @returns the options_description.
+     */
     boost::program_options::options_description const&
     get_visible_options() const;
 
   protected:
+    /**
+     * Add options to option groups.
+     */
     virtual void
     add_options ();
 
+    /**
+     * Add option groups to container groups.
+     */
     virtual void
     add_option_groups ();
 
+    /**
+     * Check options after parsing.
+     */
     virtual void
     check_options ();
 
+    /**
+     * Check actions after parsing.
+     */
     virtual void
     check_actions ();
 
+    /// General options group.
     boost::program_options::options_description            general;
+    /// Hidden options group.
     boost::program_options::options_description            hidden;
+    /// Positional options group.
     boost::program_options::positional_options_description positional;
+    /// Visible options container (used for --help).
     boost::program_options::options_description            visible;
+    /// Global options container (used for parsing).
     boost::program_options::options_description            global;
+    /// Variables map, filled during parsing.
     boost::program_options::variables_map                  vm;
 
   private:
diff --git a/schroot/schroot-listmounts-main.cc b/schroot/schroot-listmounts-main.cc
index e64bec88..ba06c13d 100644
--- a/schroot/schroot-listmounts-main.cc
+++ b/schroot/schroot-listmounts-main.cc
@@ -69,7 +69,8 @@ sbuild::error<main::error_code>::error_strings
 
 main::main (options::ptr& options):
   schroot_base::main("schroot-listmounts",
-		     // TRANSLATORS: Please use an ellipsis e.g. U+2026
+		     // TRANSLATORS: '...' is an ellipsis e.g. U+2026,
+		     // and '-' is an em-dash.
 		     N_("[OPTION...] - list mount points"),
 		     options),
   opts(options)
diff --git a/schroot/schroot-listmounts-options.h b/schroot/schroot-listmounts-options.h
index 47bea112..581b4811 100644
--- a/schroot/schroot-listmounts-options.h
+++ b/schroot/schroot-listmounts-options.h
@@ -74,6 +74,7 @@ namespace schroot_listmounts
     virtual void
     check_options ();
 
+    /// Mount options group.
     boost::program_options::options_description mount;
   };
 
diff --git a/schroot/schroot-main-base.cc b/schroot/schroot-main-base.cc
index ea72a2e8..cb0f5f0e 100644
--- a/schroot/schroot-main-base.cc
+++ b/schroot/schroot-main-base.cc
@@ -64,6 +64,7 @@ namespace
 
 }
 
+/// Error code to description mapping.
 template<>
 sbuild::error<main_base::error_code>::map_type
 sbuild::error<main_base::error_code>::error_strings
diff --git a/schroot/schroot-main-base.h b/schroot/schroot-main-base.h
index 92172977..fc0254f3 100644
--- a/schroot/schroot-main-base.h
+++ b/schroot/schroot-main-base.h
@@ -117,13 +117,15 @@ namespace schroot
      * Load configuration.
      */
     virtual void
-    load_config();
+    load_config ();
 
     /**
      * Create a session.  This sets the session member.
+     *
+     * @param sess_op the session operation to perform.
      */
     virtual void
-    create_session(sbuild::session::operation sess_op) = 0;
+    create_session (sbuild::session::operation sess_op) = 0;
 
   protected:
     /// The program options.
diff --git a/schroot/schroot-main.cc b/schroot/schroot-main.cc
index 2472d5bd..0681f2ef 100644
--- a/schroot/schroot-main.cc
+++ b/schroot/schroot-main.cc
@@ -37,7 +37,8 @@ using namespace schroot;
 
 main::main (options_base::ptr& options):
   main_base("schroot",
-	    // TRANSLATORS: Please use an ellipsis e.g. U+2026
+	    // TRANSLATORS: '...' is an ellipsis e.g. U+2026, and '-'
+	    // is an em-dash.
 	    N_("[OPTION...] [COMMAND] - run command or shell in a chroot"),
 	    options)
 {
diff --git a/schroot/schroot-main.h b/schroot/schroot-main.h
index 31c7d2f8..c9c10120 100644
--- a/schroot/schroot-main.h
+++ b/schroot/schroot-main.h
@@ -55,9 +55,6 @@ namespace schroot
     action_config ();
 
   protected:
-    /**
-     * Create a session.  This sets the session member.
-     */
     virtual void
     create_session(sbuild::session::operation sess_op);
   };
diff --git a/schroot/schroot-options-base.h b/schroot/schroot-options-base.h
index bc800bb8..992ddc7e 100644
--- a/schroot/schroot-options-base.h
+++ b/schroot/schroot-options-base.h
@@ -134,8 +134,11 @@ namespace schroot
     virtual void
     check_actions ();
 
+    /// Chroot options group.
     boost::program_options::options_description chroot;
+    /// Chroot environment options group.
     boost::program_options::options_description chrootenv;
+    /// Session options group.
     boost::program_options::options_description session;
   };
 
diff --git a/schroot/schroot-releaselock-main.cc b/schroot/schroot-releaselock-main.cc
index e7069706..3317eaad 100644
--- a/schroot/schroot-releaselock-main.cc
+++ b/schroot/schroot-releaselock-main.cc
@@ -67,7 +67,8 @@ sbuild::error<main::error_code>::error_strings
 
 main::main (options::ptr& options):
   schroot_base::main("schroot-releaselock",
-		     // TRANSLATORS: Please use an ellipsis e.g. U+2026
+		     // TRANSLATORS: '...' is an ellipsis e.g. U+2026,
+		     // and '-' is an em-dash.
 		     N_("[OPTION...] - release a device lock"),
 		     options),
   opts(options)
diff --git a/schroot/schroot-releaselock-options.h b/schroot/schroot-releaselock-options.h
index 91317d80..c38fffb9 100644
--- a/schroot/schroot-releaselock-options.h
+++ b/schroot/schroot-releaselock-options.h
@@ -76,6 +76,7 @@ namespace schroot_releaselock
     virtual void
     check_options ();
 
+    /// Lock options group.
     boost::program_options::options_description lock;
   };
 
diff --git a/schroot/schroot-setup.5.in b/schroot/schroot-setup.5.in
index 6818fed2..b86e55e8 100644
--- a/schroot/schroot-setup.5.in
+++ b/schroot/schroot-setup.5.in
@@ -16,7 +16,7 @@
 .\" MA  02111-1307  USA
 .TH SCHROOT-SETUP 5 "@RELEASE_DATE@" "Version @VERSION@" "Debian sbuild"
 .SH NAME
-schroot-setup \- schroot chroot setup scripts
+schroot-setup \[em] schroot chroot setup scripts
 .SH DESCRIPTION
 \fBschroot\fP uses scripts to to set up and then clean up the chroot
 environment.  The directories \f[BI]@SCHROOT_CONF_SETUP_D@\fP and
diff --git a/schroot/schroot.1.in b/schroot/schroot.1.in
index ea50add9..5b7c0d5c 100644
--- a/schroot/schroot.1.in
+++ b/schroot/schroot.1.in
@@ -17,7 +17,7 @@
 .\" MA  02111-1307  USA
 .TH SCHROOT 1 "@RELEASE_DATE@" "Version @VERSION@" "Debian sbuild"
 .SH NAME
-schroot \- securely enter a chroot environment
+schroot \[em] securely enter a chroot environment
 .SH SYNOPSIS
 .B schroot
 .RB [ \-h \[or] \-\-help " \[or] " \-V \[or] \-\-version
diff --git a/schroot/schroot.conf.5.in b/schroot/schroot.conf.5.in
index f2026dff..02001ba0 100644
--- a/schroot/schroot.conf.5.in
+++ b/schroot/schroot.conf.5.in
@@ -16,7 +16,7 @@
 .\" MA  02111-1307  USA
 .TH SCHROOT.CONF 5 "@RELEASE_DATE@" "Version @VERSION@" "Debian sbuild"
 .SH NAME
-schroot.conf \- chroot definition file for schroot
+schroot.conf \[em] chroot definition file for schroot
 .SH DESCRIPTION
 \f[BI]schroot.conf\fP is a plain UTF-8 text file, describing the chroots
 available for use with sbuild.
@@ -73,14 +73,14 @@ A comma-separated list of users which are allowed \fBpassword-less\fP root
 access to the chroot.  If empty or omitted, no users will be allowed root
 access without a password (but if a user or a group they belong to is in
 \f[CI]users\fP or \f[CI]groups\fP, respectively, they may gain access with a
-password).
+password).  See the section \[lq]\fISecurity\fP\[rq] below.
 .TP
 \f[CBI]root\-groups=\fP\f[CI]group1,group2,...\fP
 A comma-separated list of groups which are allowed \fBpassword-less\fP root
 access to the chroot.  If empty or omitted, no users will be allowed root
 access without a password (but if a user or a group they belong to is in
 \f[CI]users\fP or \f[CI]groups\fP, respectively, they may gain access with a
-password).
+password).  See the section \[lq]\fISecurity\fP\[rq] below.
 .TP
 \f[CBI]aliases=\fP\f[CI]alias1,alias2,...\fP
 A comma-separated list of aliases (alternate names) for this chroot.  For
@@ -213,14 +213,15 @@ If empty or omitted, no users will be allowed access.  This will become the
 access to the source chroot.  If empty or omitted, no users will be allowed
 root access without a password (but if a user is in \f[CI]users\fP, they may
 gain access with a password).  This will become the \f[CI]root\-users\fP option
-in the source chroot.
+in the source chroot.  See the section \[lq]\fISecurity\fP\[rq] below.
 .TP
 \f[CBI]source\-root\-groups=\fP\f[CI]group1,group2,...\fP
  A comma-separated list of groups which are allowed \fBpassword-less\fP root
 access to the source chroot.  If empty or omitted, no users will be allowed
 root access without a password (but if a user's group is in \f[CI]groups\fP,
 they may gain access with a password).  This will become the
-\f[CI]root\-groups\fP option in the source chroot.
+\f[CI]root\-groups\fP option in the source chroot.  See the section
+\[lq]\fISecurity\fP\[rq] below.
 .SS Localisation
 .PP
 Some keys may be localised in multiple lanuages.  This is achieved by adding
@@ -239,6 +240,14 @@ This will localise the \f[CI]description\fP key for the en_GB locale.
 .PP
 This will localise the \f[CI]description\fP key for all French locales.
 .br
+.SH SECURITY
+Note that giving untrusted users root access to chroots is a \fBserious
+security risk\fP!  Although the untrusted user will only have root access to
+files inside the chroot, in practice there are many obvious ways of breaking
+out of the chroot and of disrupting services on the host system.  As always,
+this boils down to \fItrust\fP.
+.B Don't give chroot root access to users you would not trust
+.B with root access to the host system.
 .SH EXAMPLE
 \f[CR]# Sample configuration\fP
 .br
@@ -260,7 +269,7 @@ This will localise the \f[CI]description\fP key for all French locales.
 .br
 \f[CR]groups=sbuild\fP
 .br
-\f[CR]root-users=rleigh\fP
+\f[CR]root\-users=rleigh\fP
 .br
 \f[CR]aliases=unstable,default\fP
 .br
@@ -268,31 +277,31 @@ This will localise the \f[CI]description\fP key for all French locales.
 .br
 \f[CR][etch]\fP
 .br
-\f[CR]type=block-device\fP
+\f[CR]type=block\-device\fP
 .br
-\f[CR]description=Debian testing (32-bit)\fP
+\f[CR]description=Debian testing (32\-bit)\fP
 .br
 \f[CR]priority=2\fP
 .br
 \f[CR]groups=users\fP
 .br
-\f[CR]#groups=sbuild-security\fP
+\f[CR]#groups=sbuild\-security\fP
 .br
 \f[CR]aliases=testing\fP
 .br
 \f[CR]device=/dev/hda_vg/etch_chroot\fP
 .br
-\f[CR]mount-options=-o atime\fP
+\f[CR]mount\-options=\-o atime\fP
 .br
 \f[CR]personality=linux32\fP
 .br
-\f[CR]run-setup-scripts=true\fP
+\f[CR]run\-setup\-scripts=true\fP
 .br
-\f[CR]run-exec-scripts=true\fP
+\f[CR]run\-exec\-scripts=true\fP
 .br
 \f[CR]\fP
 .br
-\f[CR][sid-file]\fP
+\f[CR][sid\-file]\fP
 .br
 \f[CR]type=file\fP
 .br
@@ -304,15 +313,15 @@ This will localise the \f[CI]description\fP key for all French locales.
 .br
 \f[CR]file=/srv/chroots/sid.tar.gz\fP
 .br
-\f[CR]run-setup-scripts=true\fP
+\f[CR]run\-setup\-scripts=true\fP
 .br
-\f[CR]run-exec-scripts=true\fP
+\f[CR]run\-exec\-scripts=true\fP
 .br
 \f[CR]\fP
 .br
-\f[CR][sid-snapshot]\fP
+\f[CR][sid\-snapshot]\fP
 .br
-\f[CR]type=lvm-snapshot\fP
+\f[CR]type=lvm\-snapshot\fP
 .br
 \f[CR]description=Debian unstable LVM snapshot\fP
 .br
@@ -322,19 +331,19 @@ This will localise the \f[CI]description\fP key for all French locales.
 .br
 \f[CR]users=rleigh\fP
 .br
-\f[CR]source-root-users=rleigh\fP
+\f[CR]source\-root\-users=rleigh\fP
 .br
-\f[CR]source-root-groups=admin\fP
+\f[CR]source\-root\-groups=admin\fP
 .br
 \f[CR]device=/dev/hda_vg/sid_chroot\fP
 .br
-\f[CR]mount-options=-o atime,sync,user_xattr\fP
+\f[CR]mount\-options=\-o atime,sync,user_xattr\fP
 .br
-\f[CR]lvm-snapshot-options=--size 2G\fP
+\f[CR]lvm\-snapshot\-options=\-\-size 2G\fP
 .br
-\f[CR]run-setup-scripts=true\fP
+\f[CR]run\-setup\-scripts=true\fP
 .br
-\f[CR]run-exec-scripts=true\fP
+\f[CR]run\-exec\-scripts=true\fP
 .SH FILES
 .TP
 .I @SCHROOT_CONF@