cifgen.mi

dnl $ Id: $
dnl Copyright{2000,2024}: Albert van der Horst, HCC FIG Holland by GNU Public License
undefine({worddoc})
\input texinfo
@setfilename thisfilename
@afourpaper
@settitle Generating ciforth's
@setchapternewpage odd

@titlepage
@title ciforth Manual
A system to generate
a ciforth together with
its documentation.


@author Albert van der Horst
Dutch Forth Workshop

@page
@c @vskip Opt plus 1fill
Copyright @copyright{{}} 2024 Albert van der Horst

Permission is granted to copy with attribution.
Program is protected by the GNU Public License.
@end titlepage

@node top, , ,
@chapter Overview
forthvar({ci86.gnr}) is a system to build a ciforth in diverse
configuration's.
This is a configurators manual.
For each ciforth there is a corresponding documentation;
there is however just this one documentation for the generic
system.
What is common to all generated Forth's that they
are intended for the Intel 86 family and
comply in detail with DPANS 94 (ISO/IEC 15145), for the CORE wordset
at least.
It is assumed that you are familiar with Forth and with ciforth
in particular.
Linux is used for a development system,
and the main tool is forthprog({m4}) , the macro preprocessor.
@pindex m4
This extracts an assembler source file and a raw documentation file
out of the single generic source, controlled by a configuration
file.
In addition there is a file with blocks, that is common to all Forth's.
This library is a concatenation of blocks that handle options,
a system dependant file of error messages, and blocks with
utilities, the library proper.

For further processing you need an assembler, such as forthprog({nasm})
and one or more documentation tools, such as forthprog({info}). The raw
documentation file can be ordered only by a more sophisticated tool
than the usual forthprog({sort}).
Formerly I used forthprog({ssort}) a tool I wrote in C++.
In order not to make an already complicated
  forthprog({ciforth}) project dependant on C++,
I use a ciforth script forthprog({sortworddoc.frt}) to handle the sorting
since 2017.
@pindex sortworddoc.frt

The library contains indications in each index line (the first line of
a 16 line screen) that tell for what configuration
the screen is intended, e.g. 32 or 64 bit, and Linux or Microsoft.

@chapter Non-technical background.
@section                        Legalese
The Forth's called ciforth are made available by Albert van der Horst a
member of foundation DFW , the "Dutch Forth Workshop" .
The copyright still resides with him.
All publications of the DFW are available under GPL, the GNU public license.
The file COPYING containing the legal expression of these lines must
accompany it.

This forthsamp({ci86.gnr}) system is protected by GPL.
This applies to the generic source, the macro files and the Forth
source in the block file.

@subsection Copyright of the ciforth's build by this tool.
A ciforth extracted from  ci86.gnr is probably not a derived work
(a thesis written in TeX is not a derived work from TeX).
So Albert van der Horst separately claims copyright for the different
versions of ciforth generated by her using this tool.
On the other hand any copyright for a version of ciforth you build by
this tool is waived explicitly.

The following is present in all documentation of ciforth's:
forthquotation
Because Forth is ``programming by extending the language'' the GPL
could be construed to mean that systems based on ciforth
always are legally obliged to make the source available.
But we consider this ``fair use in the Forth sense''.
forthendquotation

In addition to the GPL the Albert van der Horst states the
following:

forthquotation
The GPL is interpreted in the sense that a system based on ciforth
and intended to serve a particular purpose, that purpose not being a
``general purpose Forth system'', is fair use of the system, even if it
could accomplish everything ciforth could, under the condition that the
ciforth it is based on is available in accordance to the GPL rules,
and this is made known to the user of the derived system.
Consequently, for these systems the obligation to make the source available
does not apply.
forthendquotation

@section Legal matters
My extensions are GPL-ed or library GPL-ed.
See the copyright documents that go with the distribution.
The original figforth is public domain and is still available.
@section                         Rationale

This has been split off of a similar generic Forth, that is intended
to be the last of the fig-Forth's. This generic system is no longer
maintained, but the last fig-Forth is, in the sense that if there
ever should be found a bug, it can be fixed. It also features
the Fig glossary, which I made available
in electronic form after scanning and OCR. I shamelessly
copied from it.
Apart from being ISO compliant, the Forth you have here is similar in many
respects to fig-Forth.
The motivation for having this type of Forth available follows from its
characteristics. It is available as an assembler source, and it is an
indirect threaded Forth.
An assembler source has distinct advantages for getting started.
An engineer might balk at the description of how to use a meta
compiler, but feels at ease with an assembler source.
(eForth, FIGForth, CamelForth, JonesForth  prove the popularity of
assembler source as a starting point for own developments.)

Although speed is currently in fashion, using subroutine threaded Forth's
with optimizers, indirect threading is the preferred choice for some
applications. I did this work, because I needed it.
I have also the firm belief that an optimizer on an indirect threaded system
has more information to work with and can ultimately outperform any
other system in speed.

@subsection               Source and Copyright
As discussed ciforth is released under the GPL.
In practice the GPL
 means (note: this is an explanation and has no legal value!)

They may be
further reproduced and distributed subject to the following conditions:

The three file comprising it must be kept together and in particular
the reference section with the World Wide Web sites.

This Forth builds on figforth, for its source see the next section.
The maintainer can be reached at forthmail({ciforth@@spenarnc.xs4all.nl})

@section History
From the introduction to the figforth installation manual:
forthquotation
The figforth implementation project occurred because a key group of Forth
fanciers wished to make this valuable tool available on a personal computing
level. In June of 1978, we gathered a team of nine systems level
programmers, each with a particular target computer. The charter of the
group was to translate a common model of Forth into assembly language
listings for each computer. It was agreed that the group's work would be
distributed in the public domain by FIG.

We intend that our primary recipients of the Implementation Project be
computer users groups, libraries, and commercial vendors.
We expect that each will further customize for particular computers and
redistribute. No restrictions are placed on cost, but we expect faithfulness
to the model. FIG does not intend to distribute machine readable versions,
as that entails customization, revision, and customer support better
reserved for commercial vendors.

Of course, another broad group of recipients of the work is the community of
personal computer users. We hope that our publications will aid in the use
of Forth and increase the user expectation of the performance of high level
computer languages.
forthendquotation

ciforth want to following in those footsteps.

@subsection                 Evolution off the FIG model

The first version of ciforth complied faithfully to the fig model,
at least as faithfully as is customary.
Now it is ISO compliant, which
means a lot of details are changed about how words work.
In the following we will discuss not some details and the changes
made to the general build up of the Forth.

The rigid subdivision in 7 area's was never adhered to.
In particular the boot up parameters
are not up front as CP/M and MS-DOS require a 100H byte reserved
area there.
There is mention of forthvar({(KEY)}) being ``implementation dependent code''
but these were not often present in
fig implementations.
This was based on the idea that there was some EPROM with console commands.
This has been replaced by calls to an operating system, that do
not
comply with a simple function that could be called.
Here
the code definitions for forthcode({KEY}) itself
become implementation dependent code, but often it can written in
high level.
An important change is that the character by character i/o of fig
( forthcode({KEY}) and forthcode({EMIT}) ) is replaced by the unix idea of buffer by buffer i.o
( forthcode({READ-FILE}) and forthcode({WRITE-FILE}) ).

All documentation has been updated to accurately describe
ciforth, and only ciforth.
The forthcode({RUBOUT}) key is a bona-fide forthcode({USER}) variable
and now has a name.

DR0 and DR1 are removed. There is only one consecutive mass storage area, be
it a disk or a file.
The assumption in using forthcodeni({OFFSET}) was that you could switch
the blocks to a different area on disk in order to accommodate users
with different needs.
Multi usage of the same Forth is nowadays an unlikely scenario.
Instead I put forthcodeni({OFFSET})
to good use to screen off a part of the floppy that must not be used (such
as an MS-DOS directory or the hard disk part that contains the forth system.)

