doc.tex 11.3 KB
 pknaggs committed Sep 28, 2014 1 2 % !TeX root = forth.tex  pknaggs committed Aug 23, 2007 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 committed Oct 26, 2013 18 implementor, provided that the requirements of this standard are  pknaggs committed Aug 23, 2007 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 committed Mar 01, 2011 27 \item character editing of \wref{core:ACCEPT}{ACCEPT};  pknaggs committed Aug 23, 2007 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 committed Mar 01, 2011 47 \item display after input terminates in \wref{core:ACCEPT}{ACCEPT};  pknaggs committed Aug 23, 2007 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 committed Oct 30, 2010 98 \item size of the pictured numeric output string buffer  pknaggs committed Aug 23, 2007 99 100 101  (\xref[Other transient regions]{usage:transient}); \item size of the scratch area whose address is returned by  pknaggs committed Oct 30, 2010 102 103  \wref{core:PAD}{PAD} \\ (\xref[Other transient regions]{usage:transient});  pknaggs committed Aug 23, 2007 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 ===========================  pknaggs committed Aug 21, 2009 128 \label{doc:ambiguous}  pknaggs committed Aug 23, 2007 129 130 131  A system shall document the system action taken upon each of the general or specific ambiguous conditions identified in this  pknaggs committed Oct 26, 2013 132 standard. See \xref[Possible actions on an ambiguous condition]{usage:ambiguous}.  pknaggs committed Aug 23, 2007 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 committed Nov 18, 2014 174 \item interpreting a word with undefined interpretation semantics;  pknaggs committed Aug 23, 2007 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});  pknaggs committed Oct 22, 2007 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)});  pknaggs committed Aug 23, 2007 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});  pknaggs committed Oct 22, 2007 254 255 \item \wref{core:POSTPONE}{POSTPONE}, \wref{core:[COMPILE]}{[COMPILE]},  pknaggs committed Aug 23, 2007 256  \wref{core:'}{'} or  pknaggs committed Oct 22, 2007 257  \wref{core:[']}{[']} applied to \wref{core:TO}{TO};  pknaggs committed Aug 23, 2007 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 committed Oct 30, 2010 271  \wref{core:HOLD}{HOLD},  pknaggs committed Mar 01, 2011 272  \wref{core:HOLDS}{},  pknaggs committed Nov 18, 2014 273  \wref{core:SIGN}{SIGN});  pknaggs committed Aug 23, 2007 274 275 276 277 \end{itemize} % ==== X:Deferred ====  pknaggs committed Oct 31, 2012 278 \begin{itemize}  pknaggs committed Aug 23, 2007 279 \item access to a deferred word, a word defined by \wref{core:DEFER}{DEFER},  pknaggs committed Nov 18, 2014 280  which has yet to be assigned to an \param{xt};  pknaggs committed Aug 23, 2007 281 282  \item access to a deferred word, a word defined by \wref{core:DEFER}{DEFER},  pknaggs committed Nov 18, 2014 283  which was not defined by \wref{core:DEFER}{DEFER};  pknaggs committed Aug 23, 2007 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 committed Nov 18, 2014 287  or \wref{core:IS}{IS};  pknaggs committed Oct 31, 2012 288 \end{itemize}  pknaggs committed Aug 23, 2007 289   pknaggs committed Oct 30, 2010 290 291 % ==== X: Escaped Strings ====  pknaggs committed Oct 31, 2012 292 \begin{itemize}  pknaggs committed Nov 18, 2014 293  \item \bs{x} is not followed by two hexadecimal characters (\wref{core:Seq}{});  pknaggs committed Mar 01, 2011 294 295  \item a \bs{} is placed before any character, other than those defined in \wref{core:Seq}{}.  pknaggs committed Oct 31, 2012 296 \end{itemize}  pknaggs committed Mar 22, 2009 297   pknaggs committed Aug 23, 2007 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  pknaggs committed Aug 21, 2009 325 \label{doc:env}  pknaggs committed Aug 23, 2007 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 committed Mar 01, 2011 338  in a received string (\wref{core:ACCEPT}{ACCEPT});  pknaggs committed Aug 23, 2007 339 340 341 342  \item relying on a particular rounding direction (\xref[Integer division]{usage:div});  pknaggs committed Oct 30, 2010 343 \item requiring a particular number representation and arithmetic \\  pknaggs committed Aug 23, 2007 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 committed Sep 27, 2010 363 364 \item using definition names of more than 31 characters in length (\xref{usage:names});  pknaggs committed Mar 13, 2010 365   pknaggs committed Aug 23, 2007 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}