% -*- Mode:Text -*-

\chapter{Guide to the thesaurus}\sectlabel{thesguide}

\section{About the thesaurus}

The \step\ software thesaurus consists of three parts:
 \begin{itemize}
	 \item A \tbf{Guide to the thesaurus}---the present chapter.
	\item The \tbf{\SF\ thesaurus}, describing, under individual entries
arranged by topic, all the \SF\ words that are intended for use by the \step\
application programmer.  The thesaurus is divided into two chapters: a {\bf
Forth thesaurus} (\chapt{forth-thes}), devoted to generic Forth constructs,
and a \tdf{Step thesaurus} (\chapt{step-thes}), devoted to \step-specific
constructs.
	\item The \tbf{Thesaurus index}---a single alphabetical
cross-reference to all the thesaurus entries.
	\end{itemize}

Since \SF\ is a close relative of F83, for which much tutorial and reference
material is already available, the Forth-generic entries of the thesaurus are
conceived as a utilitarian reference---not an in-depth technical manual for
the Forth language.  On the other hand, the \step-specific entries try to be
fairly exhaustive, so as to provide a complete reference for
\step\ machine and support the needs of even the sophisticated user.

Moreover, through the \id|see| facility (Forth decompiler/disassembler) and
the \id|view| facility (source-code definition locator), the systems
programmer has direct access from \SF\ to all the \SF\ internals and the
accompanying online documentation.

\medskip

To every relevant \SF\ word there corresponds an \tdf{entry} in the
thesaurus. The entries are arranged by subject and grouped under separate
\tdf{topics}. Entries are liberally cross-referenced to other entries and
topics.  All entries are listed in alphabetical order in the thesaurus index.


\subsection{Thesaurus topics}

Each thesaurus topic is in the form a a reasonably self-contained subsection
of text, headed by a section number and a descriptive name.  In turn, topics
are arranged by subject and grouped within larger sections.  For instance,
the comparison of unsigned numbers is discussed in the section
\tdf{Arithmetic and logic operations} under the topic

{\hspace*{2em}\bf \ref{sect.Unsigned comparison}\quad Unsigned comparison}

\noindent The topic number (``\ref{sect.Unsigned comparison}'' in the above
example) is the target of cross-references found in the Thesaurus index.

\medskip

A topic starts with a brief summary of the subject at hand.  This summary is
followed by headings, collected in tabular form, for all the entries that are
discussed under that topic. Each heading includes the entry's name as a Forth
word, its stack and input-stream interfaces, and indications on the
lexical/semantic type of the word (see \sect{word type}).  Finally, the
entries are discussed in detail in discursive form, with notes on usage,
examples, and cross-references.

Occasionally, when clarity demands, the listing of heading is broken into two
or three separate segments, each followed by the text describing the entries
in that segment.


\subsection{Thesaurus entries}

The structure of thesaurus entries is illustrated by the following example,
where the headings for the three entries \id|forget|, \id|(forget)|, and
\id|fence| are followed by the description of the entries themselves.

\medskip

 \begin{thesaurus}
 \advance\leftskip by1em
 \makeatletter
 \let\@word=\@wordnoindex
 \makeatother
 \itp\word{forget}{\=:name}{:}
 \word{(forget)}{acf \=}{:}
 \word{fence}{\= addr}{variable}

If \tsl{name} is found in the \current\ vocabulary, \id|forget| deletes
\tsl{name} from it, as well as all words added to the dictionary after
\tsl{name}, regardless of their vocabulary. If \tsl{name} is not found, or
the name of the \current\ vocabulary has been deleted, an error condition
occurs.

\id|forget| calls \id|(forget)|, which expects the \ag{acf} of a word from
the stack rather than its name from the input stream.  If the \ag{acf} of the
specified word is lower than the value of the user variable \id|fence|,
\id|(forget)| aborts with the message ``{\tt Below Fence}'' and no forgetting
will take place; this is to prevent accidentally erasing critical parts of
the system.
 \end{thesaurus}

\medskip

The conventions used in the headings are explained immediately below.


\subsubsection{Forth word naming conventions}

Most Forth words that return a flag have a name that ends with a question
mark.  Most words whose action depends on a flag have a name that starts with
a question mark. Words that start with a parenthesis are usually lower-level
versions of a similar word without parenthesis. Other conventions used in
naming words either are generic Forth conventions or are explained along with
the relevant words.

All single-digit hex numbers ({\tt 0} through {\tt f}) are defined as Forth
constants; no two-digit hex numbers (i.e., {\tt 00} through {\tt ff}) are
used as names of words in the \id|forth| vocabulary. [How about
\id|cd| and \id|df|?]

\medskip