forthvar({MOVE MON BLOCK-READ BLOCK-WRITE DLIST}) are not present.
Altering OUT to influence formatting doesn't work here, nor on
any figforth I know off.

forthcode({+ORIGIN}) now points to the boot up version of the first user
variable instead to some not well defined start of the boot image.
The layout has not changed, so the negative offsets can be used for
the other data traditionally there.
 Their indices have not changed, but there is now a boot-up
parameter for each and every user variable. A system with other boot
parameters can now be generated in an even more portable fashion by using
phrase like forthsamp({7 CELLS +ORIGIN}).

Where possible installation dependent code is using a generic call to the
operating system in particular MS-DOS BIOS or XOS. See below.
The false urban legend that one could forthcodeni({FORGET}) forthcodeni({TASK})
has been replaced by an accurate description of forthcodeni({TASK}).
The following words have been documented for the first time:
forthcodeni({FLUSH}) forthcodeni({CURRENT}) forthcodeni({2DUP})
forthcodeni({RP@@}) forthcodeni({U.}).

Some non-substantial deviation of the original FIG source have been made
for good reasons.

The FIG philosophy is that sectors, blocks and screens must be compatible, but
may be all different. The original 8086 FIG had one sector for a block. I
changed that in having one block for a screen. This is a boon for those
wanting to ISO-fy the sources.

The way I coded the character I/O points ahead to vectoring
forthcodeni({TYPE}) and forthcodeni({EXPECT}) rather than
forthcodeni({EMIT}) and forthcodeni({KEY}) . This way I can have the
host system handle the rub out key. See the above remark about unix
philosophy.

I added generic words for accessing system resources
forthcodeni({BIOS}) , forthcodeni({BDOS}) and forthcodeni({XOS}) .
(See subsection The joy of genericity.)

Some real errors were fixed:
forthenumerate
forthitem
The redefine forthsample({NULL}) bug is fixed.
It is no longer possible to redefine this word,
that handles the refill of the forthcode({TIB}),
by typing a <ret> immediately after a defining word.
forthitem
Forgetting part of a namespace, other than the forthcode({FORTH}) namespace
no longer crashes.
forthitem
Loading a screen with characters having an 8th bit set,
no longer crashes.
forthendenumerate

@subsection Evolution of ciforth
The first version of
ciforth  was in fact the
figforth for the 8086
that was put in the framework of this manual.
By adding a 32 bits macro file, programming
I/O for Linux, programming I/O  with non-obsolete MS-DOS calls
and a way to switch to protected mode,
this figforth came available in all ciforth configurations.
The RCS version numbers of the generic file fig86.gnr
are in the 2-branch and the latest version is available still.
(The 1-branch was experimental).
This version has however an manual not split between a generic and
a user part. But the user part of the manual forthemph({is})
generated from the generic source.
This version 2 can be seen as a 32-bit figForth.

The third and fourth
versions of ciforth (RCS branch 3 and 4)
are generated  according to this manual.
As you see there is little pertinent information about these Forth's
in this manual.
All the information you need to use it is in the user manual,
generated with that version.
Branch 3 evolves towards an ISO compatible system.
Version 4 is  a stable maintained ISO compatible system,
a balance between
technical criteria and compatibility issues.
It has a load-on-demand library facility: forthcode({REQUIRE}) which is a
quantum leap regards usability.

