doc.tex

% !TeX root = forth.tex
% !TeX spellcheck = en_US
% !TeX program = pdflatex

\chapter{Documentation requirements}
\label{doc}

When it is impossible or infeasible for a system or program to
define a particular behavior itself, it is permissible to state
that the behavior is unspecifiable and to explain the circumstances
and reasons why this is so.

\section{System documentation} % 4.1
\label{doc:system}

\subsection{Implementation-defined options} % 4.1.1
\label{doc:imp}

The implementation-defined items in the following list represent
characteristics and choices left to the discretion of the
implementor, provided that the requirements of this standard are
met. A system shall document the values for, or behaviors of, each
item.

\begin{itemize}
\item aligned address requirements \xref[Addresses]{usage:addr};
%
\item behavior of \wref{core:EMIT}{EMIT} for non-graphic characters;
%
\item character editing of \wref{core:ACCEPT}{ACCEPT};
%
\item character set (\xref[Character types]{usage:char},
	\wref{core:EMIT}{EMIT}, \wref{core:KEY}{KEY});
%
\item character-aligned address requirements
	(\xref[Addresses]{usage:addr});
%
\item character-set-extensions matching characteristics
	(\xref[Finding definition names]{usage:find});
%
\item conditions under which control characters match a space
	delimiter (\xref[Delimiters]{usage:delim});
%
\item format of the control-flow stack
	(\xref[Control-flow stack]{usage:controlstack});
%
\item conversion of digits larger than thirty-five
	(\xref[Digit conversion]{usage:digits});
