4 files changed, 41 insertions, 0 deletions
diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml
index cb47b99418b6..44a7ac3885a8 100644
--- a/doc/manual/conf-file.xml
+++ b/doc/manual/conf-file.xml
@@ -134,6 +134,23 @@ env-keep-derivations = false
 
     </listitem>
 
+  <varlistentry xml:id="conf-build-timeout"><term><literal>build-timeout</literal></term>
+
+    <listitem>
+
+      <para>This option defines the maximum number of seconds that a
+      builder can run.  This is useful (for instance in a automated
+      build system) to catch builds that are stuck in an infinite loop
+      but keep writing to their standard output or standard error.  It
+      can be overriden using the <option
+      linkend="opt-timeout">--timeout</option> command line
+      switch.</para>
+
+      <para>The value <literal>0</literal> means that there is no
+      timeout.  This is also the default.</para>
+
+    </listitem>
+
   </varlistentry>
 
 
diff --git a/doc/manual/opt-common-syn.xml b/doc/manual/opt-common-syn.xml
index da60288b2a19..23bd36dd6bf0 100644
--- a/doc/manual/opt-common-syn.xml
+++ b/doc/manual/opt-common-syn.xml
@@ -21,6 +21,10 @@
   <arg><option>--max-silent-time</option></arg>
   <replaceable>number</replaceable>
 </arg>
+<arg>
+  <arg><option>--timeout</option></arg>
+  <replaceable>number</replaceable>
+</arg>
 <arg><option>--keep-going</option></arg>
 <arg><option>-k</option></arg>
 <arg><option>--keep-failed</option></arg>
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index 2d67162d7cad..e86e4b412581 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -132,6 +132,16 @@
 
 </varlistentry>
 
+<varlistentry xml:id="opt-timeout"><term><option>--timeout</option></term>
+
+  <listitem><para>Sets the maximum number of seconds that a builder
+  can run.  The default is specified by the <link
+  linkend='conf-build-timeout'><literal>build-timeout</literal></link>
+  configuration setting.  <literal>0</literal> means no
+  timeout.</para></listitem>
+
+</varlistentry>
+
 <varlistentry><term><option>--keep-going</option></term>
   <term><option>-k</option></term>
 
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
index 1e579a37b017..0c29cae90f9d 100644
--- a/doc/manual/release-notes.xml
+++ b/doc/manual/release-notes.xml
@@ -22,6 +22,16 @@
     option.</para>
   </listitem>
 
+  <listitem>
+    <para>The option <option>--timeout</option> (corresponding to the
+    configuration setting <literal>build-timeout</literal>) allows you
+    to set an absolute timeout on builds — if a build runs for more than
+    the given number of seconds, it is terminated.  This is useful for
+    recovering automatically from builds that are stuck in an infinite
+    loop but keep producing output, and for which
+    <literal>--max-silent-time</literal> is ineffective.</para>
+  </listitem>
+
 </itemizedlist>
 
 </section>