Use methoddesc and memberdesc, as needed.

Added description of BastionClass, since it is referred to in the Bastion
description as subclassable.

4 files changed, 104 insertions, 84 deletions

diff --git a/Doc/lib/libbastion.tex b/Doc/lib/libbastion.tex
index c405c64..b5bec15 100644
--- a/Doc/lib/libbastion.tex
+++ b/Doc/lib/libbastion.tex
@@ -1,7 +1,6 @@
 \section{Standard Module \sectcode{Bastion}}
 \label{module-Bastion}
 \stmodindex{Bastion}
-\setindexsubitem{(in module Bastion)}
 
 % I'm concerned that the word 'bastion' won't be understood by people
 % for whom English is a second language, making the module name
@@ -17,7 +16,8 @@ other, unsafe attributes.
 
 % I've punted on the issue of documenting keyword arguments for now.
 
-\begin{funcdesc}{Bastion}{object\optional{, filter, name, class}}
+\begin{funcdesc}{Bastion}{object\optional{, filter\optional{,
+                          name\optional{, class}}}}
 Protect the object \var{object}, returning a bastion for the
 object.  Any attempt to access one of the object's attributes will
 have to be approved by the \var{filter} function; if the access is
@@ -32,8 +32,17 @@ will be \samp{<Bastion for \var{name}>} if a value for
 \var{name} is provided; otherwise, \samp{repr(\var{object})} will be
 used.
 
-\var{class}, if present, would be a subclass of \class{BastionClass};
+\var{class}, if present, should be a subclass of \class{BastionClass}; 
 see the code in \file{bastion.py} for the details.  Overriding the
 default \class{BastionClass} will rarely be required.
-
 \end{funcdesc}
+
+
+\begin{classdesc}{BastionClass}{getfunc, name}
+Class which actually implements bastion objects.  This is the default
+class used by \function{Bastion()}.  The \var{getfunc} parameter is a
+function which returns the value of an attribute which should be
+exposed to the restricted execution environment when called with the
+name of the attribute as the only parameter.  \var{name} is used to
+construct the \function{repr()} of the \class{BastionClass} instance.
+\end{classdesc}
diff --git a/Doc/lib/librexec.tex b/Doc/lib/librexec.tex
index e301f81..03e8284 100644
--- a/Doc/lib/librexec.tex
+++ b/Doc/lib/librexec.tex
@@ -50,8 +50,7 @@ instance won't have any effect; instead, create a subclass of
 Instances of the new class will then use those new values.  All these
 attributes are tuples of strings.
 
-\setindexsubitem{(RExec object attribute)}
-\begin{datadesc}{nok_builtin_names}
+\begin{memberdesc}{nok_builtin_names}
 Contains the names of built-in functions which will \emph{not} be
 available to programs running in the restricted environment.  The
 value for \class{RExec} is \code{('open',} \code{'reload',}
@@ -61,9 +60,9 @@ override this variable should probably start with the value from the
 base class and concatenate additional forbidden functions --- when new
 dangerous built-in functions are added to Python, they will also be
 added to this module.)
-\end{datadesc}
+\end{memberdesc}
 
-\begin{datadesc}{ok_builtin_modules}
+\begin{memberdesc}{ok_builtin_modules}
 Contains the names of built-in modules which can be safely imported.
 The value for \class{RExec} is \code{('audioop',} \code{'array',}
 \code{'binascii',} \code{'cmath',} \code{'errno',} \code{'imageop',}
@@ -72,16 +71,16 @@ The value for \class{RExec} is \code{('audioop',} \code{'array',}
 \code{'strop',} \code{'struct',} \code{'time')}.  A similar remark
 about overriding this variable applies --- use the value from the base
 class as a starting point.
-\end{datadesc}
+\end{memberdesc}
 
-\begin{datadesc}{ok_path}
+\begin{memberdesc}{ok_path}
 Contains the directories which will be searched when an \keyword{import}
 is performed in the restricted environment.  
 The value for \class{RExec} is the same as \code{sys.path} (at the time
 the module is loaded) for unrestricted code.
-\end{datadesc}
+\end{memberdesc}
 
-\begin{datadesc}{ok_posix_names}
+\begin{memberdesc}{ok_posix_names}
 % Should this be called ok_os_names?
 Contains the names of the functions in the \module{os} module which will be
 available to programs running in the restricted environment.  The
@@ -90,68 +89,69 @@ value for \class{RExec} is \code{('error',} \code{'fstat',}
 \code{'times',} \code{'uname',} \code{'getpid',} \code{'getppid',}
 \code{'getcwd',} \code{'getuid',} \code{'getgid',} \code{'geteuid',}
 \code{'getegid')}.
-\end{datadesc}
+\end{memberdesc}
 
-\begin{datadesc}{ok_sys_names}
+\begin{memberdesc}{ok_sys_names}
 Contains the names of the functions and variables in the \module{sys}
 module which will be available to programs running in the restricted
 environment.  The value for \class{RExec} is \code{('ps1',}
 \code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',}
 \code{'exit',} \code{'maxint')}.
-\end{datadesc}
+\end{memberdesc}
+
 
 \class{RExec} instances support the following methods:
-\setindexsubitem{(RExec object method)}
 
-\begin{funcdesc}{r_eval}{code}
+\begin{methoddesc}{r_eval}{code}
 \var{code} must either be a string containing a Python expression, or
 a compiled code object, which will be evaluated in the restricted
 environment's \module{__main__} module.  The value of the expression or
 code object will be returned.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_exec}{code}
