% !TeX root = forth.tex
% !TeX spellcheck = en_US
\annex{Compatibility analysis} % D (informative annex)
\label{annex:diff}
\setwordlist{core}

Before this standard, there were several industry standards for Forth.
The most influential are listed here in chronological order, along
with the major differences between this standard and the most recent,
Forth 94.

\section{FIG Forth (circa 1978)} % D.1

FIG Forth was a ``model'' implementation of the Forth language
developed by the Forth Interest Group (FIG). In FIG Forth, a
relatively small number of words were implemented in processor-dependent
machine language and the rest of the words were implemented in Forth.
The FIG model was placed in the public domain, and was ported to a wide
variety of computer systems. Because the bulk of the FIG Forth
implementation was the same across all machines, programs written in
FIG Forth enjoyed a substantial degree of portability, even for
``system-level'' programs that directly manipulate the internals
of the Forth system implementation.

FIG Forth implementations were influential in increasing the number
of people interested in using Forth. Many people associate the
implementation techniques embodied in the FIG Forth model with
``the nature of Forth''.

However, FIG Forth was not necessarily representative of commercial
Forth implementations of the same era. Some of the most successful
commercial Forth systems used implementation techniques different
from the FIG Forth ``model''.


\section{Forth 79} % D.2

The Forth-79 Standard resulted from a series of meetings from 1978
to 1980, by the Forth Standards Team, an international group of Forth
users and vendors (interim versions known as Forth 77 and Forth 78
were also released by the group).

Forth 79 described a set of words defined on a 16-bit, twos-complement,
unaligned, linear byte-addressing virtual machine. It prescribed an
implementation technique known as ``indirect threaded code'', and used
the ASCII character set.

The Forth-79 Standard served as the basis for several public domain
and commercial implementations, some of which are still available and
supported today.


\section{Forth 83} % D.3

The Forth-83 Standard, also by the Forth Standards Team, was released
in 1983. Forth 83 attempted to fix some of the deficiencies of Forth
79.

Forth 83 was similar to Forth 79 in most respects. However, Forth 83
changed the definition of several well-defined features of Forth 79.
For example, the rounding behavior of integer division, the base value
of the operands of \word{PICK} and \word{ROLL}, the meaning of the
address returned by \word{'}, the compilation behavior of \word{'},
the value of a ``true'' flag, the meaning of \texttt{NOT}, and the
``chaining'' behavior of words defined by \texttt{VOCABULARY} were all
changed. Forth 83 relaxed the implementation restrictions of Forth 79
to allow any kind of threaded code, but it did not fully allow
compilation to native machine code (this was not specifically prohibited,
but rather was an indirect consequence of another provision).

Many new Forth implementations were based on the Forth-83 Standard, but
few ``strictly compliant'' Forth-83 implementations exist.

Although the incompatibilities resulting from the changes between
Forth 79 and Forth 83 were usually relatively easy to fix, a number
of successful Forth vendors did not convert their implementations to
be Forth 83 compliant. For example, the most successful commercial
Forth for Apple Macintosh computers is based on Forth 79.


\section{ANS Forth (1994)} % D.5
\label{diff:ans}

In the mid to late 1980s the computer industry underwent a rapid and
profound change.  The personal-computer market matured into a business
and commercial market, while the market for ROM-based embedded control
computers grew substantially.  Improvements in custom processor design
allowed for the de\-vel\-op\-ment of numerous ``Forth chips,'' customized
for the execution of the Forth language.

In order to take full advantage of evolving technology, many Forth
implementations ignored some of the restrictions imposed by the
implied ``virtual machine'' of previous standards.
The ANS Forth committee was formed in 1987 to address the fragmentation
within the Forth community caused not only by the difference between
Forth 79 and Forth 83 but the exploitation of technical developments.

The committee undertook a comprehensive review of a variety of existing
implementations, especially those with substantial user bases and/or
considerable success in the market place.  This allowed them to identify
and document features common to these systems, many of which had not been
included in any previous standard.
This was the most comprehensive review of Forth systems to date, taking
eighty-seven days covering twenty-three meetings over eight years.
The inclusive nature of the standard allowed the various factions within
the community to unify in support of ANS Forth, with many systems
providing a compatibility layer.