@ Release 5
The forthcode({REQUIRE}) facility of release 4 conflicted with usage of
forthcode({REQUIRE}) in other Forths.
So it was renamed in forthcode({WANT}) and this warrants a
major new release as it affects nearly all code.
Release 5 also sees a MS-Windows configuration that is based on calls
to DLL's instead of usage of DPMI (Dos Protected Mode Interface). That
means ciforth runs on the latest 32 and 64 bit MS-windows OS-es.
@section Acknowledgment
ciforth is based on the figforth
of Charlie Krajewski and Thomas Newman, Hayward, Ca.
This figforth (as are all figforth's) is public domain.
It is still available via taygeta. And of course kudos to FIG.

forthurl({ftp://ftp.forth.org/pub/Forth/compilers/native/dos})

This original version is public domain according to the
following statement:

forthquotation
All publications of the Forth Interest Group are public domain. They may be
further reproduced and distributed by inclusion of this credit notice:

This publication has been made available by the Forth Interest Group,

              P. O. Box 1105,  San Carlos, Ca 94070
forthendquotation

I also want to thank  J. E. Smith, Philadelphia for another fig Intel86
implementation was obtainable from
forthurl({http://www.simtel.net/pub/simtelnet/msdos/forth/fig86.zip})
(You'll could use the wayback machine though, as per 2018).

This is a fairly good documented FIG Forth for IBM PC, but its
"Seattle Computer 8086 assembler" format makes it less practical.

@chapter Background.
If you are a Unix and a Forth guru, you can skip this chapter.
_VERBOSE_({ If you think you are,
you can read this chapter and discover you are not.})
This chapter is about pervading concepts and
how tools are used, conceptually.

@section Orthogonality
The concept of orthogonality is central to this effort.
Orthogonality means that different aspects of configuration
(in this case)
are made independent of each other.
For example, ciforth can be bootable or started by MSDOS,
it can be assembled by forthprog({nasm}) or by forthprog({MASM.EXE}) .
@pindex nasm
@pindex MASM.EXE
These two choices can be made independently from each other,
and every combination ought to work.
Each choice is associated with file with macros for forthprog({m4}) ,
so ideally if you need to specify that the assembler source
is extracted in a form suitable for forthprog({nasm}) you
only need to use the file forthfile({nasm.m4}).

This is, of course, as far as it goes.
Try as you may to separate all information about header layout
in the forthfile({header.m4}) configuration file,
a change to the order of the fields in a header will certainly have
it impact at certain places in the source.
(This applies to early versions of forthprog({gas}), and it required
 forthprog({sed}) scripts on top of forthprog({m4}) )

@section Metacompilation a remark
Meta compilation, the generation of a new version of a Forth system
by ``similar tools as compilation'', was already done
with the cassette based computer system of the late seventies.
Metacompilation is mainly used to generate
a similar forth for a forthemph({different}) processor or system.
This would properly be called cross-compilation, by the way.
On a half-decent (or better) disk operating system like MSDOS the use
of meta-compilation works more smoothly.

We want our Forth to be able to generate standalone programs anyway.
(a forthdefi({turnkey}) facility.)
So what do we need
forthenumerate
forthitem
A facility to save a running system with all what is loaded on it,
in the configuration it currently has.
forthitem
A facility to remove parts of a running system, that are not needed
for an application after it has been build. (E.g. the assembler.)
forthitem
A facility to optimize some parts of a system. (Then remove the,
possibly large, optimizer.).
forthendenumerate

If you have the first facility,
you can build a powerful Forth from a small kernel and regular source code.
If you have all of them, you can build a truly,
optimal Forth from a small kernel.

The forthcodeni({SAVE-SYSTEM}) facility of course requires
in depth knowledge of the operating system.
This doesn't mean it is cumbersome or difficult.
Under Linux (a.d. 2000) we need
forthexample(
dnl NOTE! All @ must be doubled for tex.
{HEX
\ The magic number marking the start of an ELF header
 CREATE MAGIC 7F C, &E C, &L C, &F C,
\ Return the START of the ``ELF'' header.
 : SM BM BEGIN DUP @@ MAGIC @@ <> WHILE 1 CELLS - REPEAT ;
\ Return the VALUE of ``HERE'' when this forth started.
 : HERE-AT-STARTUP  ' DP >DFA @@ +ORIGIN @@ ;
\ Save the system in a file with NAME .
 : SAVE-SYSTEM
\ Increment the file and dictionary sizes
  HERE HERE-AT-STARTUP - DUP SM 20 + +!      SM 44 + +!
   U0 @@   0 +ORIGIN   40 CELLS  MOVE \ Save user variables
\ Now write it. Consume NAME here.
   SM    HERE OVER -   2SWAP   PUT-FILE ;  DECIMAL
})
Actual code as per 2018 may be different, but is hardly more involved.

@section How m4 is used.
The Unix macroprocessor forthprog({m4}) is very powerful indeed.
@pindex m4
Testimony is that the description of its usage in here
is longer that its man-pages.
You know
forthprog({m4}) is a text substitution tool.
A macro is like a function. In the macro call the text is replaced by
the text present in the function.
Within the text the placeholders for the parameters are replaced
by the actual parameters.
In forthprog({m4}) the placeholders are forthsamp({$}{1}) ... forthsamp({$}{9}).
Parameters can be passed, and any (even multiline)
text can be given as a parameter, provided it is quoted.
We will use forthsamp({_lbracket_}) and forthsamp({_rbracket_}) (braces) throughout.
This is convenient, because they are
not used in a Basic Forth system
and  they are
special anyway (e.g. for TeX).
The use of quotation is very critical at times,
and the fine points are not covered in the following.
@subsection Customization
Plain use of m4 is the use of macro's to just define a string
that is different under different circumstances.
Simple customization can be done by forthprog({m4}) as follows:

 forthsamp({define(_lbracket_version_rbracket_,2.149)})

Within the text treated the version number is substituted.

Among those we also have segment definitions, defined in the m4 file
belonging to the assembler used.

_TEXT_ : This introduces the part of the Forth with the definitions.
It is supposed to be stored on disk.
Normally it is modifiable, so e.g. VARIABLE's can be in here.

In the circumstance that there is separation of code and data,
there is the another segment
_DATA_ : modifiable data, not machine-executable code
This is important if the underlying operating system doesnot
allow the modifiation of code.
In that case the _TEXT_ segment is non-writable.
Most Forth's to date can get by with this data in the _TEXT_
segment.
This macro is conditional on _SEPARATED_.
So mostly _DATA_ is a void statement.

_BSS_ : This part of the Forth imposes a layout without
initialising the data.
It agrees with a traditional bss segment in e.g. an a.out format.

_IDATA_ : As an exception extra segments has to be introduced.

@subsection Selection
Selection, often one of alternatives, is in general done as follows

forthsamp({_BITS16_(32)_BITS32_(64)_BITS64_(128)}) ,

which gives, of course, the size of a double number.

This is accomplished by

forthsamp({define(_lbracket__BITSxx_  _rbracket_,_lbracket_$1  _rbracket_)})

for the actual bitsize and

forthsamp({define(_lbracket__BITSxx_  _rbracket_,)})

for others.

This is made easier with the forthsamp({_yes}) and forthsamp({_no}) macro's,
see forthfile({prelude.m4}) .

Selections can be nested within other forthprog({m4}) macro constructs.
As in
forthexample(
{{_VERBOSE_}_lbracket_({_BITS64_}(_lbracket_The possibility to cycle through all (64-bit)
numbers by {forthsamp}(_lbracket_0 0 DO ... LOOP_rbracket_) is very useful indeed._rbracket_)_rbracket_)})
Here you see at work, apart from forthmacro({_BITS64_}) , the macro forthmacro({_VERBOSE_})
that allows (if turned on)
verbosity that can help understanding but is not always appreciated.
You also see forthmacro({forthsamp}) that is in fact
a markup to indicate we have a piece of Forth code there.

Selections can be used to throw out a block of
word definitions and their documentation as a whole.
For example words interfacing with an MS-Windows o.s. make
no sense in a Linux Forth.

The braces are essential here.
Without it the introduction of a comma somewhere in the text
results in forthprog({m4}) interpreting the remainder as a second parameter,
which it will ignore.

@subsection A postponed markup language.
In documentations files you
just say forthsamp({forthcode(_lbracket_+LOOP _rbracket_)}) to indicate that you want
formatting as for ``code'' words.
Later you can decide to use
forthbreak
 forthsamp({define(_lbracket_forthcode _rbracket_,_lbracket_@@code_lbracket_$}{1_rbracket__rbracket_)})
forthbreak
for forthsamp({texinfo}) or
forthbreak
forthsamp({define(_lbracket_forthcode _rbracket_,_lbracket_<B>$1</B> _rbracket_)})
forthbreak
for forthsamp({html})
.
@subsection Defining structures
Some macro calls must be considered to define a structure, in particular
 forthsamp({worddoc}) .
Suppose we have a list of structures, meaning that the first person is
a child of the second and third person:

parents(_lbracket_Alice_rbracket_,_lbracket_Mary_rbracket_,_lbracket_John_rbracket_)

parents(_lbracket_Fred_rbracket_,_lbracket_Mary_rbracket_,_lbracket_Henry_rbracket_)

parents(_lbracket_Aayilah_rbracket_,_lbracket_Sjantil_rbracket_,_lbracket_Bodaji_rbracket_)

...

With
 forthsamp({define(_lbracket_parents_rbracket_,_lbracket_$2_rbracket_)}) we get a list of (you guessed) the mothers.

The usage of forthmacro({divert()}) can best be explained with an example in this context.

forthexample(
{{define(_lbracket_parents_rbracket_,
_lbracket__lbracket_divert(3)dnl_rbracket_
$}{2
_lbracket_divert(6)dnl_rbracket_
$}{3
_rbracket_)}})

will give out the mothers on channel 3 and fathers on channel 6.
The output will be concatenated,
but all mothers and all fathers stay together.
For forthsamp({dnl}) see the forthprog({m4}) man-page.

@subsection Defining lists
By using an extra pair of braces you can have a list in forthprog({m4}) .
So forthsamp({_lbracket__lbracket_A_rbracket_,_lbracket_B_rbracket_,_lbracket_C_rbracket_,_lbracket_D_rbracket__rbracket_}) is
a single parameter to a macro and can
be passed to other macro's as a whole.
The outer braces are removed and
without special measures (reinstalling extra braces again)
the macro called forthemph({sees})
the comma's and concludes there are four parameters.
This is put to good use in the ``See also'' and ``Test''
fields of the forthsamp({worddoc}) structure.
These fields may have zero or more parts.

The ``Test'' field contain the tests in the odd fields, and the
expected outcome in the following even fields.

@subsection Defining aliases
Sometimes you need aliases, i.e. other names for macro's,
Although it doesn't properly belong here as a technique, I want
to mention it, because the amount of brackets is hard to sort
out. An alias is useful in a transition period, where you want
to rename something, but where you want to be able to do that
gradually on a file by file basis.

 forthsamp({define(_lbracket__OLDNAME__rbracket_,_lbracket__NEWNAME_(_lbracket_$1_rbracket_,_lbracket_$2_rbracket_)_rbracket_)})

After forthvar({_OLDNAME_}) is phased out everywhere this definition can be deleted.
Note that for this to work all parameters applicable to forthvar({_NEWNAME_}) must be
taken into account, the two shown here are just an example.

@subsection Impress the crowd
By using macro's to define other macro's, then pass the result through
forthprog({m4}) another time, severe stress can be laid upon the intelligence
of the everyday person.
The very inconvenient way nodes must be linked in texinfo even forced
me to define part of the macro in one macro and the remainder in
another.

@section How the glossary is ordered.
The sorting tool forthprog({ssort}) can order multiple field records, with
different sorting criteria for each field.
The fields can be defined by regular expressions, such that
the forthsamp({worddoc}) structures can be sorted by name, or by wordset
then by name, or in about any way you want.
Because such a tool didn't exist, I had to write it.
This tool was in use until release 5.3.
From that time on ciforth itself is used for ordering,
using a small program forthfile({sortworddoc.frt}) .

@subsection Analyzing forthsamp({worddoc}) using forthcode({ssort})
 forthprog({ssort}) captures the structure of a forthsamp({worddoc}) as follows:

 forthsamp({^worddoc(_lbracket_@@_rbracket_,_lbracket_@@_rbracket_.*\n$worddoc})

The part between forthsamp({^}) and forthsamp({$}) matches the record.
The part after the last forthsamp({$})
is for synchronization, to make sure the record doesn't end early.
This would result in an error ``not according to structure'': the next
line doesn't start with ``worddoc'' and so it just doesn't match the record
description.
The forthsamp({$}) is merely a separation, (newlines are indicated by forthsamp({\n}) ).
The forthsamp({.*}) matches anything, including new lines.
But it isn't greedy as in ordinary regular expressions,
because not being stopped by forthsamp({\n}) ,
it would match the whole file.
Here it tries to match as little as possible.
 forthsamp(@@_rbracket_) is shorthand for forthsamp([^_rbracket_]*_rbracket_$)
so a ``sequence of anything except
right braces followed by a right brace''.
It also contains the forthsamp({$}) to
mark the end of a field.
@subsection Sorting fields
Once we know what the fields are,
 forthsamp({-M 1S2S }) sorts on the first field
and within that field on the second. We just use the ordinary ASCII collating
sort, indicated by forthsamp({S}) .

The program forthfile({sortworddoc.frt}) does the same,
but it is coded in Forth.

@chapter Structures and processes
@section The generic source file
The generic source file forthfile({ci86.gnr}) mostly
consists of Intel assembly code, with which, I assume,
you are familiar. All macro's in the following are forthfile({m4}) macro's.
Words are divided in small (<20) groups of cooperating words,
the forthdefi({wordset}). See also ``thinking Forth''.

The things that differ among assemblers, are taken care of by
macro's, e.g. forthmacro({_COMMENTED},$1) brackets a comment.
One of the most important is forthmacro({DC}) that lays done a cell
in memory. Not only is this different between 32 and 64 bit Forths's,
even such a simple command differs among assemblers.
Most of the time they don't have parameters.

The selection of parts that go or don't go into a particular configuration
is done by multiline macro's, generally with a call on a separate line.
Such as:
forthexample({
{_HIGH_BUF_}(_lbracket_
BUF1    EQU     EM-(KBBUF+2*2)*NBUF      ;_lbracket_ FIRST DISK BUFFER_rbracket_
STRUSA  EQU     BUF1-US         ;_lbracket_ User area_rbracket_
_rbracket_);{_END_}(_lbracket_ _HIGH_BUF__rbracket_)  })
Note how comments are protected from macro expansion by quotation.
The forthmacro({_END_}) is an adornment. It expands to nothing.
So it doesn't show up in the output,
but it helps to keep the generic source organized.

The forthmacro({worddoc}) macro defines a structure with additional information
of a word.
Generally it is placed in front of the word.
The same word can be found several times in the input file,
but only one is selected in a particular configuration.
The same goes for the corresponding forthmacro({worddoc}) .
forthbreak
Its fields are:
forthenumerate
forthitem
Wordset name.
forthitem
Word name.
forthitem
Pronunciation.
This is a pure textual and pronounceable identification of the word.
It is also used in forthfile({texinfo}) that doesn't handle special characters well.
forthitem
Stack effect.
The stack effect obeys all the conventions put forth in the user manual.
forthitem
Properties.
Properties are i.a. immediate and such, and the standards with which
this word complies.
Again this is described in the user manual.
forthitem
Description.
forthitem
References.
This is a list of names of other Forth words,
that can be studied to better understand this one.
forthitem
Tests.
This is a list.
The first and all other odd members is a test,
code that can be passed to Forth.
The second and all other even members is the expected outcome of the
preceding test.
forthendenumerate
forthmacro({worddoc}) are such that a structure starts with forthsamp({worddoc( })  and
end with a forthsamp({_rbracket_)}) at the end of a line.
This means that a worddoc
can be simply skipped if it occurs in Forth code,
by defining a word forthcode({worddoc(}) that reads and ignores source up to the
end sentinel.

The forthmacro({worddocchapter}) macro defines a wordset.
It has the same fields as a forthmacro({worddoc}) macro,
but most are left empty.
It is primarily used for its ``description'' field,
that is used as an overview description for the wordset in glossaries.
These macro's can be put anywhere,
but take care to exclude macro's for wordsets that are not present.

@section The process
The ultimate information about how a ciforth is generated are the makefile's :
 forthfile({Makefile}) and forthfile({test.mak}) .

The process of generating a program proceeds along the following steps:
forthenumerate
forthitem
Extract the assembler source from the generic source via a configuration file.
The file suffix indicates which assembler to use.
forthitem
Generate an object file.
forthitem
Link the object file.
forthendenumerate
Once you have an assembler file, you can do what you want with it.
Proceeding from an assembler source file to a binary is in general
straightforward.

The process of generating program's documentation
(TeX and info)
proceeds along the following steps:
forthenumerate
forthitem
Generated the raw glossary documentation
from the generic source via a configuration file.
The file suffix is forthfile({.rawdoc}) .
forthitem
Sort the forthfile({.rawdoc}) file,
such that words of a wordset appear together,
and are preceded by a wordset documentation.
The file suffix is forthfile({.mig}) .
forthitem
Generate the glossary documentation from the forthfile({.mig})
by expanding the forthmacro({worddoc}) 's into glossary entries by
forthfile({gloss.m4}) or forthfile({glosshtml.m4}) .
This, for a second time (!), takes into account the configuration file{}_VERBOSE_(
{, to generate exactly fitting information}).
forthitem
Expand the ``postponed markup's '' in forthfile({ciforth.mi})
by the macro's from forthfile({manual.m4}) to
generate the texinfo commands.
This file include all the other forthfile({.mi}) files with postponed markup's.
forthendenumerate

The process for generating html has the postponed markups and the
expansion into glossary entries in the same file forthfile({glosshtml.m4}).
Only the documentation of the glossary enters into html ,
and the forthfile({ciforth.html}) is generated from the intermediate
file forthfile({.mig}).

Generating documents is made more complicated by the requirements for special tables.
For forthsamp({html}) we want an extra alphabetic list of all the words where we click on to
get at the glossary entry immediately.
forthbreak
In forthfile({texinfo}) we need to build complicated menu structures, that refer back and forth.
forthbreak
This is done by separate passes over the forthfile({.rawdoc})  or forthfile({.mig})
files, with other macro's.
@chapter Production,
After all the explanations of tools, we're now in a position to actually
build a Forth compiler.
@section Overview

There is one generic source file, where documentation, test and code
of a Forth definitions are kept together. m4 selects and extracts the
assembler code, a test, and documentation paragraphs, meanwhile making
slight adaptations. The assembler file is turned into a runnable program.
The texinfo file is turned into whatever documentation format.
The testfiles consists of runnable code, and the expected outcome.

@section Design decisions
Is has been explained why this Forth is restricted to the Intel 86.
Not much more can be said for such a highly configurable system,
but in this section we will try to illuminate major design decisions.

@subsection Assembler language
ciforth borrows the distribution strategy philosophy from the old figforth.
It is in fact based on it, and its documentation in first draft
copied from it.
The Forth's are build from an assembler source, and it is in general an
indirect threaded Forth.
FIG produced a first source for a new processor as
a text file, using an existing Forth,
with many parts just copied from that Forth.
In this way the FIG working group produced a printed copy
of an assembler source for every processor in existance at 1980.
Strictly adhering to the assembly language as defined by the chip
manufacturer, allowed to type in from hardcopy, then build the
Forth using any conforming assembler and little, or nothing, more.
ciforth tries to reproduce this desirable situation.

An engineer might balk at the description of how to use a meta
compiler, which means specifying a Forth at an abstract level,
but feels at ease with a (much larger) assembler source and can
easily make modifications, an empowerment much talked about
in the era of the Free Software Movement,
but not much practiced.

@subsection Indirect threaded
Although speed is currently in fashion, using subroutine threaded Forth's
with optimizers, indirect threading is the preferred choice for some
applications.
I did this work, because I planned to use it
for work in artificial intelligence.
A forth has the property like lisp that a running system can
add definitions to itself.
An indirect threaded Forth has the same property than is present
in some lisps that even very basic word can be rewritten
on a running system and take effect immediately.

Furthermore the current trend of subroutine threaded Forth's may very
well be unsuitable for 64-bits processors like the Alpha.

@subsection bit-size indifferent
It is unusual for a forth to be configurable as 16, 32 bit or 64 bits.
It turned out that the addition of forthcode({CELL+}) goes a long way
toward allowing
utilities like a decompiler to be 16/32/64 bit clean.
In the documentation mostly reference to cells can be made.
But the macro's
forthsamp({_BITS_})
forthsamp({_BIT16_}) and
forthsamp({_BIT32_})
forthsamp({_BIT64_})
can be used to signify the actual number of bits and parts to refer
to 16, 32 and 64 bits only respectively.

@section System requirements

The host requirements, for building, are different from the
target requirements, for running.
In practice the generic system must be run on a GNU Linux system.
This generated Forth can target almost anything.
At least it runs on industry standard hardware
("PC's") : standalone, under Linux and under MSDOS/MSWINDOWS.

To build, you need a version of forthprog({nasm}) , forthprog({TASM.EXE}) or forthprog({MASM.EXE}) on your system.
As of 2018 forthprog({fasm}) is the assembler of choice as it allows
the building of binaries without a linker.
Also it can build MS-Windows executables on a linux system.


@section Different assemblers

The difference between high level languages and assembler can be summarized as follows.
Two compilers for e.g. forthprog({ADA}) accept the same source and produce different binaries,
that however are functionally equivalent programs.
Two assemblers produce byte-for-byte same binaries, but the
functionally equivalent sources may exhibit substantial difference.
A diff file may be as long as the source itself, on the account
of differing comment symbols, or the habit to prefix register names
with '%', or the order of operands.

The ciforth system has a provision that during extraction of the
actual assembler source such things as the comment symbols and the directives
are adapted to the actual assembler.

@subsection Actual assemblers used
To build, you need a version of forthprog({nasm}) , forthprog({TASM.EXE}) or forthprog({MASM.EXE}) on your system.
As of 2018 forthprog({fasm}) is the assembler of choice as it allows
the building of binaries without a linker.
Also it can build MS-Windows executables on a linux system.

An other commendable assembler is forthprog({nasm}) , it is an open source assembler and available on different
platforms, at least MSDOS and Unix, and most importantly OSX.
It solves a lot of the design errors I
find in the Intel ways of forthprog({MASM.EXE}) .
It is easier to use than the GNU forthprog({as}) because it adheres more
to the Intel syntax.
Another advantage is that it can generate a binary without a linker.
On the opposite side, e.g. Borland's forthprog({TASM.EXE}) you can buy (as per 2000)
only as part of a giant C++ package.
If you want to use the generic possibilities you will need a Unix system
with all of its tools.
I have successfully used GNU-Linux (RedHat , Suse, Debian) to
 do the makes and version
control on that. If you want your bootable floppies made from Linux to be
MSDOS-compatible you need mtools.

@section example of how sources are extracted.

The file forthfile({alone.asm}) can be assembled using forthprog({nasm})
which can be concluded from the extension forthdefi({asm}) .
It includes a boot
sector such that it can boot from a standard floppy on a industry standard
Intel PC.
If you have the mtools set (most Linux's have it) the Makefile
shows you how to make the floppy.
On MSDOS you can use forthprog({DEBUG.EXE}) .
If you run on Linux with
 forthsamp({mtools}) , forthsamp({make boot}) will do it.
The resulting floppy will even be recognized by
MSDOS, such that you can copy block sources to it.
 forthsamp({make moreboot})
will do this from Linux, then you will have forthfile({forth.lab})
available.
forthsamp({make allboot})
will do it all, but it needs a working forth
on Linux for doing some calculations.
Otherwise on MSDOS (I recommended version 3.3, the most stable MSDOS ever)
adapt the example forthfile({genboot.asm}) .

The file forthfile({msdos.msm}) can be assembled
using forthprog({TASM.EXE}) and forthprog({MASM.EXE}).
The resulting Forth
executable can be run off hard disk and respects the file system on it.
It uses the file forthfile({forth.lab}) .

@section customizations

In this section the different ways the generic ciforth system can
be used to produce a Forth of your liking. They require different
expertise and target a different audience.

@subsection Overview
As was mentioned before, ciforth has one single source file: the generic forthfile({ci86.gnr}) .
All advantages of assembler source would be gone, if an engineer were
confronted with conditional compilation and lots of code for other systems
he doesn't want to learn or assemblers he doesn't want to use.
So we proceed in two steps. First a clean assembler source is generated from
the generic Forth using configuration files. Then the assembler source is
processed in one of a number of ways, each way familiar to one brand of
engineers.
The clean assembler source is the preferred form of publication,
because it is the most usable.

You can customize at a number of levels.
forthenumerate
forthitem
Configuration files have extension forthsamp({.cfg}) , these are files with forthprog({m4})
commands. They are intended to use at the highest and easiest level of
configuration. The usage is simple. If you want a Linux Forth use forthfile({lina.cfg}) .
forthitem
forthprog({m4}) files have extension forthvar({.m4}), and control one aspect of genericity, such
as which assembler or the protection mode. You definitely need to know forthprog({m4})
to adapt or create these.
forthitem
Assembler files can be customized in the traditional way by adopting
constants, or commenting in source lines. The assembler files are distinct
from the one generic source. No forthprog({m4}), you need only cope with the directives
of your assembler, and you will not see any code applicable to other operating
systems or I/O systems. (It is not commented out, it is just not there.)
forthitem
You can adapt the generic system.
This is difficult, but can accomplish a lot.
If you manage to adapt it to the ARM,
the result is a lot of ARM Forth's.
One of those will run on ARM Linux, but, try as you may,
none will run on MS-Windows.

forthendenumerate

@subsection Level 1 customization.

This is assuming you run on some sort of Unix.
This amounts to using, maybe adapting or creating one of the configuration
files with extension forthcode({.cfg}) .
Sensible choices will in general lead to a usable Forth's.
A source file that is extracted may need to be assembled on a target
system. Fortunately Unix in particular GNU/Linux can emulate
almost everything.

By specifying what you want in a configuration file you can generate a host
of assembler listings. This is as simple as replacing ``_yes'' with ``_no'' in
configuration files.
See the examples forthfile({msdos.cfg}) and forthfile({alone.cfg}) and the Makefile.
You can find out what the options are by inspecting forthfile({prelude.m4}) .

There is a division of labor between your configuration file
and the forthfile({prelude.m4}) and forthfile({postlude.m4})
files. forthfile({prelude.m4}) sets all variables to defaults,
for sets of alternatives this is NO, waiting to be overwritten.
For the other options it is the most sensible one. You must
include forthfile({prelude.m4}) first in your configuration
file. Then you specify your configuration and include
forthfile({postlude.m4}). forthfile({postlude.m4}) will correct
the options to the most, or the only, sensible ones for that configuration.
It will reject some of the configurations that will not
assemble, or lead to programs that do not work, by aborting.

After including forthfile({postlude.m4}) you can
overwrite some of the sensible defaults.
So you can force the generation of source
that is rejected by the assembler anyway.
An example is the default stack size of 64K
for 32 bit programs. Sensible as it is, you may want to have a
32 bit Forth that uses little memory. You will overwrite that stack
size. Be careful.

@subsubsection Assemblers
With respect to the assembler you can choose between forthprog({nasm}) and forthprog({MASM.EXE}) , with
file extension forthfile({.asm}) and forthfile({.msm}) respectively.
The forthvar({.msm}) are acceptable by
NASM.EXE too.
You can generate an equivalent forthfile({.s}) file, but this requires
care in selecting a proper GNU as assembler.
_VERBOSE_({{
I have reported problems in generating a forth using the Intel 86,
GNU tools. Whether or not the problems could have been overcome
at the time, at least from kernels 2.4.x on, GNU tools should be
able to generate a Forth.}})
And the newcomer is forthprog({fasm}) using the extension forthfile({.fas})

@subsubsection Host
With respect to the hosting you can choose between forthmacro({_HOSTED_}) ( forthmacro({_HOSTED_LINUX_}) or
 forthmacro({_HOSTED_MSDOS_})) and forthmacro({_BOOTED_}) . ( forthmacro({_BOOTFD_}) or forthmacro({_BOOTHD_}) ).
Since release 5 there is also the choice of forthmacro({_HOSTED_OSX_}) and  forthmacro({_HOSTED_DLL_})
A host dictates what I/O one has to use.

A hosted version relies on MSDOS or Linux or other operating system
to get the program started.
(It may or may not use MSDOS for I/O, once started.).
A forthmacro({_BOOTED_}) version contains a boot sector, such that
you you can make a standalone version that boots from floppy or hard disk.
A forthmacro({_BOOTED_}) version may very well be startable from plain DOS and its files
visible from DOS.

Of course a forthmacro({BOOTED_}) version that tries to use MSDOS I/O (or Linux) crashes
immediately, so not all versions are useful.

You have a choice between 16 or 32 bit protected mode and real mode.
Of course on Linux real mode is not an option, (but you could run the
MSDOS emulator). Protected mode Forth's for MSDOS cannot be started from
virtual real mode, e.g. they will not run in a "DOS box" in Windows
or Linux.

@subsubsection Basic I/O
With respect to I/O on Linux you can choose between c-based and native.
The c-based version may be portable to other I86 unices.
All Linux versions have their blocks in a file. (Accessing
a floppy in the classic way is perfectly possible -- and implementing it would
be a perfectly pointless exercise.)
As per 2018 a warning is in order for the c-based version.
It has not been generated, leave alone tested, since 2003.

The native version of course uses system calls directly and lina
is expected to be not portable to other unices.
However this hinges only on the numbers used for system calls.
Surprisingly, Intel bases Apple systems, very old kernels and BSD
systems run lina with few problems.

On MSDOS you can choose between three sets of I/O facilities,
I/O (words like forthcodeni({EXPECT})
forthcodeni({R|W}) )
You can use dos forthmacro({_CLASSIC_}) in the classic way as with the original. This
means that the floppy is used directly without regard for directory
structures. This uses calls that are declared obsolete.
You can use dos in a modern way. forthmacro({_MODERN_}). This allocates block in the
file with name forthfile({forth.lab}) . This name is available in the string forthcodeni({BLOCK-FILE})
for you to change, also at run time. No (as of 2000 ) obsolete MSDOS calls
are used (Checked against MS-DOS programmers reference "covers through
version 6" ISBN 1-55615-546-8)
You can use the BIOS forthmacro({_USEBIOS_}) No MSDOS interrupts are required.

On MS-Windows there are two options. forthmacro({DPMI}) is very restricted
MS-DOS compatible, and forthmacro({DLL}) works on the modernest systems.
We can paint with a large brush here because the ciforth kernel has
only facilities that are
common to all existing MS-Windows versions (from 3.11 to 10).
Executable formats are not compatible though.

@subsubsection Conflicts
If you specify conflicting options by accident
the preprocessor (forthprog({m4})) breaks
off and you can look up the exit code in forthfile({postlude.m4}) .
Than you can reason back why this is a conflict.
For example error 1000 indicates floppy and hard
disk i/o at the same time.
From forthfile({postlude.m4}) you see that forthmacro({_RWFD_})
and forthmacro({_RWHD_}) are on at the same time.
forthmacro({_RWHD_}) is turned on because you wanted to boot
from hard disk or you specified it yourself in the first place.

forthfile({postlude.m4}) does you another favor. It derives
logical consequences, such as once you decide for a
forthmacro({_REAL_}) mode Forth, it must be
forthmacro({_BITS16_}) and you need not specify,
In particular forthmacro({_LINUX_N_}) or
forthmacro({_LINUX_C_}) by themselves
define a whole configuration.

There is no guarantee, that all conflicts are detected.

@subsection Level 2 customization.

So you have this Forth.
and it looks like what you want to have, but not quite.
And it almost does what you want, almost.
Well, you can modify it is as you would expect for
a decently documented, parametrized source.
Changing a parameter in the start of the program may
go a long way to help you out.

The change of a word from high level to assembler for speed,
or the addition of word needed in your particular circumstances
is straightforward.

All these small alterations only require understanding the
assembler file.

@subsection Level 3 customization.
Level three customization is the a fundamental redesign
of the Forth itself.
An example is -- something I would like to do myself -- is to add
the source code of the word into the binary and add a field to point
to that. Or you'd want so many flags (more than 64) that you need a
second flag field. Or you'd change the threading from indirect to direct.
Both are fundamental changes that can be accomplish by
adapting only one file, forthfile({header.m4}).
Then there may be the need for another assembler format.

It is clear that you really have to understand the generic system,
to do this.

@subsection Level 4 customization.
Adapting the package to a different processor will change every
assembler instruction in ci86.gnr. This may be quite an undertaking,
but the documentation, the testing and the library don't change.
The author was able to have a fully tested, fully documented
Dec Alpha version in 13 days, wall clock time.
If you want to adapt to a different processor, please contact.

Of course in order to do this you really have to understand the
generic system, but in less depth than for level 3.

@section Some remarks about the library
In the file forthfile({forth.lab}) is available a assembler, decompiler
and tools like forthcodeni({DUMP}),
Beware! Some of the tools handle hards disks.
There are example programs and benchmarks.
Everything up till the screen marked forthsamp({end of lab})
you will find more or less working, but maybe not all of it on all systems.
Everything loaded from the electives screen (option -e screen 5)
is used by me on a regular basis and is 16/32/64 bits clean.
Beware! The full screen editor is specific to old MSDOS systems,
although it may work under emulations like dosbox.
The WANT system prevent loading it under Linux even if you try.
Several examples implementing the functionality of
forthprog({wc}) demonstrate the use forthprog({lina}) as a scripting language.

@section Web sites and availability.
A newer or improved versions may be gotten from
 forthurl({ https://github.com/albertvanderhorst/ciforth })
 forthurl({http://home.hccnet.nl/a.w.m.van.der.horst/ciforth.html})
Nasm is found at

ftp://ftp.us.kernel.org/pub/software/devel/nasm/source/

forthurl({http://www.cryogen.com/Nasm/})

The FIG source this is based on was at simtel in better times.

MASM.EXE is available from IBM, at least the version 1.0 I used.
Microsoft seems to distribute later versions.

The original fig documentation is obtainable via
 forthurl({http://home.hccnet.nl/a.w.m.van.der.horst/figforth.html})
This include the pictures.

@chapter Releases and release numbering

For the plethora of release possibilities read the file
 forthcode({howto.txt}) .
It is dated, only use descriptions that
applies to your point in the history, i.e. they are not
overwritten at a later point in history.
The Makefile contains important release targets, some but not all
described in howto.txt. Some targets are stale.

Files with the extension forthsamp({.bat}) are scripts that are up to
date.

An official release has identification #.#.# .
Snapshot release have identifications 'beta #.NNN'
where forthvar({NNN}) is as appropriate: the RCS version
number. Snapshot releases in git have an identification based on the
date, similar to forthsamp({2017dec09}) .
The startup message contains the word "beta ",
unless it is an official release.

At the start of 2018 there are make targets for configured versions
but none to publish the generic system.
@section Bugs
See the separate test report for an indication of which and how far
versions have been tested.

The websites where ciforth is published indicate where bug reports
can be send to.

@chapter Blocks

The block stuff is considered by many as legacy in Forth.
What little advantage it had, seems to be no longer applicable.

@section Why blocks?
Blocks can still be put to good use.
Their original forte still holds. They are a good store for
small code snippets, that all can be loaded separately as wanted.
For more see the word forthcode({WANTED}) in the user documentation.
@section Blocks implementation in ciforth
The original fig block system was copied verbatim into ciforth.
It is designed for a slow background store, and keeps blocks in memory
as long as possible. However at the load of each new block, the current
block could be swapped out. In case of nesting, a block that is being
interpreted, at the moment the interpreter returns to it, must be reloaded
from mass storage. What is worse, this condition must be checked all
the time.
This leads to the complicate rules around forthcode({ BLK}) and
forthcode({SOURCE}) in the ANS standard document and overhead
in compiling.

In ciforth this is replaced by a locking mechanism.
All blocks being interpreted at whatever nesting level are locked in memory,
i.e. they can not be swapped out until the lock is released.
Moreover the underlying buffering mechanism is made general.
A block number is considered the identification of a buffer.
Locking 15 means that a buffer is allocated to block 15, but the block
is not read from disk. That means that you can use
forthsamp({id})'s outside of the block range
can be use to lock buffers, e.g. as file buffers for line by line reading.

To replace blocks in ciforth (2001) I did the following.
forthenumerate
forthitem
There is a very simple forthcode({INCLUDED}) to compile files.
This eliminates the necessity to use
blocks for the development of user programs.
forthitem
Blocks are always forthcode({UPDATE}) 'd immediately. This makes words
like forthcode({FLUSH}) trivial.
forthitem
forthcode({BLK}) and its ilk are defined by second guessing. They do not
dictate what is going on. This is contrary to ISO, but makes the
basic system so much cleaner.
Blocks that load other blocks are forthcode({LOCK}) ed
during that time, so that forthcode({WORD}) need not constantly look
whether the rug is pulled out from under it.
forthendenumerate

The original FIG system had the block buffers in common for all users/task
and a separate area per user for the stacks, the user variables and the
console input buffer. This layout is kept in ciforth.

32 bits systems have enough space to duplicate those areas, whose total space
could be as large as the whole addressable memory space of classic 16-bits
systems.

@chapter Miscellaneous remarks

What you find in this chapter may be very old, and may or
may not be worthwhile.
@section My remarks
What follows are some examples from the time ciforth was born,
around 2000.

@subsection Booting from floppy or hard disk
The following examples all relate to concrete sources,
it may not make sense for the source file you've at hand.

If you use other than 3" floppy disks you have to specify the disk
parameters. Parameters for a 5" HD floppy are present and can be commented
in.
If you do not need a DOS-compatible floppy, you can put the image
immediately after the boot sector. A bootable hard disk version always works
like that.
You can change the default name of the forthcodeni({BLOCK-FILE}) at run time.
If you want to change the header layout, you will find that the way headers
are done via MACRO's make it more pleasant to use the generic listing.
If you may want you can use this as a starting point for generating a whole
other Forth (like me).
If you want to boot into your 20 Gbyte disk (like me), you probably have a
version 3.0 super modern LBA BIOS. There is no file system, just 20,000,000
blocks (and yes a 16 bit system would be inconvenient). If you want to use
an older system you must experiment by using the forthcodeni({BIOS}) word.
(You need not resort to assembler for experimenting.)
Then you can adapt your assembler listing.
@subsection More deviations from the FIG model

The name USER reflects that more than one user could use the dictionary
and users could share the background storage, provided certain precautions
are taken. In the twentieth century this is no longer attempted.

During a forthsamp({SAVE-SYSTEM}) user variables  are stored back
in the boot-up parameters as follows
forthsamp({USVA @@  ' USVA @@  +ORIGIN !})
where forthvar({USVA}) is the user variable which value you want to keep.
Otherwise saved images could be extremely large, because the user variables
are at the highest memory.

Underneath the I/O model has improved. forthsamp({TYPE}) and forthsamp({ACCEPT}) are
implemented using standard in and standard out, which is now
universal in hosted systems. forthsamp({TYPE}) instead of repeated forthsamp({KEY}) .

Key rub out is best left to the forthsamp({ACCEPT}) code, that relies on the
OS to handle corrections.
Remember, a Linux itself knows the
rubout key for any of its 500+ known terminal types and isn't it nice in
MSDOS that F3 gets the previous command back for you?
An forthsamp({ACCEPT}) that builds up a line from separate key strokes is still
available in the generic source.
If you ever need to change the rubout key,
just change the forthsamp({RUBOUT}) user variable.

@section FIG's remarks

@subsection Bringing up a 32 bit FIG system

[I leave this in despite it referring to FIG systems.
In ciforth these are the versions numbered 2.xx
In git they are old versions before 2000 dec 14.]
This versions can still be used to bring up a FIG-compatible system
for vintage lovers and it contains valuable techniques for
modern systems.
The following words are traditionally
the only portion that need change between different
installations of the same computer CPU.
They cannot come close to the capabilities
of the generic system,
and should be used for minor modifications only.

There are five words that need adaptation:

@table @code
forthitem KEY
Push the next ASCII value (7 bits) from the terminal keystroke to the
computation stack and execute NEXT. High 9 bits are zero. Do not echo
this character, especially a control character.
forthitem EMIT
Pop the computation stack (16 bit value). Display the low 7 bits on the
terminal device, then execute NEXT. Control characters have their
natural functions.
forthitem ?TERMINAL
For terminals with a break key, wait till released and push to the
computation stack 1 if it was found depressed; otherwise 0.
Execute NEXT. If no break key is available, sense any key depression as
a break (sense but don't wait for a key). If both the above are
unavailable, simply push 0 and execute NEXT.
forthitem CR
Execute a terminal carriage return and line feed. Execute NEXT.
forthitem R|W
This colon-definition is the standard linkage to your disc. It requests
the read or write of a disc block, be it raw disk or allocated in a file.
@end table

On primitive systems these may be jumps to ROM-code. But generally on i86
facilities like this are available using forthdefi({INT})'s a kind of traps.
These observe operating system protocols and are available as high level forth
code.

@subsection : a simple ram disk

The ciforth model may be used to bring up a Forth for a
SBC (single board computer).
The following notes coming from ancient scrolls of FIG still have
some value for that situation.
If disc is not available, a simulation of forthcode({BLOCK}) and
forthcode({BUFFER}) may be made in RAM.
The following definitions setup high memory as mass storage.
Referenced ``screens'' are then brought to the ``disc buffer'' area.
This is a good method
to test the start-up program even if disc may be available.

forthexample(
{HEX
4000 CONSTANT LO ( START OF BUFFER AREA )
6800 CONSTANT HI ( 10 SCREEN EQUIVALENT )
: R|W >R ( save boolean )
    B/BUF * LO + DUP
    HI > 6 ?ERROR ( range check )
    R> IF ( read ) SWAP ENDIF
    B/BUF CMOVE ; })

Insert the code field address of forthcode({R|W}) into forthcode({BLOCK}) and forthcode({BUFFER})
and proceed as if testing disc.
This forthcode({R|W}) simulates screens 0 thru 9, in the
memory area 04000H thru 067FFH.

@subsection Debugging an assembled system.

The ciforth model may be used to bring up a Forth under widely
differing situations.
The following notes coming from ancient scrolls of FIG contains
some valuable tips and tricks, widely but
not always applicable to e.g. hosted Forth's.

Let us assume we have an system based on an assembler listing
and we want to debug it.

Here are the sequential steps:
forthenumerate
forthitem
Familiarize yourself with the model written in Forth, the glossary, and
specific assembly listings.
forthitem
Edit the assembly listings into your system. Set the
boot-up parameter that initialises the forthcode({WARNING}) user variable to 0;
so warning messages are shown as simple numbers.
forthitem
Alter the terminal support code ( forthcode({KEY}) , forthcode({EMIT}) , etc,) to match your system.
Observe register protocol specific to your  implementation!
forthitem
Place a break in your debugger at the end of NEXT,
just before indirectly jumping via register W to execution.
forthsamp({W}) is the Forth name for the register
holding a code field address.
In ciforth this is the Intel 86 register AX.
If your NEXT is inline code,
for the moment replace it by a jump.
Mostly this can be done by inactivating the macro forthmacro({_NEXT_})
through removing the line containing it from
from forthfile( _BITS16_({width16.m4}) _BITS32_({width32.m4}) _BITS64_({width64.m4}) ).
forthitem
Enter the cold start at the origin.
Upon the break, check that the interpretive pointer HIP points within forthcodeni({ABORT})
and WOR points to forthcodeni({SP!}) .
But in the source the symbolic names is used.
forthcodeni({COLD}) being a colon-definition,
the HIP has been initialized on the way to NEXT and your testing will
begin in forthcodeni({COLD}) .
The purpose of forthcodeni({COLD}) is to initialize HIP, SPO, RPO, UP,
and some user variables from the start-up
parameters at the origin.
forthitem
Continue execution one word at a time.
Clever individuals could write a simple trace routine to print HIP, WOR, SPO, RPO
and the top of the stacks.
Run in this single step mode until the greeting message is printed.
Note that the interpretation is several hundred cycles to this stage!
forthitem
Execution errors may be localized by observing the above pointers when a
crash occurs.
forthitem
After the word forthcodeni({QUIT}) is executed (incrementally),
and you can input a "return" key and get ``OK'' printed, remove the break.
You may have some remaining errors, but a reset and examination of the
above registers will again localize problems.
forthitem
Get forthcodeni({H.}) running, directly, not based on forthcodeni*{.}) .
You may replace temporarily forthcodeni({.}) by forthcodeni({H.}) in forthcode({.S}).
Hunt down code words that don't work by using forthcode({.S}).
The forthfile({tsuite.frt}) may come in handy for this.
forthitem
Once the system is interpreting from the keyboard, execute forthcodeni({EMPTY-BUFFERS})
to clear the disc buffer area.
You must create now your disc driver, the word forthcodeni({R|W}) .
You may test the disc access by typing:
forthsamp({0 BLOCK 64 TYPE})
This should bring block zero from the disc to a buffer and
type the first 64 characters.
If forthcodeni({BLOCK}) (and forthcodeni({R|W}) ) doesn't function--happy hunting!
forthendenumerate
@section Linux application notes lina version
The lina version is based on a single assembler source,
and, once built, binary-portable across Linux Intel
(all systems were it has been tried work : 1.2.13 .. 2.4.20).
This is the by now a tried and proven configuration,
no run time c-libraries, no compile time c-libraries,
only the Forth source library.
forthexample({
    nasm -felf lina.asm
    ld lina.o -s -o lina
    strip lina
})
forthexample({
    fasm lina.fas -m256000
})
It is about 20k and the dictionary space is set at 64 Mbyte.

Like in all hosted configurations,
blocks are allocated in a file called forthfile({forth.lab})
This name can be changed in the source
and also during run time.
 forthfile({forth.lab}) can be changed into an editable file and back by
the forth programs forthfile({toblk.frt}) and forthfile({fromblk.frt}) .
With some care -- keeping  lines at the same length -- a programming editor
can do the job on its own.

The user variable forthsamp({EM}) still is the end of the memory.
The forthsamp({M4_EM}) in the configuration files is such that
it designates the relative size, from the relocatable start.
Consequently it is not the same as the user variable.
(The relocatable start is some 128 Mbyte into the memory space.).
@section Linux application notes ciforthc version
[ Forth with I/O defined in c are popular.
Note that the ciforthc configuration
has no binary, documented, tested releases.
It will probably even have to be debugged.
]

The Linux forth called ciforthc has its i/o based on c. This may seem more
portable but it isn't. Where c is very portable on Linux, the way assembler
is linked with forth is not documented (as far as I can tell. )
 forthcodeni({KEY?}) is implemented using a forthsamp({select}) system call.
The forthcodeni({EXPECT}) has not the " return if
maximum reached property", so it is not strictly conforming. This can be
done at the expense of handling each character separately. (Use forthcodeni({KEY}) to
implement forthcodeni({EXPECT}) as in the CLASSIC I/O model). This results in loosing
interruptability. Moreover Linux knows better what the forthcodeni({RUBOUT}) key should be,
although for your convenience it is already placed in a user variable and
can be easily changed.
The c-approach allows signals to be handled in a familiar way.
By using quit, a loop can be interrupted. So ^\ results in a warm start.
A segmentation fault also results in a warm start. ^C immediately leaves.
^S/^Q can be used to hold up output and are not interpreted as a break
in e.g. WORDS.

@section MULTI-USER

In the context if FIG and now in the context of ciforth
the name forthcodeni({USER}) reflects that more than one user could use the dictionary
and users could share the background storage,
provided certain precautions are taken.
These precautions are
forthenumerate
forthitem
Variables that can be different for different users,
must be defined as an offset to an area,
that is different for each user: the forthdefi({user area}) .
forthitem
Provisions that maintains the integrity of the dictionary.
Different scratch pads for each user.
forthitem
Different stacks, user area's and terminal input buffer's for each user.
forthitem
A means to switch applications.
forthendenumerate

Almost nothing from this is realized in the figforth model.
In fact only 1, and the pointer to the current user area is
in the bootup parameters.

forthcode({USER}) variable must be handled even if there is just one task,
because they must be initialised during start up.
Likewise they must be handled by forthcode({SAVE-SYSTEM}) such that
only the area from
 forthcode({BM}) to forthcode({HERE}) need be saved.

Because the initialized memory is saved the initial values
would be stored if they were ordinary variables. So the above
really is primarily relevant for systems that accommodate multitasking.

The user variables can be restored by typing forthcode({COLD}) .
This is hardly used anymore to restore an initial state because with
the fast mass storage you would rather type forthcode({BYE}) and
forthsamp({forth}) as a much safer way to restart your Forth.
forthcode({COLD}) performs a second execution of the startup options
that almost always give give problems
and it may leave an undefined situation w.r.t. wordlists.

dnl@node Glossary Index,,,top
@unnumbered Program Index
This index lists programs words.
@printindex pg
dnl@node Forth Word Index,,,top
@unnumbered Forth Word Index
This index lists forth words.
@printindex fn
dnl@node Concept Index,,,top
@unnumbered Concept Index
This index lists concepts.
dnl The first reference is where the concept is explained.
@printindex cp
@summarycontents
@contents
@bye