Make documentation into dcorrect GAPDoc and add to reference manual.

An example would still be nice.

doc/ref/function.xml

@@ -42,6 +42,17 @@ several arguments</Heading>
 
 </Section>
 
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Calling a function with a time limit">
+<Heading>Calling a function with a time limit</Heading>
+
+
+<#Include Label="CallWithTimeout">
+<#Include Label="GAPInfo.TimeoutsSupported">
+</Section>
+
+
+
 
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <Section Label="Functions that do nothing">

doc/ref/makedocreldata.g

@@ -64,6 +64,7 @@ GAPInfo.ManualDataRef:= rec(
     "../../lib/fpmon.gd",
     "../../lib/fpsemi.gd",
     "../../lib/function.g",
+    "../../lib/function.gd",
     "../../lib/galois.gd",
     "../../lib/gasman.gd",
     "../../lib/ghom.gd",

lib/function.gd

@@ -19,43 +19,54 @@
 #F  CallWithTimeoutList( <timeout>, <func>, <arglist> )  
 ##
 ##  <#GAPDoc Label="CallWithTimeout">
+##  <Index>Timeouts</Index>
 ##  <ManSection>
 ##  <Func Name="CallWithTimeout" Arg='timeout, func, .....'/>
-##  <Func Name="CallWithTimeoutList" Arg='timeout, func, args'/>
+##  <Func Name="CallWithTimeoutList" Arg='timeout, func, arglist'/>
 ##
 ##  <Description>
-##    CallWithTimeout and CallWithTimeoutList support calling a function
-##  with a limit on the CPU time it can consume. 
+##    <C>CallWithTimeout</C> and <C>CallWithTimeoutList</C> support calling a function
+##  with a limit on the CPU time it can consume. <P/>
+##
+##  This functionality may not be available on all systems and you should check 
+##  <Ref Var="GAPInfo.TimeoutsSupported"/> before using this functionality.<P/>
+##
+##  <C>CallWithTimeout</C> is variadic. 
+##  Its third and subsequent arguments, if any, are the arguments passed to <A>func</A>.
+##  <C>CallWithTimeoutList</C> in contrast takes exactly three arguments, of which the third is a list
+##  (possibly empty) or arguments to pass to <A>func</A>. <P/>
 ##
 ##  If the call completes within the allotted time and returns a value, the result of 
-##  CallWithTimeout[List] is a length 1 list containing that value. 
+##  <C>CallWithTimeout[List]</C> is a length 1 list containing that value. <P/>
 ##  
 ##  If the call completes within the allotted time and returns no value, the result of 
-##  CallWithTimeout[List] is an empty list.
-##
-##  If the call does not complete within the timeout, the result of CallWithTimeout[List]
-## is fail.
+##  <C>CallWithTimeout[List]</C> is an empty list.<P/>
 ##
-##  The timer is suspended during execution of a break loop and abandoned when you quit from a break loop.
+##  If the call does not complete within the timeout, the result of <C>CallWithTimeout[List]</C>
+##  is <K>fail</K>.<P/>
 ##
-## CallWithTimeout is variadic. 
-##  Its third and subsequent arguments if any are the arguments if any passed to <func>
-##  CallWithTimeoutList in contract takes exactly three arguments, of which the third is a list
-##  (possibly empty) or arguments to pass to <func>. 
-## 
-##  The limit <timeout> is specified as a record. At present the following components are recognised
-##  nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days and weeks. Any of these 
-##  components which is present should be bound to a positive integer, rational or float and the times
-##  represented are totalled.
+##  The timer is suspended during execution of a break loop and abandoned when you quit from a break loop.<P/>
 ##
-##  Further components are permitted and ignored, to allow for future functionality.
+##  Timeouts may not be nested. That is, during execution of <C>CallWithTimeout(<A>timeout</A>,<A>func</A>,...)</C>,
+##  <A>func</A> (or functions it calls) may not call <C>CallWithTimeout</C> or <C>CallWithTimeoutList</C>. 
+##  This restriction may be lifted on at least some systems in future releases. It is 
+##  permitted to use <C>CallWithTimeout</C> or <C>CallWithTimeoutList</C> from within a break loop, even if a
+##  suspended timeout exists, although there is limit on the depth of such nesting.<P/>
 ##
-##  As a shorthand, a single positive integers may be supplied, and is taken as a number of microseconds
+##  The limit <A>timeout</A> is specified as a record. At present the following components are recognised
+##  <C>nanoseconds</C>, <C>microseconds</C>, <C>milliseconds</C>, <C>seconds</C>, 
+##  <C>minutes</C>, <C>hours</C>, <C>days</C> and <C>weeks</C>. Any of these 
+##  components which is present should be bound to a positive integer, rational or float and the times
+##  represented are totalled to give the actual timeout. As a shorthand, a single positive 
+##  integers may be supplied, and is taken as a number of microseconds.
+##  Further components are permitted and ignored, to allow for future functionality.<P/>
 ##
 ##  The precision of the timeouts is not guaranteed, and there is a system dependent upper limit on the timeout 
 ##  which is typically about 8 years on 32 bit systems and about 30 billion years on 64 bit systems. Timeouts longer
-##  than this will be silently ignored. 
-##
+##  than this will be reduced to this limit.<P/>
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
 
 DeclareGlobalFunction("CallWithTimeout");
 DeclareGlobalFunction("CallWithTimeoutList");

lib/system.g

@@ -523,7 +523,7 @@ end);
 ##
 ## <Description>
 ##  tests whether this installation of &GAP; supports the timeout functionality
-## of <C>CallWithTimeout</C> and related functions. 
+## of <Ref Func="CallWithTimeout"/> and related functions. 
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>