The committee chose to move away from prescribing stringent requirements
as previous standards had, with the specification of a virtual machine.
It preferred to describe the operation of the virtual machine, without
reference to its implementation, thus allowing an implementor to take
full advantage of any technical developments while providing the
developer with a complete list of entitlements.

This required the identification of implicit assumptions made by the
previous standards, making them explicit and abstracting them into
more general concepts where possible.  A good example of this is the
size of an item on the stack.  In previous standards this was assumed
to be 16 bits wide.  This was no longer a valid assumption.  ANS Forth
introduced the concept of the \emph{cell}, allowing an implementation
to use a stack size most suited to the environment.

The American National Standards Institution (ANSI) published the ANS
Forth Standard in 1994 with the title ``\emph{ANSI X3.215-1994
Information Systems --- Programming Language FORTH}''.  This is referenced
throughout this document as Forth 94.

\section{ISO Forth (1997)}
\label{diff:iso}

ANSI submitted the Forth 94 Standard to the
ISO (International Organization for Standardization) and
IEC (International Electrotechnical Commission) joint committee for
consideration as an international standard.
The ISO/IEC adopted the Forth 94 document as an international standard
in 1997, publishing it under the title ``\emph{ISO/IEC 15145:1997
Information technology.  Programming languages.  FORTH}''.


\section{Approach of this standard} % D.6
\label{diff:approach}

During a workshop on the Forth standard at the EuroForth conference in
2004 it was agreed that Forth 94 required updating.

A committee was formed and agreed that the process should be as open
as possible, adopting the Usenet RfD/CfV (Request for Discussion/Call
for Votes) process to produce semi-formal proposals for changes to the
standard.  In addition to general discussion on the \texttt{comp.lang.forth}
usenet news group, a moderated mailing list (with public archive) was
created for those who do not follow the news group.
Standards meetings to discuss CfVs were held in public in
conjunction with the EuroForth conference.

The work of the Forth 94 committee was the basis of this standard,
informally called Forth 200\emph{x}.  The aim of the Forth 200\emph{x}
committee is to produce a rolling document, with the standard constantly
being updated based on discussion of proposals and the corresponding
votes.  A snapshot document is occasionally produced, with this document
being the first.

The Forth 200\emph{x} committee defined a procedure for proposals.  In
addition to the formal text of the proposal, they had to include:
the rationale behind the change;
a reference implementation, or a description of the reason a reference
implementation cannot be presented;
unit testing for the proposed change, especially for border conditions.
See \xref[Process]{process} (page \pageref{process}) for a full description.


\section{Differences from Forth 94} % D.7
\label{diff:forth94}

\subsection{Removed Obsolete Words} % D.7.1
\label{diff:ans:obsolete}