%
\item display after input terminates in \wref{core:ACCEPT}{ACCEPT};
%
\item exception abort sequence (as in \wref{core:ABORTq}{ABORT"});
%
\item input line terminator (\xref[User input device]{usage:input});
%
\item maximum size of a counted string, in characters
	(\xref[Counted strings]{usage:cstring}, \wref{core:WORD}{WORD});
%
\item maximum size of a parsed string
	(\xref[Parsing]{usage:parsing});
%
\item maximum size of a definition name, in characters
	(\xref[Definition names]{usage:names});
%
\item maximum string length for
	\wref{core:ENVIRONMENTq}{ENVIRONMENT?}, in characters;
%
\item method of selecting \xref[User input device]{usage:input};
%
\item method of selecting \xref[User output device]{usage:output};
%
\item methods of dictionary compilation
	(\xref[The Forth dictionary]{usage:dict});
%
\item number of bits in one address unit
	(\xref[Addresses]{usage:addr});
%
\item number representation and arithmetic
	(\xref[Internal number representation]{usage:number});
%
\item ranges for \param{n}, \param{+n}, \param{u}, \param{d},
	\param{+d}, and \param{ud}
	(\xref[Single-cell types]{usage:cell},
	 \xref[Cell-pair types]{usage:2cell});
%
\item read-only data-space regions
	(\xref[Data space]{usage:dataspace});
%
\item size of buffer at \wref{core:WORD}{WORD}
	(\xref[Other transient regions]{usage:transient});
%
\item size of one cell in address units
	(\xref[Single-cell types]{usage:cell});
%
\item size of one character in address units
	(\xref[Character types]{usage:char});
%
\item number of string buffers provided (\xref{usage:"literal});
%
\item size of string buffer used by \xref{usage:"literal};
%
\item size of the keyboard terminal input buffer
	(\xref[Input buffers]{usage:inbuf});
%
\item size of the pictured numeric output string buffer 
	(\xref[Other transient regions]{usage:transient});
%
\item size of the scratch area whose address is returned by
	\wref{core:PAD}{PAD} \\
	(\xref[Other transient regions]{usage:transient});
%
\item system case-sensitivity characteristics
	(\xref[Finding definition names]{usage:find});
%
\item system prompt (\xref[The Forth text interpreter]{usage:dict},
	\wref{core:QUIT}{QUIT});
%
\item type of division rounding (\xref[Integer division]{usage:div},
	\wref{core:*/}{*/}, \wref{core:*/MOD}{*/MOD}, \wref{core:/}{/},
	\wref{core:/MOD}{/MOD}, \wref{core:MOD}{MOD});
%
\item values of \wref{core:STATE}{STATE} when true;
%
\item whether the current definition can be found after
	\wref{core:DOES}{DOES>} (\wref{core::}{:}).

\end{itemize}


\subsection{Ambiguous conditions} % 4.1.2 ===========================
\label{doc:ambiguous}

A system shall document the system action taken upon each of the
general or specific ambiguous conditions identified in this
standard. See \xref[Possible actions on an ambiguous condition]{usage:ambiguous}.

The following general ambiguous conditions could occur because of a
combination of factors:

\begin{itemize}
\item \remove{ed19}{a \emph{name} is neither a valid definition name nor a valid
	number during text interpretation} (\xref[The Forth text
	interpreter]{usage:command});
%
\item \remove{ed19}{a definition name exceeded the maximum length allowed}
	(\xref[Definition names]{usage:names});
%
\item addressing a region not listed in \xref[Data Space]{usage:dataspace};
%
\item argument type incompatible with specified input parameter,
	\remove{ed19}{e.g., passing a \emph{flag} to a word expecting an \emph{n}}
	(\xref[Data types]{usage:data});
%
\item attempting to obtain the execution token, (e.g., with
	\wref{core:'}{'}, \wref{core:FIND}{FIND}, etc. of a definition
	with undefined interpretation semantics;
%
\item dividing by zero
	(\wref{core:*/}{*/},
	 \wref{core:*/MOD}{*/MOD},
	 \wref{core:/}{/},
	 \wref{core:/MOD}{/MOD},
	 \wref{core:FM/MOD}{FM/MOD},
	 \wref{core:MOD}{MOD},
	 \wref{core:SM/REM}{SM/REM},
	 \wref{core:UM/MOD}{UM/MOD},
	 \wref{double:M*/}{M*/});
%
\item insufficient data-stack space or return-stack space (stack
	overflow);
%
\item insufficient space for loop-control parameters;
%
\item \remove{ed19}{insufficient space in the dictionary;}
%
\item interpreting a word with undefined interpretation semantics;
%
\item modifying the contents of the input buffer or a string literal
	(\xref[Text-literal regions]{usage:"literal},
	\xref[Input buffers]{usage:inbuf});
%
\item overflow of a pictured numeric output string;
%
\item parsed string overflow;
%
\item producing a result out of range, e.g., multiplication
	(using \word{*}) results in a value too big to be represented by
	a single-cell integer
	(\wref{core:*}{*},
	 \wref{core:*/}{*/},
	 \wref{core:*/MOD}{*/MOD},
	 \wref{core:toNUMBER}{>NUMBER},
	 \wref{core:FM/MOD}{FM/MOD},
	 \wref{core:SM/REM}{SM/REM},
	 \wref{core:UM/MOD}{UM/MOD},
	 \wref{double:M*/}{M*/});
%
\item reading from an empty data stack or return stack
	(stack underflow);
%
\item unexpected end of input buffer, resulting in an attempt to
	use a zero-length string as a \emph{name}.
\end{itemize}


The following specific ambiguous conditions are noted in the
glossary entries of the relevant words:

\begin{itemize}
\item \word{toIN} greater than size of input buffer
	(\xref[Parsing]{usage:parsing});
%
\item \wref{core:RECURSE}{RECURSE} appears after
	\wref{core:DOES}{DOES>};
%
\item argument input source different than current input source for
	\wref{core:RESTORE-INPUT}{RESTORE-INPUT};
%
\item data space containing definitions is de-allocated
	(\xref[Contiguous regions]{usage:contiguous});
%
\item data space read/write with incorrect alignment
	(\xref[Address alignment]{usage:aaddr});
%
\item data-space pointer not properly aligned
	(\wref{core:,}{,}, \wref{core:C,}{C,});
%
\item less than \param{u}+2 stack items (\wref{core:PICK}{PICK},
	\wref{core:ROLL}{ROLL});
%
\item loop-control parameters not available
	(\wref{core:+LOOP}{+LOOP},
	 \wref{core:I}{I},
	 \wref{core:J}{J},
	 \wref{core:LEAVE}{LEAVE},
	 \wref{core:LOOP}{LOOP},
	 \wref{core:UNLOOP}{UNLOOP});
%
\item most recent definition does not have a \emph{name}
	(\wref{core:IMMEDIATE}{IMMEDIATE});
%
\item \wref{core:TO}{TO} not followed directly by a \emph{name}
	defined by a word with ``\word{TO} \emph{name} runtime''
	semantics (\wref{core:VALUE}{VALUE} and
	\wref{local:LOCAL}{(LOCAL)});
%
\item \emph{name} not found \wref{core:'}{'},
	\wref{core:POSTPONE}{POSTPONE}, \wref{core:[']}{[']},
	\wref{core:[COMPILE]}{[COMPILE]});
%
\item parameters are not of the same type \wref{core:DO}{DO},
	\wref{core:qDO}{?DO}, \wref{core:WITHIN}{WITHIN});
%
\item \wref{core:POSTPONE}{POSTPONE},
	\wref{core:[COMPILE]}{[COMPILE]},
	\wref{core:'}{'} or
	\wref{core:[']}{[']} applied to \wref{core:TO}{TO};
%
\item string longer than a counted string returned by
	\wref{core:WORD}{WORD};
%
\item $u$ greater than or equal to the number of bits in a cell
	(\wref{core:LSHIFT}{LSHIFT}, \wref{core:RSHIFT}{RSHIFT});
%
\item word not defined via \wref{core:CREATE}{CREATE}
	(\wref{core:toBODY}{>BODY}, \wref{core:DOES}{DOES>});
%
\item words improperly used outside
	\wref{core:num-start}{<\num} and \wref{core:num-end}{\num>}
	(\wref{core:num}{\num}, \wref{core:numS}{\num{}S},
	 \wref{core:HOLD}{HOLD},
	 \wref{core:HOLDS}{},
	 \wref{core:SIGN}{SIGN});
\end{itemize}

% ==== X:Deferred ====

\begin{itemize}
\item access to a deferred word, a word defined by \wref{core:DEFER}{DEFER},
	which has yet to be assigned to an \param{xt};
%
\item access to a deferred word, a word defined by \wref{core:DEFER}{DEFER},
	which was not defined by \wref{core:DEFER}{DEFER};
%
\item \wref{core:POSTPONE}{POSTPONE}, \wref{core:[COMPILE]}{[COMPILE]},
	\wref{core:[']}{[']} or \wref{core:'}{'} applied to \wref{core:ACTION-OF}{ACTION-OF}
	or \wref{core:IS}{IS};
\end{itemize}

% ==== X: Escaped Strings ====

\begin{itemize}
	\item \bs{x} is not followed by two hexadecimal characters (\wref{core:Seq}{});
	\item a \bs{} is placed before any character, other than those defined in
		\wref{core:Seq}{}.
\end{itemize}


\subsection{Other system documentation} % 4.1.3

A system shall provide the following information:

\begin{itemize}
\item list of non-standard words using \wref{core:PAD}{PAD}
	(\xref[Other transient regions]{usage:transient});
%
\item operator's terminal facilities available;
%
\item program data space available, in address units;
%
\item return stack space available, in cells;
%
\item stack space available, in cells;
%
\item system dictionary space required, in address units.
\end{itemize}



\section{Program documentation} % 4.2 ===============================
\label{doc:program}

\subsection{Environmental dependencies} % 4.2.1
\label{doc:env}

A program shall document the following environmental dependencies,
where they apply, and should document other known environmental
dependencies:

\begin{itemize}
\item considering the pictured numeric output string buffer a fixed
	area with unchanging access parameters
	(\xref[Other transient regions]{usage:transient});
%
\item depending on the presence or absence of non-graphic characters
	in a received string (\wref{core:ACCEPT}{ACCEPT});
%
\item relying on a particular rounding direction
	(\xref[Integer division]{usage:div});
%
\item requiring a particular number representation and arithmetic \\
	(\xref[Internal number representation]{usage:number});
%
\item requiring non-standard words or techniques
	(\xref[Usage requirements]{usage});
%
\item requiring the ability to send or receive control characters
	(\xref[Control characters]{usage:control},
	\wref{core:KEY}{KEY});
%
\item using control characters to perform specific functions
	\wref{core:EMIT}{EMIT}, \wref{core:TYPE}{TYPE});
%
\item using flags as arithmetic operands
	(\xref[Flags]{usage:flags});
%
\item using lower case for standard definition names or depending
	on the case sensitivity of a system
	(\xref[Definition names]{usage:names});
%
\item using definition names of more than 31 characters in length
	(\xref{usage:names});
%
\item using the graphic character with a value of hex 24
	(\xref[Graphic characters]{usage:ASCII}).
\end{itemize}


\subsection{Other program documentation} % 4.2.2

A program shall also document:

\begin{itemize}
\item minimum operator's terminal facilities required;
%
\item whether a Standard System exists after the program is loaded.
\end{itemize}