From 25dcf051d6d5d8d6c81d571414e1062223b051b8 Mon Sep 17 00:00:00 2001
From: crc
Date: Mon, 14 Oct 2019 20:59:08 +0000
Subject: [PATCH] more glossary updates
FossilOrigin-Name: 4cfe1f3b58b493f0ed5769ce817ce69bdce73f90657470ab934d312d78abe6f8
---
RELEASE-NOTES | 1 +
doc/Glossary-Concise.txt | 6 +++---
doc/Glossary.html | 6 +++---
doc/Glossary.txt | 6 +++---
words.tsv | 6 +++---
5 files changed, 13 insertions(+), 12 deletions(-)
diff --git a/RELEASE-NOTES b/RELEASE-NOTES
index 9e835e6..f3eadaa 100644
--- a/RELEASE-NOTES
+++ b/RELEASE-NOTES
@@ -82,6 +82,7 @@ Documentation
- fix some namespace listings in the glossary
- correct an example in the book
- formatting improvements in html for glossary server
+- minor expansions to the descriptions in the glossary
Kernel
diff --git a/doc/Glossary-Concise.txt b/doc/Glossary-Concise.txt
index e3add25..6752fb4 100644
--- a/doc/Glossary-Concise.txt
+++ b/doc/Glossary-Concise.txt
@@ -188,7 +188,7 @@ RewriteUnderscores D: -a A: - F: -
Variable. When set to `TRUE`, RETRO will replace underscores in strings with spaces. When `FALSE`, RETRO does not.
STRINGS D: -a A: - F: -
-Return the address of the start of the temporary string pool.
+Return the address of the start of the temporary string pool. This can be altered by changing the values of `TempStrings` and `TempStringMax`.
ScopeList D: -a A: - F: -
Variable. This holds some information used by `{{` and `}}`.
@@ -422,7 +422,7 @@ case D: nmq- || nmq-n A: - F: -
If `n` is equal to `m`, drop both and execute the specified quote before exiting the calling word. If not equal, leave `n` on the stack and let execution continue.
choose D: fqq- A: - F: -
-Execute q1 if the flag is true (-1) or q2 if the flag is false (0). Only these flags are valid when using `choose`.
+Execute q1 if the flag is true (-1) or q2 if the flag is false (0). Only these flags are valid when using `choose`; passing other values as flags will result in memory corruption.
class:data D: n- || n-n A: - F: -
Class handler for data structures.
@@ -1352,7 +1352,7 @@ times D: nq- A: - F: -
Run the specified quote the specified number of times.
times D: nq- A: - F: -
-Run a quote the specified number of times, tracking the loop index in `I`.
+Run a quote the specified number of times, tracking the loop index in `I`. This is less efficient than `times`, so if the index is not needed, this should be avoided.
tri D: xqqq-? A: - F: -
Apply q1 against x, then q2 against a copy of x, and finally q3 against another copy of x.
diff --git a/doc/Glossary.html b/doc/Glossary.html
index d59be10..5a8cf74 100644
--- a/doc/Glossary.html
+++ b/doc/Glossary.html
@@ -471,7 +471,7 @@
Addr: -
Float: -
-Return the address of the start of the temporary string pool.
+Return the address of the start of the temporary string pool. This can be altered by changing the values of `TempStrings` and `TempStringMax`.
Class: | class:word |
Namespace: | global |
Interface Layer: | all |
ScopeList
Data: -a
@@ -1041,7 +1041,7 @@
Addr: -
Float: -
-Execute q1 if the flag is true (-1) or q2 if the flag is false (0). Only these flags are valid when using `choose`.
+Execute q1 if the flag is true (-1) or q2 if the flag is false (0). Only these flags are valid when using `choose`; passing other values as flags will result in memory corruption.
Class: | class:word |
Namespace: | global |
Interface Layer: | all |
class:data
Data: n- || n-n
@@ -3471,7 +3471,7 @@
Addr: -
Float: -
-Run a quote the specified number of times, tracking the loop index in `I`.
+Run a quote the specified number of times, tracking the loop index in `I`. This is less efficient than `times`, so if the index is not needed, this should be avoided.
Class: | class:word |
Namespace: | global |
Interface Layer: | all |
tri
Data: xqqq-?
diff --git a/doc/Glossary.txt b/doc/Glossary.txt
index 31b4982..38a3741 100644
--- a/doc/Glossary.txt
+++ b/doc/Glossary.txt
@@ -730,7 +730,7 @@ STRINGS
Addr: -
Float: -
-Return the address of the start of the temporary string pool.
+Return the address of the start of the temporary string pool. This can be altered by changing the values of `TempStrings` and `TempStringMax`.
Class: class:word | Namespace: global | Interface Layer: all
------------------------------------------------------------------------
@@ -1618,7 +1618,7 @@ choose
Addr: -
Float: -
-Execute q1 if the flag is true (-1) or q2 if the flag is false (0). Only these flags are valid when using `choose`.
+Execute q1 if the flag is true (-1) or q2 if the flag is false (0). Only these flags are valid when using `choose`; passing other values as flags will result in memory corruption.
Class: class:word | Namespace: global | Interface Layer: all
------------------------------------------------------------------------
@@ -5326,7 +5326,7 @@ times
Addr: -
Float: -
-Run a quote the specified number of times, tracking the loop index in `I`.
+Run a quote the specified number of times, tracking the loop index in `I`. This is less efficient than `times`, so if the index is not needed, this should be avoided.
Class: class:word | Namespace: global | Interface Layer: all
------------------------------------------------------------------------
diff --git a/words.tsv b/words.tsv
index 0430fca..78af955 100644
--- a/words.tsv
+++ b/words.tsv
@@ -61,7 +61,7 @@ J -n - - Access the parent loop index for the current loop. (For loops made usin
K -n - - Access the grandparent loop index for the current loop. (For loops made using `times`) class:word {n/a} {n/a} global all
NoEcho -a - - Variable. If TRUE, allow display of the "ok" prompt and startup banner. class:word {n/a} {n/a} global rre
RewriteUnderscores -a - - Variable. When set to `TRUE`, RETRO will replace underscores in strings with spaces. When `FALSE`, RETRO does not. class:data {n/a} {n/a} global all
-STRINGS -a - - Return the address of the start of the temporary string pool. class:word {n/a} {n/a} global all
+STRINGS -a - - Return the address of the start of the temporary string pool. This can be altered by changing the values of `TempStrings` and `TempStringMax`. class:word {n/a} {n/a} global all
ScopeList -a - - Variable. This holds some information used by `{{` and `}}`. class:data {n/a} {n/a} global all
TIB -a - - Constant. Returns a pointer to the text input buffer. class:data {n/a} {n/a} global rre
TRUE -n - - Returns `-1`, the value used to indicate a TRUE result. class:word {n/a} {n/a} global all
@@ -139,7 +139,7 @@ c:vowel? c-f - - Return TRUE if character is a vowel or FALSE otherwise. class
c:whitespace? c-f - - Return TRUE if character is whitespace, or FALSE otherwise. class:word {n/a} {n/a} c all
call a- - - Call a function. class:primitive {n/a} {n/a} global all
case nmq- || nmq-n - - If `n` is equal to `m`, drop both and execute the specified quote before exiting the calling word. If not equal, leave `n` on the stack and let execution continue. class:word {n/a} {n/a} global all
-choose fqq- - - Execute q1 if the flag is true (-1) or q2 if the flag is false (0). Only these flags are valid when using `choose`. class:word {n/a} {n/a} global all
+choose fqq- - - Execute q1 if the flag is true (-1) or q2 if the flag is false (0). Only these flags are valid when using `choose`; passing other values as flags will result in memory corruption. class:word {n/a} {n/a} global all
class:data n- || n-n - - Class handler for data structures. Keep the address or value on the stack. Compile the value or address as a literal into the current definition. class:word {n/a} {n/a} class all
class:macro a- - - Class handler for compiler macros (immediate words) Execute the function at the provided address. Execute the function at the provided address. class:word {n/a} {n/a} class all
class:primitive a- - - Class handler for primitive words (words which map to Nga instructions) Execute the function. Compile the machine code in the definiton into the current definition. class:word {n/a} {n/a} class all
@@ -449,7 +449,7 @@ sys:argv n-s - - Given an argument number, return the argument as a string. cl
sys:name -s - - Return the filename of the program being run. class:word {n/a} {n/a} sys rre
tab - - - Display a tab (`ASCII:HT`) class:word {n/a} {n/a} global all
times nq- - - Run the specified quote the specified number of times. class:word #12 [ $- c:put ] times {n/a} global all
-times nq- - - Run a quote the specified number of times, tracking the loop index in `I`. class:word {n/a} {n/a} global all
+times nq- - - Run a quote the specified number of times, tracking the loop index in `I`. This is less efficient than `times`, so if the index is not needed, this should be avoided. class:word {n/a} {n/a} global all
tri xqqq-? - - Apply q1 against x, then q2 against a copy of x, and finally q3 against another copy of x. class:word {n/a} {n/a} global all
tri* xyzqqq-? - - Apply q1 against x, q2 against y, and q3 against z. class:word {n/a} {n/a} global all
tri@ xyzq-? - - Apply q against x, then against y, and finally against z. class:word {n/a} {n/a} global all