+\begin{methoddesc}{r_exec}{code}
 \var{code} must either be a string containing one or more lines of
 Python code, or a compiled code object, which will be executed in the
 restricted environment's \module{__main__} module.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_execfile}{filename}
+\begin{methoddesc}{r_execfile}{filename}
 Execute the Python code contained in the file \var{filename} in the
 restricted environment's \module{__main__} module.
-\end{funcdesc}
+\end{methoddesc}
 
 Methods whose names begin with \samp{s_} are similar to the functions
 beginning with \samp{r_}, but the code will be granted access to
 restricted versions of the standard I/O streams \code{sys.stdin},
 \code{sys.stderr}, and \code{sys.stdout}.
 
-\begin{funcdesc}{s_eval}{code}
+\begin{methoddesc}{s_eval}{code}
 \var{code} must be a string containing a Python expression, which will
 be evaluated in the restricted environment.  
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{s_exec}{code}
+\begin{methoddesc}{s_exec}{code}
 \var{code} must be a string containing one or more lines of Python code,
 which will be executed in the restricted environment.  
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{s_execfile}{code}
+\begin{methoddesc}{s_execfile}{code}
 Execute the Python code contained in the file \var{filename} in the
 restricted environment.
-\end{funcdesc}
+\end{methoddesc}
 
 \class{RExec} objects must also support various methods which will be
 implicitly called by code executing in the restricted environment.
 Overriding these methods in a subclass is used to change the policies
 enforced by a restricted environment.
 
-\begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}}
+\begin{methoddesc}{r_import}{modulename\optional{, globals\optional{,
+                             locals\optional{, fromlist}}}}
 Import the module \var{modulename}, raising an \exception{ImportError}
 exception if the module is considered unsafe.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
+\begin{methoddesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
 Method called when \function{open()} is called in the restricted
 environment.  The arguments are identical to those of \function{open()},
 and a file object (or a class instance compatible with file objects)
@@ -159,32 +159,33 @@ should be returned.  \class{RExec}'s default behaviour is allow opening
 any file for reading, but forbidding any attempt to write a file.  See
 the example below for an implementation of a less restrictive
 \method{r_open()}.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_reload}{module}
