From 51bbdfb2ffe9cb2bfce56bd7877928d8936ea283 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Wed, 1 Mar 1995 14:07:08 +0000 Subject: totally rewritten, for new macro set --- Doc/lib/libtemplate.tex | 161 +++++++++++++++++++++++++++++++++++------------ Doc/libtemplate.tex | 161 +++++++++++++++++++++++++++++++++++------------ Doc/templates/module.tex | 161 +++++++++++++++++++++++++++++++++++------------ 3 files changed, 363 insertions(+), 120 deletions(-) diff --git a/Doc/lib/libtemplate.tex b/Doc/lib/libtemplate.tex index 7465af8..5c702e5 100644 --- a/Doc/lib/libtemplate.tex +++ b/Doc/lib/libtemplate.tex @@ -1,40 +1,121 @@ -% Template for library sections. -% Replace text in ALL CAPS by your own text. -% Comments starting with %** give additional directions. - -%** Choose one of the following two section headings: -\section{Built-in module {\tt YOUR-MODULE-NAME}} % If written in C -\section{Standard module {\tt YOUR-MODULE-NAME}} % If written in Python - -PUT A SHORT INTRODUCTION AND DESCRIPTION OF THE MODULE HERE. - -%** change this sentence to taste: -The module defines the following variables and functions: - -\begin{description} - -\renewcommand{\indexsubitem}{(in module YOUR-MODULE-NAME)} - - -%** You can mix exceptions, variables and functions below; often it is a -%** good idea to alphabetize them all. - - -%** repeat the following for each exception: -\excitem{NAME} -DESCRIPTION OF THE EXCEPTION GOES HERE. - - -%** repeat the following for each variable (or constant): -\dataitem{NAME} -DESCRIPTION OF THE VARIABLE/CONSTANT GOES HERE. - - -%** repeat the following for each function: -\funcitem{NAME}{PARAMETERS} % Don't include the parentheses -DESCRIPTION OF THE FUNCTION GOES HERE. - - -\end{description} - -ADDITIONAL HINTS FOR USING THE MODULE MAY GO HERE. +% Template for a library manual section. +% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE + + +% ==== 1. ==== +% Choose one of the following section headers and index entries; +% \section{} generates the section header, +% \bimodindex{} or \stmodundex{} generates an index entry for this module + +\section{Built-in module \sectcode{spam}} % If implemented in C +\bimodindex[spam} + +\section{Standard module \sectcode{spam}} % If implemented in Python +\stmodindex{spam} + + +% ==== 2. ==== +% Give a short overview of what the module does. +% If it is platform specific, mention this. +% Mention other important restrictions or general operating principles. +% For example: + +The \code{spam} module defines operations for handling cans of Spam. +It knows the four generally available Spam varieties and understands +both can sizes. + +Because spamification requires UNIX process management, the module is +only available on genuine UNIX systems. + + +% ==== 3. ==== +% List the public functions defined by the module. Begin with a +% standard phrase. You may also list the exceptions and other data +% items defined in the module, insofar as they are important for the +% user. + +The \code{spam} module defines the following functions: + +% ---- 3.1. ---- +% Redefine the ``indexsubitem'' macro to point to this module: + +\renewcommand{\indexsubitem}{(in module spam)} + +% ---- 3.2. ---- +% For each function, use a ``funcdesc'' block. This has exactly two +% parameters (each parameters is contained in a set of curly braces): +% the first parameter is the function name (this automatically +% generates an index entry); the second parameter is the function's +% argument list. If there are no arguments, use an empty pair of +% curly braces. If there is more than one argument, separate the +% arguments with backslash-comma. Optional parts of the parameter +% list are contained in \optional{...} (this generates a set of square +% brackets around its parameter). Arguments are automatically set in +% italics in the parameter list. Each argument should be mentioned at +% least once in the description; each usage (even inside \code{...}) +% should be enclosed in \var{...}. + +\begin{funcdesc}{open}{filename\optional{\, mode\, buffersize}} +Open the file \var{filename} as a can of Spam. The optional +\var{mode} and \var{buffersize} arguments specify the read-write mode +(\code{'r'} (default) or \code{'w'}) and the buffer size (default: +system dependent). +\end{funcdesc} + +% ---- 3.3. ---- +% Data items are described using a ``datadesc'' block. This has only +% one parameter: the item's name. + +\begin{datadesc}{cansize} +The default can size, in ounces. Legal values are 7 and 12. The +default varies per supermarket. This variable should not be changed +once the \code{open()} function has been called. +\end{datadesc} + +% --- 3.4. --- +% Exceptions are described using a ``excdesc'' block. This has only +% one parameter: the exception name. + +\begin{excdesc}{error} +Exception raised when an operation fails for a Spam specific reason. +The exception argument is a string describing the reason of the +failure. +\end{excdesc} + +% ---- 3.5. ---- +% There is no standard block type for classes. I generally use +% ``funcdesc'' blocks, since class instantiation looks very much like +% a function call. + + +% ==== 4. ==== +% Now is probably a good time for a complete example. (Alternatively, +% an example giving the flavor of the module may be given before the +% detailed list of functions.) + +Example: + +\begin{verbatim} +>>> import spam +>>> can = spam.open('/etc/passwd') +>>> can.empty() +>>> can.close() +\end{verbatim} + +% ==== 5. ==== +% If your module defines new object types (for a built-in module) or +% classes (for a module written in Python), you should list the +% methods and instance variables (if any) of each type or class in a +% separate subsection. It is important to redefine ``indexsubitem'' +% for each subsection. + +\subsection{Spam methods} + +Spam objects (returned by \code{open()} above) have the following +methods. + +\renewcommand{\indexsubitem}{(spam method)} + +\begin{funcdesc}{empty}{} +Empty the can into the trash. +\end{funcdesc} diff --git a/Doc/libtemplate.tex b/Doc/libtemplate.tex index 7465af8..5c702e5 100644 --- a/Doc/libtemplate.tex +++ b/Doc/libtemplate.tex @@ -1,40 +1,121 @@ -% Template for library sections. -% Replace text in ALL CAPS by your own text. -% Comments starting with %** give additional directions. - -%** Choose one of the following two section headings: -\section{Built-in module {\tt YOUR-MODULE-NAME}} % If written in C -\section{Standard module {\tt YOUR-MODULE-NAME}} % If written in Python - -PUT A SHORT INTRODUCTION AND DESCRIPTION OF THE MODULE HERE. - -%** change this sentence to taste: -The module defines the following variables and functions: - -\begin{description} - -\renewcommand{\indexsubitem}{(in module YOUR-MODULE-NAME)} - - -%** You can mix exceptions, variables and functions below; often it is a -%** good idea to alphabetize them all. - - -%** repeat the following for each exception: -\excitem{NAME} -DESCRIPTION OF THE EXCEPTION GOES HERE. - - -%** repeat the following for each variable (or constant): -\dataitem{NAME} -DESCRIPTION OF THE VARIABLE/CONSTANT GOES HERE. - - -%** repeat the following for each function: -\funcitem{NAME}{PARAMETERS} % Don't include the parentheses -DESCRIPTION OF THE FUNCTION GOES HERE. - - -\end{description} - -ADDITIONAL HINTS FOR USING THE MODULE MAY GO HERE. +% Template for a library manual section. +% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE + + +% ==== 1. ==== +% Choose one of the following section headers and index entries; +% \section{} generates the section header, +% \bimodindex{} or \stmodundex{} generates an index entry for this module + +\section{Built-in module \sectcode{spam}} % If implemented in C +\bimodindex[spam} + +\section{Standard module \sectcode{spam}} % If implemented in Python +\stmodindex{spam} + + +% ==== 2. ==== +% Give a short overview of what the module does. +% If it is platform specific, mention this. +% Mention other important restrictions or general operating principles. +% For example: + +The \code{spam} module defines operations for handling cans of Spam. +It knows the four generally available Spam varieties and understands +both can sizes. + +Because spamification requires UNIX process management, the module is +only available on genuine UNIX systems. + + +% ==== 3. ==== +% List the public functions defined by the module. Begin with a +% standard phrase. You may also list the exceptions and other data +% items defined in the module, insofar as they are important for the +% user. + +The \code{spam} module defines the following functions: + +% ---- 3.1. ---- +% Redefine the ``indexsubitem'' macro to point to this module: + +\renewcommand{\indexsubitem}{(in module spam)} + +% ---- 3.2. ---- +% For each function, use a ``funcdesc'' block. This has exactly two +% parameters (each parameters is contained in a set of curly braces): +% the first parameter is the function name (this automatically +% generates an index entry); the second parameter is the function's +% argument list. If there are no arguments, use an empty pair of +% curly braces. If there is more than one argument, separate the +% arguments with backslash-comma. Optional parts of the parameter +% list are contained in \optional{...} (this generates a set of square +% brackets around its parameter). Arguments are automatically set in +% italics in the parameter list. Each argument should be mentioned at +% least once in the description; each usage (even inside \code{...}) +% should be enclosed in \var{...}. + +\begin{funcdesc}{open}{filename\optional{\, mode\, buffersize}} +Open the file \var{filename} as a can of Spam. The optional +\var{mode} and \var{buffersize} arguments specify the read-write mode +(\code{'r'} (default) or \code{'w'}) and the buffer size (default: +system dependent). +\end{funcdesc} + +% ---- 3.3. ---- +% Data items are described using a ``datadesc'' block. This has only +% one parameter: the item's name. + +\begin{datadesc}{cansize} +The default can size, in ounces. Legal values are 7 and 12. The +default varies per supermarket. This variable should not be changed +once the \code{open()} function has been called. +\end{datadesc} + +% --- 3.4. --- +% Exceptions are described using a ``excdesc'' block. This has only +% one parameter: the exception name. + +\begin{excdesc}{error} +Exception raised when an operation fails for a Spam specific reason. +The exception argument is a string describing the reason of the +failure. +\end{excdesc} + +% ---- 3.5. ---- +% There is no standard block type for classes. I generally use +% ``funcdesc'' blocks, since class instantiation looks very much like +% a function call. + + +% ==== 4. ==== +% Now is probably a good time for a complete example. (Alternatively, +% an example giving the flavor of the module may be given before the +% detailed list of functions.) + +Example: + +\begin{verbatim} +>>> import spam +>>> can = spam.open('/etc/passwd') +>>> can.empty() +>>> can.close() +\end{verbatim} + +% ==== 5. ==== +% If your module defines new object types (for a built-in module) or +% classes (for a module written in Python), you should list the +% methods and instance variables (if any) of each type or class in a +% separate subsection. It is important to redefine ``indexsubitem'' +% for each subsection. + +\subsection{Spam methods} + +Spam objects (returned by \code{open()} above) have the following +methods. + +\renewcommand{\indexsubitem}{(spam method)} + +\begin{funcdesc}{empty}{} +Empty the can into the trash. +\end{funcdesc} diff --git a/Doc/templates/module.tex b/Doc/templates/module.tex index 7465af8..5c702e5 100644 --- a/Doc/templates/module.tex +++ b/Doc/templates/module.tex @@ -1,40 +1,121 @@ -% Template for library sections. -% Replace text in ALL CAPS by your own text. -% Comments starting with %** give additional directions. - -%** Choose one of the following two section headings: -\section{Built-in module {\tt YOUR-MODULE-NAME}} % If written in C -\section{Standard module {\tt YOUR-MODULE-NAME}} % If written in Python - -PUT A SHORT INTRODUCTION AND DESCRIPTION OF THE MODULE HERE. - -%** change this sentence to taste: -The module defines the following variables and functions: - -\begin{description} - -\renewcommand{\indexsubitem}{(in module YOUR-MODULE-NAME)} - - -%** You can mix exceptions, variables and functions below; often it is a -%** good idea to alphabetize them all. - - -%** repeat the following for each exception: -\excitem{NAME} -DESCRIPTION OF THE EXCEPTION GOES HERE. - - -%** repeat the following for each variable (or constant): -\dataitem{NAME} -DESCRIPTION OF THE VARIABLE/CONSTANT GOES HERE. - - -%** repeat the following for each function: -\funcitem{NAME}{PARAMETERS} % Don't include the parentheses -DESCRIPTION OF THE FUNCTION GOES HERE. - - -\end{description} - -ADDITIONAL HINTS FOR USING THE MODULE MAY GO HERE. +% Template for a library manual section. +% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE + + +% ==== 1. ==== +% Choose one of the following section headers and index entries; +% \section{} generates the section header, +% \bimodindex{} or \stmodundex{} generates an index entry for this module + +\section{Built-in module \sectcode{spam}} % If implemented in C +\bimodindex[spam} + +\section{Standard module \sectcode{spam}} % If implemented in Python +\stmodindex{spam} + + +% ==== 2. ==== +% Give a short overview of what the module does. +% If it is platform specific, mention this. +% Mention other important restrictions or general operating principles. +% For example: + +The \code{spam} module defines operations for handling cans of Spam. +It knows the four generally available Spam varieties and understands +both can sizes. + +Because spamification requires UNIX process management, the module is +only available on genuine UNIX systems. + + +% ==== 3. ==== +% List the public functions defined by the module. Begin with a +% standard phrase. You may also list the exceptions and other data +% items defined in the module, insofar as they are important for the +% user. + +The \code{spam} module defines the following functions: + +% ---- 3.1. ---- +% Redefine the ``indexsubitem'' macro to point to this module: + +\renewcommand{\indexsubitem}{(in module spam)} + +% ---- 3.2. ---- +% For each function, use a ``funcdesc'' block. This has exactly two +% parameters (each parameters is contained in a set of curly braces): +% the first parameter is the function name (this automatically +% generates an index entry); the second parameter is the function's +% argument list. If there are no arguments, use an empty pair of +% curly braces. If there is more than one argument, separate the +% arguments with backslash-comma. Optional parts of the parameter +% list are contained in \optional{...} (this generates a set of square +% brackets around its parameter). Arguments are automatically set in +% italics in the parameter list. Each argument should be mentioned at +% least once in the description; each usage (even inside \code{...}) +% should be enclosed in \var{...}. + +\begin{funcdesc}{open}{filename\optional{\, mode\, buffersize}} +Open the file \var{filename} as a can of Spam. The optional +\var{mode} and \var{buffersize} arguments specify the read-write mode +(\code{'r'} (default) or \code{'w'}) and the buffer size (default: +system dependent). +\end{funcdesc} + +% ---- 3.3. ---- +% Data items are described using a ``datadesc'' block. This has only +% one parameter: the item's name. + +\begin{datadesc}{cansize} +The default can size, in ounces. Legal values are 7 and 12. The +default varies per supermarket. This variable should not be changed +once the \code{open()} function has been called. +\end{datadesc} + +% --- 3.4. --- +% Exceptions are described using a ``excdesc'' block. This has only +% one parameter: the exception name. + +\begin{excdesc}{error} +Exception raised when an operation fails for a Spam specific reason. +The exception argument is a string describing the reason of the +failure. +\end{excdesc} + +% ---- 3.5. ---- +% There is no standard block type for classes. I generally use +% ``funcdesc'' blocks, since class instantiation looks very much like +% a function call. + + +% ==== 4. ==== +% Now is probably a good time for a complete example. (Alternatively, +% an example giving the flavor of the module may be given before the +% detailed list of functions.) + +Example: + +\begin{verbatim} +>>> import spam +>>> can = spam.open('/etc/passwd') +>>> can.empty() +>>> can.close() +\end{verbatim} + +% ==== 5. ==== +% If your module defines new object types (for a built-in module) or +% classes (for a module written in Python), you should list the +% methods and instance variables (if any) of each type or class in a +% separate subsection. It is important to redefine ``indexsubitem'' +% for each subsection. + +\subsection{Spam methods} + +Spam objects (returned by \code{open()} above) have the following +methods. + +\renewcommand{\indexsubitem}{(spam method)} + +\begin{funcdesc}{empty}{} +Empty the can into the trash. +\end{funcdesc} -- cgit v0.12