DPANS4.HTM (13649B)
1 <HTML><HEAD> 2 <TITLE>DPANS94</TITLE> 3 <link disabled rel="stylesheet" href="mpexc6.css"> 4 <style>@import url(mpexc6.css);</style> 5 </head> 6 7 <BODY> 8 <table width=100%> 9 <tr> 10 <td align=left> 11 <a href=dpans3.htm><img src=left.gif 12 width=26 height=26 align=ALIGN border=0></a> 13 <a href=dpans5.htm><img src=right.gif 14 width=26 height=26 align=ALIGN border=0></a> 15 </td> 16 <td align=right> 17 <a href=dpans.htm#toc><img src=up.gif 18 width=26 height=26 align=ALIGN border=0></a> 19 <a name=4.>Table of Contents</a> 20 </td> 21 </tr> 22 </table> 23 <p> 24 <hr size=4> 25 26 <H1>4. Documentation requirements</H1> 27 28 When it is impossible or infeasible for a system or program to define a 29 particular behavior itself, it is permissible to state that the behavior 30 is unspecifiable and to explain the circumstances and reasons why this is so. 31 32 <P> 33 34 <hr> 35 <A name=4.1> 36 <H2>4.1 System documentation</H2> 37 </a> 38 39 40 <hr> 41 <A name=4.1.1> 42 <H3>4.1.1 Implementation-defined options</H3> 43 </a> 44 45 The implementation-defined items in the following list represent 46 characteristics and choices left to the discretion of the implementor, 47 provided that the requirements of this Standard are met. A system shall 48 document the values for, or behaviors of, each item. 49 50 <UL> 51 <LI>aligned address requirements 52 (<a href=dpans3.htm#3.1.3.3>3.1.3.3</a> Addresses); 53 <LI>behavior of 54 <a href=dpans6.htm#6.1.1320>6.1.1320</a> EMIT for non-graphic characters; 55 <LI>character editing of 56 <a href=dpans6.htm#6.1.0695>6.1.0695</a> ACCEPT and 57 <a href=dpans6.htm#6.2.1390>6.2.1390</a> EXPECT; 58 <LI>character set 59 (<a href=dpans3.htm#3.1.2>3.1.2</a> Character types, 60 <a href=dpans6.htm#6.1.1320>6.1.1320</a> EMIT, 61 <a href=dpans6.htm#6.1.1750>6.1.1750</a> KEY); 62 <LI>character-aligned address requirements 63 (<a href=dpans3.htm#3.1.3.3>3.1.3.3</a> Addresses); 64 <LI>character-set-extensions matching characteristics 65 (<a href=dpans3.htm#3.4.2>3.4.2</a> Finding 66 definition names); 67 <LI>conditions under which control characters match a space delimiter 68 (<a href=dpans3.htm#3.4.1.1>3.4.1.1</a> Delimiters); 69 <LI>format of the control-flow stack 70 (<a href=dpans3.htm#3.2.3.2>3.2.3.2</a> Control-flow stack); 71 <LI>conversion of digits larger than thirty-five 72 (<a href=dpans3.htm#3.2.1.2>3.2.1.2</a> Digit 73 conversion); 74 <LI>display after input terminates in 75 <a href=dpans6.htm#6.1.0695>6.1.0695</a> ACCEPT and 76 <a href=dpans6.htm#6.2.1390>6.2.1390</a> EXPECT; 77 <LI>exception abort sequence (as in 78 <a href=dpans6.htm#6.1.0680>6.1.0680</a> ABORT"); 79 <LI>input line terminator 80 (<a href=dpans3.htm#3.2.4.1>3.2.4.1</a> User input device); 81 <LI>maximum size of a counted string, in characters 82 (<a href=dpans3.htm#3.1.3.4>3.1.3.4</a> Counted 83 strings, 84 <a href=dpans6.htm#6.1.2450>6.1.2450</a> WORD); 85 <LI>maximum size of a parsed string 86 (<a href=dpans3.htm#3.4.1>3.4.1</a> Parsing); 87 <LI>maximum size of a definition name, in characters 88 (<a href=dpans3.htm#3.3.1.2>3.3.1.2</a> Definition 89 names); 90 <LI>maximum string length for 91 <a href=dpans6.htm#6.1.1345>6.1.1345</a> ENVIRONMENT?, in characters; 92 <LI>method of selecting 93 <a href=dpans3.htm#3.2.4.1>3.2.4.1</a> User input device; 94 <LI>method of selecting 95 <a href=dpans3.htm#3.2.4.2>3.2.4.2</a> User output device; 96 <LI>methods of dictionary compilation 97 (<a href=dpans3.htm#3.3>3.3</a> The Forth dictionary); 98 <LI>number of bits in one address unit 99 (<a href=dpans3.htm#3.1.3.3>3.1.3.3</a> Addresses); 100 <LI>number representation and arithmetic 101 (<a href=dpans3.htm#3.2.1.1>3.2.1.1</a> Internal number 102 representation); 103 <LI>ranges for n, +n, u, d, +d, and ud 104 (<a href=dpans3.htm#3.1.3>3.1.3</a> Single-cell types, 105 <a href=dpans3.htm#3.1.4>3.1.4</a> Cell-pair types); 106 <LI>read-only data-space regions 107 (<a href=dpans3.htm#3.3.3>3.3.3</a> Data space); 108 <LI>size of buffer at 109 <a href=dpans6.htm#6.1.2450>6.1.2450</a> WORD 110 (<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions); 111 <LI>size of one cell in address units 112 (<a href=dpans3.htm#3.1.3>3.1.3</a> Single-cell types); 113 <LI>size of one character in address units 114 (<a href=dpans3.htm#3.1.2>3.1.2</a> Character types); 115 <LI>size of the keyboard terminal input buffer 116 (<a href=dpans3.htm#3.3.3.5>3.3.3.5</a> Input buffers); 117 <LI>size of the pictured numeric output string buffer 118 (<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other 119 transient regions); 120 <LI>size of the scratch area whose address is returned by 121 <a href=dpans6.htm#6.2.2000>6.2.2000</a> PAD 122 (<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions); 123 <LI>system case-sensitivity characteristics 124 (<a href=dpans3.htm#3.4.2>3.4.2</a> Finding definition 125 names); 126 <LI>system prompt 127 (<a href=dpans3.htm#3.4>3.4</a> The Forth text interpreter, 128 <a href=dpans6.htm#6.1.2050>6.1.2050</a> QUIT); 129 <LI>type of division rounding 130 (<a href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division, 131 <a href=dpans6.htm#6.1.0100>6.1.0100</a> */, 132 <a href=dpans6.htm#6.1.0110>6.1.0110</a> */MOD, 133 <a href=dpans6.htm#6.1.0230>6.1.0230</a> /, 134 <a href=dpans6.htm#6.1.0240>6.1.0240</a> /MOD, 135 <a href=dpans6.htm#6.1.1890>6.1.1890</a> MOD); 136 <LI>values of 137 <a href=dpans6.htm#6.1.2250>6.1.2250</a> STATE when true; 138 <LI>values returned after arithmetic overflow 139 (<a href=dpans3.htm#3.2.2.2>3.2.2.2</a> Other integer 140 operations); 141 <LI>whether the current definition can be found after 142 <a href=dpans6.htm#6.1.1250>6.1.1250</a> DOES> 143 (<a href=dpans6.htm#6.1.0450>6.1.0450</a> :). 144 </UL> 145 146 <P> 147 148 <hr> 149 <A name=4.1.2> 150 <H3>4.1.2 Ambiguous conditions</H3> 151 </a> 152 153 A system shall document the system action taken upon each of the general or 154 specific ambiguous conditions identified in this Standard. See 155 <a href=dpans3.htm#3.4.4>3.4.4</a> Possible 156 actions on an ambiguous condition. 157 158 <P> 159 160 The following general ambiguous conditions could occur because of a 161 combination of factors: 162 163 <UL> 164 <LI>a name is neither a valid definition name nor a valid number during 165 text interpretation 166 (<a href=dpans3.htm#3.4>3.4</a> The Forth text interpreter); 167 <LI>a definition name exceeded the maximum length allowed 168 (<a href=dpans3.htm#3.3.1.2>3.3.1.2</a> 169 Definition names); 170 <LI>addressing a region not listed in 171 <a href=dpans3.htm#3.3.3>3.3.3</a> Data Space; 172 <LI>argument type incompatible with specified input parameter, e.g., 173 passing a flag to a word expecting an n 174 (<a href=dpans3.htm#3.1>3.1</a> Data types); 175 <LI>attempting to obtain the execution token, (e.g., with 176 <a href=dpans6.htm#6.1.0070>6.1.0070</a> ', 177 <a href=dpans6.htm#6.1.1550>6.1.1550</a> FIND, 178 etc.) of a definition with undefined interpretation semantics; 179 <LI>dividing by zero 180 (<a href=dpans6.htm#6.1.0100>6.1.0100</a> */, 181 <a href=dpans6.htm#6.1.0110>6.1.0110</a> */MOD, 182 <a href=dpans6.htm#6.1.0230>6.1.0230</a> /, 183 <a href=dpans6.htm#6.1.0240>6.1.0240</a> /MOD, 184 <a href=dpans6.htm#6.1.1561>6.1.1561</a> FM/MOD, 185 <a href=dpans6.htm#6.1.1890>6.1.1890</a> MOD, 186 <a href=dpans6.htm#6.1.2214>6.1.2214</a> SM/REM, 187 <a href=dpans6.htm#6.1.2370>6.1.2370</a> UM/MOD, 188 <a href=dpans8.htm#8.6.1.1820>8.6.1.1820</a> M*/); 189 <LI>insufficient data-stack space or return-stack space (stack overflow); 190 <LI>insufficient space for loop-control parameters; 191 <LI>insufficient space in the dictionary; 192 <LI>interpretating a word with undefined interpretation semantics; 193 <LI>modifying the contents of the input buffer or a string literal 194 (<a href=dpans3.htm#3.3.3.4>3.3.3.4</a> Text-literal regions, 195 <a href=dpans3.htm#3.3.3.5>3.3.3.5</a> Input buffers); 196 <LI>overflow of a pictured numeric output string; 197 <LI>parsed string overflow; 198 <LI>producing a result out of range, e.g., multiplication (using *) 199 results in a value too big to be represented by a single-cell integer 200 (<a href=dpans6.htm#6.1.0090>6.1.0090</a> *, 201 <a href=dpans6.htm#6.1.0100>6.1.0100</a> */, 202 <a href=dpans6.htm#6.1.0110>6.1.0110</a> */MOD, 203 <a href=dpans6.htm#6.1.0570>6.1.0570</a> >NUMBER, 204 <a href=dpans6.htm#6.1.1561>6.1.1561</a> FM/MOD, 205 <a href=dpans6.htm#6.1.2214>6.1.2214</a> SM/REM, 206 <a href=dpans6.htm#6.1.2370>6.1.2370</a> UM/MOD, 207 <a href=dpans6.htm#6.2.0970>6.2.0970</a> CONVERT, 208 <a href=dpans8.htm#8.6.1.1820>8.6.1.1820</a> M*/); 209 <LI>reading from an empty data stack or return stack (stack underflow); 210 <LI>unexpected end of input buffer, resulting in an attempt to use a 211 zero-length string as a name; 212 </UL> 213 <P> 214 215 The following specific ambiguous conditions are noted in the glossary entries 216 of the relevant words: 217 218 <UL> 219 <LI> 220 <a href=dpans6.htm#6.1.0560>>IN</a> 221 greater than size of input buffer 222 (<a href=dpans3.htm#3.4.1>3.4.1</a> Parsing); 223 <LI> 224 <a href=dpans6.htm#6.1.2120>6.1.2120</a> RECURSE appears after 225 <a href=dpans6.htm#6.1.1250>6.1.1250</a> DOES>; 226 <LI>argument input source different than current input source for 227 <a href=dpans6.htm#6.2.2148>6.2.2148</a> RESTORE-INPUT; 228 <LI>data space containing definitions is de-allocated 229 (<a href=dpans3.htm#3.3.3.2>3.3.3.2</a> Contiguous regions); 230 <LI>data space read/write with incorrect alignment 231 (<a href=dpans3.htm#3.3.3.1>3.3.3.1</a> Address alignment); 232 <LI>data-space pointer not properly aligned 233 (<a href=dpans6.htm#6.1.0150>6.1.0150</a> ,, 234 <a href=dpans6.htm#6.1.0860>6.1.0860</a> C,); 235 <LI>less than u+2 stack items 236 (<a href=dpans6.htm#6.2.2030>6.2.2030</a> PICK, 237 <a href=dpans6.htm#6.2.2150>6.2.2150</a> ROLL); 238 <LI>loop-control parameters not available ( 239 <a href=dpans6.htm#6.1.0140>6.1.0140</a> +LOOP, 240 <a href=dpans6.htm#6.1.1680>6.1.1680</a> I, 241 <a href=dpans6.htm#6.1.1730>6.1.1730</a> J, 242 <a href=dpans6.htm#6.1.1760>6.1.1760</a> LEAVE, 243 <a href=dpans6.htm#6.1.1800>6.1.1800</a> LOOP, 244 <a href=dpans6.htm#6.1.2380>6.1.2380</a> UNLOOP); 245 <LI>most recent definition does not have a name 246 (<a href=dpans6.htm#6.1.1710>6.1.1710</a> IMMEDIATE); 247 <LI>name not defined by 248 <a href=dpans6.htm#6.2.2405>6.2.2405</a> VALUE used by 249 <a href=dpans6.htm#6.2.2295>6.2.2295</a> TO; 250 <LI>name not found 251 (<a href=dpans6.htm#6.1.0070>6.1.0070</a> ', 252 <a href=dpans6.htm#6.1.2033>6.1.2033</a> POSTPONE, 253 <a href=dpans6.htm#6.1.2510>6.1.2510</a> ['], 254 <a href=dpans6.htm#6.2.2530>6.2.2530</a> [COMPILE]); 255 <LI>parameters are not of the same type 256 (<a href=dpans6.htm#6.1.1240>6.1.1240</a> DO, 257 <a href=dpans6.htm#6.2.0620>6.2.0620</a> ?DO, 258 <a href=dpans6.htm#6.2.2440>6.2.2440</a> WITHIN); 259 <LI> 260 <a href=dpans6.htm#6.1.2033>6.1.2033</a> POSTPONE or 261 <a href=dpans6.htm#6.2.2530>6.2.2530</a> [COMPILE] applied to 262 <a href=dpans6.htm#6.2.2295>6.2.2295</a> TO; 263 <LI>string longer than a counted string returned by 264 <a href=dpans6.htm#6.1.2450>6.1.2450</a> WORD; 265 <LI>u greater than or equal to the number of bits in a cell 266 (<a href=dpans6.htm#6.1.1805>6.1.1805</a> LSHIFT, 267 <a href=dpans6.htm#6.1.2162>6.1.2162</a> RSHIFT); 268 <LI>word not defined via 269 <a href=dpans6.htm#6.1.1000>6.1.1000</a> CREATE 270 (<a href=dpans6.htm#6.1.0550>6.1.0550</a> >BODY, 271 <a href=dpans6.htm#6.1.1250>6.1.1250</a> DOES>); 272 <LI>words improperly used outside 273 <a href=dpans6.htm#6.1.0490>6.1.0490</a> <# and 274 <a href=dpans6.htm#6.1.0040>6.1.0040</a> #> 275 (<a href=dpans6.htm#6.1.0030>6.1.0030</a> #, 276 <a href=dpans6.htm#6.1.0050>6.1.0050</a> #S, 277 <a href=dpans6.htm#6.1.1670>6.1.1670</a> HOLD, 278 <a href=dpans6.htm#6.1.2210>6.1.2210</a> SIGN). 279 </UL> 280 281 <P> 282 283 <hr> 284 <A name=4.1.3> 285 <H3>4.1.3 Other system documentation</H3> 286 </a> 287 288 A system shall provide the following information: 289 <P> 290 291 <UL> 292 <LI>list of non-standard words using 293 <a href=dpans6.htm#6.2.2000>6.2.2000</a> PAD 294 (<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient 295 regions); 296 <LI>operator's terminal facilities available; 297 <LI>program data space available, in address units; 298 <LI>return stack space available, in cells; 299 <LI>stack space available, in cells; 300 <LI>system dictionary space required, in address units. 301 </UL> 302 303 <P> 304 305 <hr> 306 <A name=4.2> 307 <H2>4.2 Program documentation</H2> 308 </a> 309 310 311 <hr> 312 <A name=4.2.1> 313 <H3>4.2.1 Environmental dependencies</H3> 314 </a> 315 316 A program shall document the following environmental dependencies, where they 317 apply, and should document other known environmental dependencies: 318 319 <UL> 320 <LI>considering the pictured numeric output string buffer a fixed area 321 with unchanging access parameters 322 (<a href=dpans3.htm#3.3.3.6>3.3.3.6</a> Other transient regions); 323 <LI>depending on the presence or absence of non-graphic characters in a 324 received string 325 (<a href=dpans6.htm#6.1.0695>6.1.0695</a> ACCEPT, 326 <a href=dpans6.htm#6.2.1390>6.2.1390</a> EXPECT); 327 <LI>relying on a particular rounding direction 328 (<a href=dpans3.htm#3.2.2.1>3.2.2.1</a> Integer division); 329 <LI>requiring a particular number representation and arithmetic 330 (<a href=dpans3.htm#3.2.1.1>3.2.1.1</a> 331 Internal number representation); 332 <LI>requiring non-standard words or techniques 333 (<a href=dpans3.htm#3.>3.</a> Usage requirements); 334 <LI>requiring the ability to send or receive control characters 335 (<a href=dpans3.htm#3.1.2.2>3.1.2.2</a> Control characters, 336 <a href=dpans6.htm#6.1.1750>6.1.1750</a> KEY); 337 <LI>using control characters to perform specific functions 338 (<a href=dpans6.htm#6.1.1320>6.1.1320</a> EMIT, 339 <a href=dpans6.htm#6.1.2310>6.1.2310</a> TYPE); 340 <LI>using flags as arithmetic operands 341 (<a href=dpans3.htm#3.1.3.1>3.1.3.1</a> Flags); 342 <LI>using lower case for standard definition names or depending on the 343 case sensitivity of a system 344 (<a href=dpans3.htm#3.3.1.2>3.3.1.2</a> Definition names); 345 <LI>using the graphic character with a value of hex 24 346 (<a href=dpans3.htm#3.1.2.1>3.1.2.1</a> Graphic 347 characters). 348 </UL> 349 350 <P> 351 352 <hr> 353 <A name=4.2.2> 354 <H3>4.2.2 Other program documentation</H3> 355 </a> 356 357 A program shall also document: 358 <P> 359 360 <UL> 361 <LI>minimum operator's terminal facilities required; 362 <LI>whether a Standard System exists after the program is loaded. 363 </UL> 364 365 366 <HR> 367 <A href=dpans.htm#toc><IMG src="up.gif" ></A> Table of Contents 368 <BR> 369 <A href=dpans5.htm><IMG src="right.gif" ></A> Next Section 370 <P> 371 </BODY> 372 </HTML>