+\begin{methoddesc}{r_reload}{module}
 Reload the module object \var{module}, re-parsing and re-initializing it.  
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_unload}{module}
+\begin{methoddesc}{r_unload}{module}
 Unload the module object \var{module} (i.e., remove it from the
 restricted environment's \code{sys.modules} dictionary).
-\end{funcdesc}
+\end{methoddesc}
 
 And their equivalents with access to restricted standard I/O streams:
 
-\begin{funcdesc}{s_import}{modulename\optional{, globals, locals, fromlist}}
+\begin{methoddesc}{s_import}{modulename\optional{, globals\optional{,
+                             locals\optional{, fromlist}}}}
 Import the module \var{modulename}, raising an \exception{ImportError}
 exception if the module is considered unsafe.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{s_reload}{module}
+\begin{methoddesc}{s_reload}{module}
 Reload the module object \var{module}, re-parsing and re-initializing it.  
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{s_unload}{module}
+\begin{methoddesc}{s_unload}{module}
 Unload the module object \var{module}.   
 % XXX what are the semantics of this?  
-\end{funcdesc}
+\end{methoddesc}
 
 \subsection{An example}
 
diff --git a/Doc/libbastion.tex b/Doc/libbastion.tex
index c405c64..b5bec15 100644
--- a/Doc/libbastion.tex
+++ b/Doc/libbastion.tex
@@ -1,7 +1,6 @@
 \section{Standard Module \sectcode{Bastion}}
 \label{module-Bastion}
 \stmodindex{Bastion}
-\setindexsubitem{(in module Bastion)}
 
 % I'm concerned that the word 'bastion' won't be understood by people
 % for whom English is a second language, making the module name
@@ -17,7 +16,8 @@ other, unsafe attributes.
 
 % I've punted on the issue of documenting keyword arguments for now.
 
-\begin{funcdesc}{Bastion}{object\optional{, filter, name, class}}
+\begin{funcdesc}{Bastion}{object\optional{, filter\optional{,
+                          name\optional{, class}}}}
 Protect the object \var{object}, returning a bastion for the
 object.  Any attempt to access one of the object's attributes will
 have to be approved by the \var{filter} function; if the access is
@@ -32,8 +32,17 @@ will be \samp{<Bastion for \var{name}>} if a value for
 \var{name} is provided; otherwise, \samp{repr(\var{object})} will be
 used.
 
-\var{class}, if present, would be a subclass of \class{BastionClass};
+\var{class}, if present, should be a subclass of \class{BastionClass}; 
 see the code in \file{bastion.py} for the details.  Overriding the
 default \class{BastionClass} will rarely be required.
-
 \end{funcdesc}
+
+
+\begin{classdesc}{BastionClass}{getfunc, name}
+Class which actually implements bastion objects.  This is the default
+class used by \function{Bastion()}.  The \var{getfunc} parameter is a
+function which returns the value of an attribute which should be
+exposed to the restricted execution environment when called with the
+name of the attribute as the only parameter.  \var{name} is used to
+construct the \function{repr()} of the \class{BastionClass} instance.
+\end{classdesc}
diff --git a/Doc/librexec.tex b/Doc/librexec.tex
index e301f81..03e8284 100644
--- a/Doc/librexec.tex
+++ b/Doc/librexec.tex
@@ -50,8 +50,7 @@ instance won't have any effect; instead, create a subclass of
 Instances of the new class will then use those new values.  All these
 attributes are tuples of strings.
 
-\setindexsubitem{(RExec object attribute)}
-\begin{datadesc}{nok_builtin_names}
+\begin{memberdesc}{nok_builtin_names}
 Contains the names of built-in functions which will \emph{not} be
 available to programs running in the restricted environment.  The
 value for \class{RExec} is \code{('open',} \code{'reload',}
@@ -61,9 +60,9 @@ override this variable should probably start with the value from the
 base class and concatenate additional forbidden functions --- when new
 dangerous built-in functions are added to Python, they will also be
 added to this module.)
-\end{datadesc}
+\end{memberdesc}
 
-\begin{datadesc}{ok_builtin_modules}
+\begin{memberdesc}{ok_builtin_modules}
 Contains the names of built-in modules which can be safely imported.
 The value for \class{RExec} is \code{('audioop',} \code{'array',}
 \code{'binascii',} \code{'cmath',} \code{'errno',} \code{'imageop',}
@@ -72,16 +71,16 @@ The value for \class{RExec} is \code{('audioop',} \code{'array',}
 \code{'strop',} \code{'struct',} \code{'time')}.  A similar remark
 about overriding this variable applies --- use the value from the base
 class as a starting point.
-\end{datadesc}
+\end{memberdesc}
 
-\begin{datadesc}{ok_path}
+\begin{memberdesc}{ok_path}
 Contains the directories which will be searched when an \keyword{import}
 is performed in the restricted environment.  
 The value for \class{RExec} is the same as \code{sys.path} (at the time
 the module is loaded) for unrestricted code.
-\end{datadesc}
+\end{memberdesc}
 
-\begin{datadesc}{ok_posix_names}
+\begin{memberdesc}{ok_posix_names}
 % Should this be called ok_os_names?
 Contains the names of the functions in the \module{os} module which will be
 available to programs running in the restricted environment.  The
@@ -90,68 +89,69 @@ value for \class{RExec} is \code{('error',} \code{'fstat',}
 \code{'times',} \code{'uname',} \code{'getpid',} \code{'getppid',}
 \code{'getcwd',} \code{'getuid',} \code{'getgid',} \code{'geteuid',}
 \code{'getegid')}.
-\end{datadesc}
+\end{memberdesc}
 
-\begin{datadesc}{ok_sys_names}
+\begin{memberdesc}{ok_sys_names}
 Contains the names of the functions and variables in the \module{sys}
 module which will be available to programs running in the restricted
 environment.  The value for \class{RExec} is \code{('ps1',}
 \code{'ps2',} \code{'copyright',} \code{'version',} \code{'platform',}
 \code{'exit',} \code{'maxint')}.
-\end{datadesc}
+\end{memberdesc}
+
 
 \class{RExec} instances support the following methods:
-\setindexsubitem{(RExec object method)}
 
-\begin{funcdesc}{r_eval}{code}
+\begin{methoddesc}{r_eval}{code}
 \var{code} must either be a string containing a Python expression, or
 a compiled code object, which will be evaluated in the restricted
 environment's \module{__main__} module.  The value of the expression or
 code object will be returned.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_exec}{code}
+\begin{methoddesc}{r_exec}{code}
 \var{code} must either be a string containing one or more lines of
 Python code, or a compiled code object, which will be executed in the
 restricted environment's \module{__main__} module.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_execfile}{filename}
+\begin{methoddesc}{r_execfile}{filename}
 Execute the Python code contained in the file \var{filename} in the
 restricted environment's \module{__main__} module.
-\end{funcdesc}
+\end{methoddesc}
 
 Methods whose names begin with \samp{s_} are similar to the functions
 beginning with \samp{r_}, but the code will be granted access to
 restricted versions of the standard I/O streams \code{sys.stdin},
 \code{sys.stderr}, and \code{sys.stdout}.
 
-\begin{funcdesc}{s_eval}{code}
+\begin{methoddesc}{s_eval}{code}
 \var{code} must be a string containing a Python expression, which will
 be evaluated in the restricted environment.  
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{s_exec}{code}
+\begin{methoddesc}{s_exec}{code}
 \var{code} must be a string containing one or more lines of Python code,
 which will be executed in the restricted environment.  
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{s_execfile}{code}
+\begin{methoddesc}{s_execfile}{code}
 Execute the Python code contained in the file \var{filename} in the
 restricted environment.
-\end{funcdesc}
+\end{methoddesc}
 
 \class{RExec} objects must also support various methods which will be
 implicitly called by code executing in the restricted environment.
 Overriding these methods in a subclass is used to change the policies
 enforced by a restricted environment.
 
-\begin{funcdesc}{r_import}{modulename\optional{, globals, locals, fromlist}}
+\begin{methoddesc}{r_import}{modulename\optional{, globals\optional{,
+                             locals\optional{, fromlist}}}}
 Import the module \var{modulename}, raising an \exception{ImportError}
 exception if the module is considered unsafe.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
+\begin{methoddesc}{r_open}{filename\optional{, mode\optional{, bufsize}}}
 Method called when \function{open()} is called in the restricted
 environment.  The arguments are identical to those of \function{open()},
 and a file object (or a class instance compatible with file objects)
@@ -159,32 +159,33 @@ should be returned.  \class{RExec}'s default behaviour is allow opening
 any file for reading, but forbidding any attempt to write a file.  See
 the example below for an implementation of a less restrictive
 \method{r_open()}.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_reload}{module}
+\begin{methoddesc}{r_reload}{module}
 Reload the module object \var{module}, re-parsing and re-initializing it.  
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{r_unload}{module}
+\begin{methoddesc}{r_unload}{module}
 Unload the module object \var{module} (i.e., remove it from the
 restricted environment's \code{sys.modules} dictionary).
-\end{funcdesc}
+\end{methoddesc}
 
 And their equivalents with access to restricted standard I/O streams:
 
-\begin{funcdesc}{s_import}{modulename\optional{, globals, locals, fromlist}}
+\begin{methoddesc}{s_import}{modulename\optional{, globals\optional{,
+                             locals\optional{, fromlist}}}}
 Import the module \var{modulename}, raising an \exception{ImportError}
 exception if the module is considered unsafe.
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{s_reload}{module}
+\begin{methoddesc}{s_reload}{module}
 Reload the module object \var{module}, re-parsing and re-initializing it.  
-\end{funcdesc}
+\end{methoddesc}
 
-\begin{funcdesc}{s_unload}{module}
+\begin{methoddesc}{s_unload}{module}
 Unload the module object \var{module}.   
 % XXX what are the semantics of this?  
-\end{funcdesc}
+\end{methoddesc}
 
 \subsection{An example}