Forth 94 declared seven words as `obsolescent', all but
\word[tools]{FORGET} have been removed from this standard.

\begin{description}
\item[Words affected:] ~\\
	\texttt{\#TIB},
  	\texttt{CONVERT},
  	\texttt{EXPECT},
  	\texttt{QUERY},
  	\texttt{SPAN},
  	\texttt{TIB},
  	\word{WORD}.
  
\item[Reason:] ~\\
	Obsolescent words have been removed.
  
\item[Impact:] ~\\
	\word{WORD} is no longer required to leave a space at the end of
	the returned string.

	It is recommended that, should the obsolete words be included,
	they have the behaviour described in Forth 94.  The names should
	not be reused for other purposes.

\item[Transition/Conversion:] ~\\
	The functions of \texttt{TIB} and \texttt{\#TIB} have been
	superseded by \word{SOURCE}.
 
	The function of \texttt{CONVERT} has been superseded by
	\word{toNUMBER}.

	The functions of \texttt{EXPECT} and \texttt{SPAN} have been
	superseded by \word{ACCEPT}.

	The function of \texttt{QUERY} may be performed with \word{ACCEPT}
	and \word{EVALUATE}.
\end{description}


\subsection{Separate Floating-point Stack is now Standard} % D.7.2
\label{diff:fpstack}

Previously systems could implement either a separate floating-point
stack or a combined floating-point/data stack; programs were required
to cater for both (or declare an environmental dependency on a
particular variant).

\begin{description}
\item[Words Affected:] ~\\
	All floating-point words.

\item[Reason:] ~\\
	The developing of software that may be used with either a combined
	stack or a separate stack is extremely difficult and costly.  While
	some of the systems surveyed provide a combined floating-point/data
	stack, they all provide a separate floating-point stack.

\item[Impact:] ~\\
	Forth 94 programs with an environmental dependency on a separate
	floating-point stack become standard programs.

	Forth 94 programs with an environmental dependency on a combined
	stack retain the environmental dependency.

	Forth 94 programs (without environmental dependency, i.e., those
	working on either kind of system) remain standard programs.

	Forth 94 systems that implement a separate floating-point stack
	continue to be standard systems.

	Forth 94 systems that implement a combined stack become systems
	with an environmental restriction of not providing a separate
	floating-point stack, but a combined stack.

\item[Transition/Conversion:] ~\\
	Any code that has an environmental dependency on the use of a
	combined floating-point/data stack should be ported to use a
	separate floating-point stack.

	A system that has an environmental restriction on using a combined
	floating-point/data stack should consider providing a separate
	floating-point stack.
\end{description}


\subsection[Using ENVIRONMENT? to inquire whether a word set is present]{Using \word{ENVIRONMENTq} to inquire whether a word set is present} % D.7.3
\label{diff:environment}

With the advent of a new standard, it was necessary to review the
meaning of word set queries.  Compatibility with Forth 94 demands
that a word set query produce the same result as for Forth 94; i.e.,
querying for \texttt{CORE-EXT} returns true only if all the Forth 94
CORE EXT words are present.  The question was how to distinguish
between word sets described by this and subsequent standards.

The committee considered adding a year indicator to the word set name
(``\texttt{CORE-EXT-\snapshot}'') or a providing a general query
(``\texttt{Forth-\snapshot}'') which could be combined with the
word-set query.  As the committee could find very few examples of the
word-set queries being used, it chose not to update the word set-query
mechanism, but rather to mark it as obsolescent.

\begin{description}
\item[Words Affected:] ~\\
	\word{ENVIRONMENTq}

\item[Reason:] ~\\
	The use of the word-set query to inquire whether a word set is
	present in the system has been marked obsolescent.  If present
	the query indicates the word set, as documented in Forth 94, is
	available.

\item[Impact:] ~\\
	Forth 94 did not guarantee the presence of these queries.  Many
	systems that provided all the words in a particular word set did
	not provide the corresponding query.  Portable programs are not
	affected as they could not rely on this function.

\item[Transition/Conversion:] ~\\
	There is no direct equivalent to determine the presence of a whole
	word set.  The \wref{tools:[DEFINED]}{} and \wref{tools:[UNDEFINED]}{}
	words can be used to detect the availability (or otherwise) of
	individual words.
\end{description}


\subsection[Additional TO targets]{Additional \word{TO} targets} % D.7.4
\label{diff:12:to}

\wref{core:TO}{TO} has been extended to act on targets defined with
\wref{floating:FVALUE}{} and \wref{double:2VALUE}{}.

\begin{description}
\item[Words affected:] ~\\
	\word{TO}
\end{description}


\subsection{Input/Output return values} % D.7.5
\label{diff:12:ior}

\begin{description}
\item[Words affected:] ~\\
	All words that return an \param{ior}.
% 	\word[memory]{ALLOCATE},
% 	\word{CLOSE-FILE},
% 	\word{CREATE-FILE},
% 	\word{DELETE-FILE},
% 	\word{FILE-POSITION},
% 	\word{FILE-SIZE},
% 	\word{FILE-STATUS},
% 	\word{FLUSH-FILE},
% 	\word[memory]{FREE},
% 	\word{OPEN-FILE},
% 	\word{READ-FILE},
% 	\word{READ-LINE}, \linebreak
% 	\word{RENAME-FILE},
% 	\word{REPOSITION-FILE},
% 	\word{RESIZE-FILE},
% 	\word[memory]{RESIZE},
% 	\word{WRITE-FILE},
% 	\word{WRITE-LINE}.

\item[Reason:] ~\\
	Forth 94 left the error code (\param{ior}) implementation-defined,
	although it did recommend an \param{ior} to be a \word[exception]{THROW}
	code.  Forth 2012 now requires an \param{ior} to be a
	\word[exception]{THROW} code.

\item[Transition/Conversion:] ~\\
	Forth 94 programs are not affected.  Programs that are dependent
	on \param{iors} being throwable are no longer required to document
	the dependency.

	Forth 94 systems that abided by the recommendation are not affected.
	Systems that did not heed this advice are required to do so. A
	number of \word[exception]{THROW} codes were added to table
	\ref{table:throw} to ease this transition.
\end{description}


\subsection{Minimum number of locals} % D.7.6
\label{diff:12:locals}

\begin{description}
\item[Words affected:] ~\\
	\word[local]{LOCAL}, \word[local]{LOCALS}

\item[Reason:] ~\\
	Some programs require more than eight locals.
 
\item[Transition/Conversion:] ~\\
	Existing programs are unaffected.  Systems implementing the locals
	word set have to be changed to support at least 16 (previously 8)
	locals.
\end{description}


\subsection{Number prefixes} % D.7.7
 \label{diff:12:prefix}

Decimal, hexadecimal, binary number literals can now be written
irrespective of \word{BASE} by using the prefix \#, \$, \%.  Also, character
literals can be written as 'c'.
 
Standard programs are unaffected.  Systems have to be changed to
recognize these forms.

See \xref[3.4.1.3]{usage:numbers}.
 

\subsection[SOURCE-ID Clarification]{\word{SOURCE-ID} Clarification} % D.7.7
\label{diff:12:sourceid}

When interpreting text from a file, the relationship between the position in the
file returned by \word{SOURCE-ID}, and the current interpretation position is
undefined.


\subsection[FASINH]{\word[floating]{FASINH}} % D.7.9
 \label{diff:12:fasinh}

An ambiguous condition on \param{r1} being less than 0 was removed.

Existing programs are not affected.  Existing systems are
unlikely to be affected.


\subsection[FATAN2]{\word[floating]{FATAN2}} % D.7.10
\label{diff:12:fatan2}

\begin{description}
\item[Words affected:] ~\\
	\word[floating]{FATAN2}

\item[Reason:] ~\\
	The result is now specified more tightly: it is the principal angle
	(between -pi and pi).

\item[Impact:] ~\\
	Forth 94 compliant programs are not affected.

\item[Transition/Conversion:] ~\\
	Systems may have to change \word[floating]{FATAN2} to return
	the principal angle.
\end{description}

% =========================================================

\section{Additional words} % D.8
\label{diff:new12}

The following words have been added to the standard:

\setcounter{subsection}{5}
\subsection{Core word sets}
The following words have been added to \xref{wordlist:core-ext}:

\begin{minipage}[t]{0.3\linewidth}
	\wref{core:ACTION-OF}{} \\
	\wref{core:BUFFER:}{} \\
	\wref{core:DEFER}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{core:DEFER!}{} \\
	\wref{core:DEFER@}{} \\
	\wref{core:HOLDS}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{core:IS}{} \\
	\wref{core:PARSE-NAME}{} \\
	\wref{core:Seq}{}
\end{minipage}
\html{<br class="clear" />}


% Block word sets
\stepcounter{subsection}

\subsection{Double-Number word sets}
The following words have been added to \xref{wordlist:double-ext}:

\wref{double:2VALUE}{}

% Exception word sets
\stepcounter{subsection}

\subsection{Facility word sets}
The following words have been added to \xref{wordlist:facility-ext}:

\begin{minipage}[t]{0.35\linewidth}
	\wref{facility:+FIELD}{} \\
	\wref{facility:BEGIN-STRUCTURE}{} \\
	\wref{facility:CFIELD:}{} \\
	\wref{facility:EKEYtoFKEY}{} \\
	\wref{facility:END-STRUCTURE}{} \\
	\wref{facility:FIELD:}{} \\
	\wref{facility:K-ALT-MASK}{} \\
	\wref{facility:K-CTRL-MASK}{} \\
	\wref{facility:K-DELETE}{} \\
	\wref{facility:K-DOWN}{} \\
	\wref{facility:K-END}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.25\linewidth}
	\wref{facility:K-F1}{} \\
	\wref{facility:K-F10}{} \\
	\wref{facility:K-F11}{} \\
	\wref{facility:K-F12}{} \\
	\wref{facility:K-F2}{} \\
	\wref{facility:K-F3}{} \\
	\wref{facility:K-F4}{} \\
	\wref{facility:K-F5}{} \\
	\wref{facility:K-F6}{} \\
	\wref{facility:K-F7}{} \\
	\wref{facility:K-F8}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.35\linewidth}
	\wref{facility:K-F9}{} \\
	\wref{facility:K-HOME}{} \\
	\wref{facility:K-INSERT}{} \\
	\wref{facility:K-LEFT}{} \\
	\wref{facility:K-NEXT}{} \\
	\wref{facility:K-PRIOR}{} \\
	\wref{facility:K-RIGHT}{} \\
	\wref{facility:K-SHIFT-MASK}{} \\
	\wref{facility:K-UP}{}
\end{minipage}
\html{<br class="clear" />}

\subsection{File-Access word sets}
The following words have been added to \xref{wordlist:file-ext}:

\begin{minipage}[t]{0.3\linewidth}
	\wref{file:INCLUDE}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{file:REQUIRE}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{file:REQUIRED}{}
\end{minipage}
\html{<br class="clear" />}

\subsection{Floating-Point word sets}
The following words have been added to \xref{wordlist:floating-ext}:

\begin{minipage}[t]{0.3\linewidth}
	\wref{floating:DFFIELD:}{} \\
	\wref{floating:FtoS}{F>S} \\
	\wref{floating:FFIELD:}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{floating:FTRUNC}{} \\
	\wref{floating:FVALUE}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{floating:StoF}{S>F} \\
	\wref{floating:SFFIELD:}{}
\end{minipage}
\html{<br class="clear" />}

\subsection{Locals word sets}
The following words have been added to \xref{wordlist:local-ext}:

\wref{local:b:}{}

% Memory-Allocation word sets
\stepcounter{subsection}

\subsection{Programming-Tools word sets}
\label{diff:12:tools}
The following words have been added to the \xref{wordlist:tools-ext}:

\begin{minipage}[t]{0.45\linewidth}
	\wref{tools:NtoR}{} \\
	\wref{tools:NAMEtoCOMPILE}{} \\
	\wref{tools:NAMEtoINTERPRET}{} \\
	\wref{tools:NAMEtoSTRING}{} \\
	\wref{tools:NRfrom}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.45\linewidth}
	\wref{tools:SYNONYM}{} \\
	\wref{tools:TRAVERSE-WORDLIST}{} \\
	\wref{tools:[DEFINED]}{} \\
	\wref{tools:[UNDEFINED]}{}
\end{minipage}
\html{<br class="clear" />}

% Search-Order word sets
\stepcounter{subsection}

\subsection{String word sets}
The following words have been added to the \xref{wordlist:string-ext}:

\begin{minipage}[t]{0.3\linewidth}
	\wref{string:REPLACES}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{string:SUBSTITUTE}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{string:UNESCAPE}{}
\end{minipage}
\html{<br class="clear" />}

\subsection{Extended-Character word sets}
The Extended Character word set was introduced by Forth-\snapshot.

The following words make up \xref{wordlist:xchar}:

\begin{minipage}[t]{0.25\linewidth}
	\wref{xchar:X-SIZE}{} \\
	\wref{xchar:XC!+}{} \\
	\wref{xchar:XC!+q}{} \\
	\wref{xchar:XC,}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.25\linewidth}
	\wref{xchar:XC-SIZE}{} \\
	\wref{xchar:XC@+}{} \\
	\wref{xchar:XCHAR+}{} \\
	\wref{xchar:XEMIT}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.4\linewidth}
	\wref{xchar:XKEY}{} \\
	\wref{xchar:XKEYq}{} \\
	\wref{xchar:+X/STRING}{} \\
	\wref{xchar:-TRAILING-GARBAGE}{}
\end{minipage}
\html{<br class="clear" />}

The following words make up \xref{wordlist:xchar-ext}:

\begin{minipage}[t]{0.3\linewidth}
	\wref{xchar:CHAR}{} \\
	\wref{xchar:EKEYtoXCHAR}{} \\
	\wref{xchar:PARSE}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{xchar:X-WIDTH}{} \\
	\wref{xchar:XC-WIDTH}{} \\
	\wref{xchar:XCHAR-}{}
\end{minipage}
\hfill
\begin{minipage}[t]{0.3\linewidth}
	\wref{xchar:XHOLD}{} \\
	\wref{xchar:XSTRING-}{} \\
	\wref{xchar:[CHAR]}{}
\end{minipage}
\html{<br class="clear" />}
