Read Me

This directory structure contains the source code for the current forth200x basis document.

Requirements

I assume you have a standard latex2e system installed. This includes the use of the latex, pdflatex, and dvips programs. I also assume a Forth interpreter is installed.

The document uses a number of standard latex packages. These are part of the standard latex2e installation. If your system does not have any of these packages they can be obtained from your local CTAN mirror (www.ctan.org/).

• graphicx - Enhanced Graphics
• fancyhdr - Fancy headings
• changebar - Change Bars
• ulem - Underline and struck thorough text
• hyperref - Hypertext links
• mathptmx - New-Times-Roman for roman and formula (PS-NFSS)
• helvet - Helvetica for sans-serif (PS-NFSS)
• courier - courier
• parskip - Non-zero parskip adjustments
• xcolor - Named colours

In addition to these packages I also make use of the following optional packages:

• answers - Deferred text, this is provided as a .sty, but the full package is provided in the Support directory. It is also available on CTAN.
• history - Change Log, I have been developing this package alongside the document. The version included here is the full code as it currently exists.
• randtext - Randomise text, used to typeset email address in a manner that automatic harvester program find impossible to process.
• environ - Editors Comments Box.

Building the Document

I have include both a makefile for use with *nix systems and a make.bat for use with dos/windows systems. Simply change into the directory/folder and type make.

There are a number of make targets available:

• dvi This will build a "forth.dvi" file. This is used to produce the PostScript version of the document.

• ps The PostScript version of the document the document. It uses both latex and dvips to do this.

• pdf This will produce a file "forth.pdf", a PDF version of the document, complete with internal hyper links. pdflatex is used to produce this.
  

• clean Will clean up all the temporary files which get left behind.

The latex process

The main "driver" file is "forth.tex". This will include all the other files as it needs them. In order to build the final document you need to run it though latex several times.

1. Extract auxiliary file

   The first time it runs, it will generate a lot of auxiliary files, these contain information needed for the cross referencing system. It will also generate a set of "labels" and you will see a large number of warnings of the form:

   LaTeX Warning: Reference `search:ONLY' on page 274 undefined
   on input line 398.
   

   and

   LaTeX Warning: Can't find definition of "TIB" in wordlist
   "core", reference on page 2 on input line 128.
   

   These are produced because the labels have not been defined yet, they are being defined by this run.

2. Sort the Index

   When latex is run on forth.tex it produces a "forth.wrd" file. This is the list of words defined in the document given in the order they have been defined. In order to get the alphabetical word list used as the index we have to sort this list. This is done with the aid of a small forth program which produces a "forth.wds" file.

   As this file uses labels to locate the page of a word definition, we do not need to wait for the page numbers to settle down.

3. Correct Labels

   As there are no labels on the first run, place holders are used. These will not be the same size as the text of the actual label. Thus having defined the labels, we have to run the file though latex once again to get the labels correct. As these labels will be of a different size to the place holders, we have to run latex a third time to resolve all the page numbers correctly.

4. Change Bars

   Now that the text has settled down we can work out where to place the change bars. This uses a similar technique to the labels, in that it collects the information it requires on one run, and then uses that information on a second run. Unfortunately, we have just changed the information on the last run, so we have to run the whole thing through latex two more times.

Configuration

There are four configuration options which can be found in the "config.tex" file.

1. Word References (\showref)

   All words are given a label so they can be referenced, this label normally has the same name as the word. Unfortunately this is not always possible. As the label is used as the target for a hyperlink it can not contain characters which have special meaning in the target format (PS/PDF or HTML). These labels are not normally shown. The \showreftrue flag is provided to show these label in the word header block and in the index. To enable this feature you must comment out the \showreffalse' command and uncomment the \showreftrue` line.

2. Informative text Location (\inline)

   The informative text (rationale, implementation and testing appendix entries) for a word is given with the word definition. The \inline flag, controls how these sections are presented:

   • \inlinetrue The informative text is given alongside the main definition. This is known as the review (r) version of the document.

   • \inlinefalse The informative text is shipped out to an external file. The file is read back in when the appropriate appendix is processed.

