doc.tex 11.3 KB
Newer Older
pknaggs's avatar
pknaggs committed
1 2
% !TeX root = forth.tex

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
\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

The implementation-defined items in the following list represent
characteristics and choices left to the discretion of the
pknaggs's avatar
pknaggs committed
18
implementor, provided that the requirements of this standard are
19 20 21 22 23 24 25 26
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;

pknaggs's avatar
pknaggs committed
27
\item character editing of \wref{core:ACCEPT}{ACCEPT};
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46

\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});

pknaggs's avatar
pknaggs committed
47
\item display after input terminates in \wref{core:ACCEPT}{ACCEPT};
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97

\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 size of the keyboard terminal input buffer
	(\xref[Input buffers]{usage:inbuf});

pknaggs's avatar
pknaggs committed
98
\item size of the pictured numeric output string buffer 
99 100 101
	(\xref[Other transient regions]{usage:transient});

\item size of the scratch area whose address is returned by
pknaggs's avatar
pknaggs committed
102 103
	\wref{core:PAD}{PAD} \\
	(\xref[Other transient regions]{usage:transient});
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127

\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 values returned after arithmetic overflow
	(\xref[Other integer operations]{usage:intops});

\item whether the current definition can be found after
	\wref{core:DOES}{DOES>} (\wref{core::}{:}).

\end{itemize}



\subsection{Ambiguous conditions} % 4.1.2 ===========================
128
\label{doc:ambiguous}
129 130 131

A system shall document the system action taken upon each of the
general or specific ambiguous conditions identified in this
pknaggs's avatar
pknaggs committed
132
standard. See \xref[Possible actions on an ambiguous condition]{usage:ambiguous}.
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173

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

\begin{itemize}

\item a \emph{name} is neither a valid definition name nor a valid
	number during text interpretation (\xref[The Forth text
	interpreter]{usage:command});

\item 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,
	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 insufficient space in the dictionary;

pknaggs's avatar
pknaggs committed
174
\item interpreting a word with undefined interpretation semantics;
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241

\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});

242 243 244 245
\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)});
246 247 248 249 250 251 252 253

\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});

254 255
\item \wref{core:POSTPONE}{POSTPONE},
	\wref{core:[COMPILE]}{[COMPILE]},
256
	\wref{core:'}{'} or
257
	\wref{core:[']}{[']} applied to \wref{core:TO}{TO};
258 259 260 261 262 263 264 265 266 267 268 269 270

\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},
pknaggs's avatar
pknaggs committed
271
	 \wref{core:HOLD}{HOLD},
pknaggs's avatar
pknaggs committed
272
	 \wref{core:HOLDS}{},
pknaggs's avatar
pknaggs committed
273
	 \wref{core:SIGN}{SIGN});
274 275 276 277
\end{itemize}

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

278
\begin{itemize}
279
\item access to a deferred word, a word defined by \wref{core:DEFER}{DEFER},
pknaggs's avatar
pknaggs committed
280
	which has yet to be assigned to an \param{xt};
281 282

\item access to a deferred word, a word defined by \wref{core:DEFER}{DEFER},
pknaggs's avatar
pknaggs committed
283
	which was not defined by \wref{core:DEFER}{DEFER};
284 285 286

\item \wref{core:POSTPONE}{POSTPONE}, \wref{core:[COMPILE]}{[COMPILE]},
	\wref{core:[']}{[']} or \wref{core:'}{'} applied to \wref{core:ACTION-OF}{ACTION-OF}
pknaggs's avatar
pknaggs committed
287
	or \wref{core:IS}{IS};
288
\end{itemize}
289

pknaggs's avatar
pknaggs committed
290 291
% ==== X: Escaped Strings ====

292
\begin{itemize}
pknaggs's avatar
pknaggs committed
293
	\item \bs{x} is not followed by two hexadecimal characters (\wref{core:Seq}{});
pknaggs's avatar
pknaggs committed
294 295
	\item a \bs{} is placed before any character, other than those defined in
		\wref{core:Seq}{}.
296
\end{itemize}
pknaggs's avatar
pknaggs committed
297

298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324

\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
325
\label{doc:env}
326 327 328 329 330 331 332 333 334 335 336 337

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
pknaggs's avatar
pknaggs committed
338
	in a received string (\wref{core:ACCEPT}{ACCEPT});
339 340 341 342

\item relying on a particular rounding direction
	(\xref[Integer division]{usage:div});

pknaggs's avatar
pknaggs committed
343
\item requiring a particular number representation and arithmetic \\
344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362
	(\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});

pknaggs's avatar
pknaggs committed
363 364
\item using definition names of more than 31 characters in length
	(\xref{usage:names});
pknaggs's avatar
pknaggs committed
365

366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381
\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}