Most Forth words are similar in spelling to ordinary English words and are
pronounced accordingly. The words \id|dup| and \id|rot| are pronounced
``dupe'' and ``rote''. A question mark is pronounced ``question''; a left or
right parentesis, ``paren''; a left or right bracket, ``bracket''. For
example, \id|sys-(key?| is pronounced ``sys-paren-key-question''.


\subsubsection{Stack and input stream}

Following the entry name is the \tdf{stack interface}, in parentheses; this
may be immediately followed by an \tdf{input-stream interface}.
If \emph{both} stack and input-stream interfaces are empty

\parhead{Stack interface} In the above example, the word \id|(forget)|
consumes one stack item, which will be called \ag{acf} in the text that
describes the word, and returns nothing on the stack. On the other hand,
\id|fence| does not consume any stack items but returns one item, called
\ag{addr}. The long dash in the stack interface separates items consumed from
items returned. The main entry \id|forget| does not affect the stack;
in this case no stack interface is given, i.e. the notation
(---) is suppressed.

Certain naming conventions are used within the stack interface; these
conventions are made use of in the accompanying text that describes the
behavior of an entry word.  \ag{n} stands for a generic signed number;
\ag{+n}, for a non-negative signed number;
\ag{-n}, for a positive one. \ag{flag} stands for a logical flag
(with value \true=$-$1 or \false=0); \ag{mask}, for a bit mask; \ag{len}, for a
length (e.g., number of bytes in a string); \ag{pstr}, for the address of a
\tsl{packed string} (the characters that make up the string are preceded by a
\tsl{count} byte); \ag{addr}, for an address.  A mnemonic such as
\ag{row\char"23} means ``row number'' (i.e., which row), while
\ag{\char"23rows} means ``number of rows'' (i.e., how many rows).

\parhead{Input-stream interface} A Forth word may consume characters
from the input stream, which will be parsed into one or more strings
on the basis of delimiting characters that depend on the word itself.
In the above thesaurus sample, \id|forget| consumes a \ag{name}, i.e., a string
of consecutive nonspace characters (see \id|blword| in the glossary); this
string is terminated by a space. If the string is terminated
by other characters, this is explicitly indicated; for instance,
the entry
	\oneliner{\hbox to55pt{\tt abort"\hfil}\tsl{text}"}
 means that \id|abort"| expects a text string terminated by the
character `{\tt"}'; the entry
	\oneliner{\hbox to55pt{\tt sh\hfil}\tsl{rest-of-line}\return}
 means that \id|sh| consumes a string \ag{rest-of-line} terminated
by a carriage return.

\subsubsection{Word type}\sectlabel{word type}

The right end of each entry line is reserved for information about the {\em
type} of the entry word, namely, its \tdf{definer} and its \tdf{attributes},
as explained below.

In the above thesurus sample, \id|forget| is a ``\tsc{colon} word'', i.e., a
word defined by the \tsc{colon} compiler; \id|fence| is a Forth
\tsc{variable}, defined by the word \id|variable|.  Knowing by what defining
word a given entry word was created gives useful clues about the latter's
role in a program.  Thus, a word created by the \tsc{colon} compiler (\id|:|)
is typically a procedure; a word created by \id|variable| is associated with
a one-cell data-structure and returns on the stack the cell's address, while
one created by \id|constant| returns the cell's contents; a word created by
\id|defer| contains a pointer to another word, and executes that word when
called; a word created by \id|create-buffer| is associated with a
\emph{buffer} data structure; etc.

The definer may be accompanied by superscripts that tell that the entry word
has one or more of the attributes \emph{immediate}, \emph{deferred},
\emph{compile-only}, or \emph{interpret-only}, with the following meanings
 $$
 \begin{tabular}{|l||l|p{2in}|}\hline
    $\dagger$ & immediate & The entry word is \emph{immediate}, i.e., is
immediately interpreted even during colon compilation.\\\hline
    * & deferred & The word is \emph{deferred}, i.e., it
contains a pointer to another word and executes that word when called. \\\hline
    C & compile & The word is intended for use only in \compile\ mode.\\\hline
    I & interpret & The word is intended for use only in \interpret\
mode.\\\hline
 \end{tabular}
 $$
	Thus, 

\medskip

 \begin{thesaurus}
 \advance\leftskip by1em
	\imm\cmp\word{literal}{n \=}{:}
 \end{thesaurus}

\medskip

\noindent means that \id|literal|, defined by the colon compiler, is an
immediate word normally used only in \compile\ mode.

\endinput


Note that `variable' generically refers to a quantity whose value may
change during the execution of a program.  We consistently use the
small-caps spelling when we mean a Forth \tsc{variable} (i.e., a word that
returns the \tsl{address} of its data cell, as explained in Section
\ref{constants}).