3. Draft or Release (\release)

   The document is typeset differently if it is a draft (\releasefalse) complete with change markup and additional draft only text, or if it is a snapshot (\releasetrue) document.

Macros

As you would expect a number of LaTeX macros are defined to make the whole thing easier to handle.

Change Markup

The change markup is provided via the "history" package. All changes require a label, the label is normally the name of the proposal associated with the change. All markup is identified with a change bar in the margin. The is limited to a single paragraph and must not span a paragraph break.

• \place{<label>}{<text>} Place new <text> in the document. The text will appear underlined.

• \replace{<label>}{<old>}{<new>} Replace the <old> text with the <new> text. The <old> text will appear struck though, while the <new> text will appear underlined.

• \remove{<label>}{<text>} Remove the <text> from the document. The <text> will appear struck though.

Word lists

When a word is defined a label is automatically defined for cross reference. These labels are separated into wordlists. A few commands have been defined to manage the LaTeX wordlists.

• \wordlist{<wordlist>} Starts the definition of a new <wordlist>. This command sets up the chapter heading and support files required for the word definitions.

• \setwordlist{<wordlist>} Sets the current wordlist search order to <wordlist>.

• \extended Switches the word list label on the definition header to add the "EXT" or extended word set.

Word Definition

To define a new word the worddef environment is used:

\begin{worddef}[<label>]{<number>}[<sub-number>]{<name>}[<english>]

• <label> Is the LaTeX label given to the word. It is used when processing links, and should not include any PDF or HTML Special characters. This is the label by which the word in known to the LaTeX system, and the name which should be used in the \word{} and \wref{} commands.

  Default: <name> is assumed to be the label.

• <number> The word's number in the alphabetical listing of words. This should be the full four digit number. If it is empty a long dash is used.

• <sub-number> The document requires we add new words between existing words. I.e., a new word between 0124 and 0125, we can only archive this by further dividing the number with a two digit sub-number.

  Default: No subdivision.

• <name> This is the display name of the word. It is typeset in standard LaTeX. Note the use of additional macros for special characters (see below).

• <english> Is the English pronunciation of the word.

  Default: None.

• <proposal> The name of the proposal which introduced this word. All words introduced by Forth 200x should have a proposal. When a new word is defined an argument MUST also be defined. This may be empty.

  Default: None.

The worddef* environment adds change bars to the output. This is used to introduce a new word into the standard for the first time.

The following commands are provided to aid the word definition:

• \stack[<stack>]{<before>}{<after>} Type set a stack picture according to the rules below.

• \param{<item>} Type set the stack according to the following rule:

  • _x or _{xx} - x or xx is a subscript.
  • x*y - x multiplied by y
  • x|y - x or y
  • < xxx > - the argument <xxx>
  • " - the open or close double quote
  • All other characters are typeset in italic.

The worddef environment MUST begin with one of the following section headings:

• \item - No section heading
• \compile - Compilation time semantics
• \execute[<type>] - Execution semantics, with a given <type>
• \init - Initiation
• \interpret - Interpretation semantics
• \note[<number>] - Note with an optional <number>
• \runtime[<type>] - Run-time semantics, with a given <type>
• \see - Reference to other words (See)
• \item[<name>] - None standard section <name>:

Word Rationale

The rationale environment should be used to identify text which is to be included in the rationale for a definition. Only one rationale section is allowed for each definition.

\begin{rationale}
	...
\end{rationale}

The \inline flag controls how the text is processed:

• \inlinefalse The text is exported to an external support file (r-<wordlist>.sub). The text is subsequently included into the rationale, appendix A.

• \inlinetrue All text typeset in a sans-serif font, but the text will appear as part of the word definition. This is used in the review version of the document.

Reference Implementation

\begin{implement}
	...
\end{implement}

