doc.tex 11.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
\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
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;

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

\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
45
\item display after input terminates in \wref{core:ACCEPT}{ACCEPT};
46 47 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

\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
96
\item size of the pictured numeric output string buffer 
97 98 99
	(\xref[Other transient regions]{usage:transient});

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

\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 ===========================
126
\label{doc:ambiguous}
127 128 129 130 131 132 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 174 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

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 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;

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

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

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

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

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

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

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

\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}.
286
\end{itemize}
287

pknaggs's avatar
pknaggs committed
288 289
% ==== X: Escaped Strings ====

290
\begin{itemize}
pknaggs's avatar
pknaggs committed
291 292 293
	\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}{}.
294
\end{itemize}
pknaggs's avatar
pknaggs committed
295

296 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

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

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
336
	in a received string (\wref{core:ACCEPT}{ACCEPT});
337 338 339 340

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

pknaggs's avatar
pknaggs committed
341
\item requiring a particular number representation and arithmetic \\
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360
	(\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
361 362
\item using definition names of more than 31 characters in length
	(\xref{usage:names});
pknaggs's avatar
pknaggs committed
363

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