The implement environment should be used to identify a reference implementation for a definition. It works in the same manner as the rationale environment, producing an i-<wordlist>.sub support file which is read in by the Reference Implementation appendix. The teletype font is used for the text in this environment.

• \textdf{<text>} Typeset the in the default font, sans-serif in the review document and times-new-roman in the final version. may not span more than a single paragraph.
• \dffamily Switch to the default font for the rest of the environment.

Testing

\begin{testing}
	...
\end{testing}

The testing environment should be used to identify text which is to be included in the test cases for a definition. It works in the same manner as the rationale environment, producing a t-<wordlist>.sub support file which is read in by the Testing appendix.

A macros has been defined to present a test case:

​ \test[<format>]{<pre>}{<post>}

Will generate a test case where <pre> is the code under test, <post> is the expected result, and <format> is the format of the result. This will produce the following output:

T{ <pre> -> <post> <format>}T

The text is typeset in the teletype font and spaces are not ignored. Additional spaces in the input will appear in the output. This allow for formatting of a group of test cases.

Special Characters

• \tab[n] Insert additional horizontal space. n is a multiplier so \tab[2] will insert twice as much space as a single \tab.

• \arg{<text>} <text> is typeset in italic between < and > signs.

• \bs Outputs the \ (backslash) character.

• \tilde Outputs the ~ (tilde) character.

• \num Outputs the # (number) character.

• \brace Outputs the { (open brace) character.

Cross Referencing

There are a number of commands which extend the standard cross reference mechanism. These commands take account of the word list and the hyperlinking.

The label are automatically defined for us by the worddef, rationale, implement and 'testing' environments. Normally the word label will be <wordlist>:<name> however, when <name> contains a character which may confuse PDF, PS or HTML the word has to be given a special label in which case this label is used <wordlist>:<label>.

• \word[<wordlist>]{<label>} - word definition. Reference the word associated with <label>. The word is either in the current wordlist (see \wordlist or \setwordlist), the core wordlist or the optional . The word is shown in courier-bold and hyperlinked to its definition.

  If the \showref flag is true (\showreftrue) the word is underlined.

  If the word has not been defined, or can not be found, a warning is reported and the <label> is typeset struck through with a line. ​

• \xref[<text>]{<label>} - Extended cross reference. This was originally developed as a tool to help in the conversion of existing documents into LaTeX form. It will look up <label> and places the section number followed by the section name as a hyperlink to the section. ​ Should <label> not be found it places <label> (between brackets) with the optional <text> along side. The idea being that we can see what was in the original document (<text>), and which <label> was not found. If the <text> is not given, the traditional double question mark is used. ​ Thus for the following example, let the label "foo" refer to section 3.2.1 which has the title "Extended Xref", the cross reference:

  \xref[original text]{foo}

  would produce:

  3.2.1 Extended Xref
  

  which is hyperlink to section 3.2.1. ​ If the label foo is not defined, it would produce:

    [foo: original text]
  

  where the "[foo: original text]" appears in bold. This is intended to indicate that the label foo was not found, but the original document had "original text" as the text which should appear here. ​

• \wref{<label>}{<Name>} - Word reference. Cross reference to a words definition.

  • <label> - will be of the form <wordlist>:<label>.

  • <name> - is the LaTeX which will be typeset for the word reference. Both the word number and name are type set and a hyperlink is provided to the word's definition. ​

• \rref{<label>}{<name>} - Rationale reference. \rref is the same as \wref except it looks in the rationale (rat:) name space. ​

• \iref{<label>}{<name>} - Implementation reference. \iref is the same as \wref except it looks in the reference implementation (imp:) name space. ​

• \tref{<label>}{<name>} - Testing reference. \tref is the same as \wref except it looks in the testing (test:) name space.

Utilities

I have been developing the document on a Windows 10 system using the following utilities:

• MiKTeX - 2.9
• TeXWorks - 0.6.1
• Notepad++ - 7.3.3
• SwiftForth - 3.6.3
• Dia - 0.97.2