%
%  "Forth2LaTeX" version 1.0
%
%  LaTeX source,  RTK
%
%  Last Mod:  01-05-95
%
\documentstyle[11pt,fleqn]{article}
 \textheight=9in
 \textwidth=6in
 \hoffset=-0.5in
 \voffset=-0.8in
 \def\singlespacing{\parskip 5 pt plus 1 pt \baselineskip 13 pt
     \lineskip 7 pt \normallineskip 7 pt}
 \def\doublespacing{\parskip 5 pt plus 1 pt \baselineskip 25 pt
     \lineskip 13 pt \normallineskip 13 pt}
%
% new definitions
%
 \def\ftl{{\sc Forth}2\LaTeX\ }
 \def\forth{{\sc Forth}\ }
\begin{document}

\doublespacing
 
\pagestyle{plain}
\pagenumbering{roman}
 
%
% Title
%
\title{\ftl Manual}
 
\author{By\\
        \\
        Ronald Thomas Kneusel\\
        \\
        \\
        version 1.9
        }
 
\date{January 1995}
 
\maketitle
 
\pagestyle{plain}
\pagenumbering{roman}
%
\singlespacing
\tableofcontents
\clearpage
%
 
%
%\singlespacing
%\addcontentsline{toc}{chapter}{LIST OF TABLES}
%\listoftables
%\clearpage
%
 
%
%\addcontentsline{toc}{chapter}{LIST OF FIGURES}
%\listoffigures
%\clearpage
%
 
%
\doublespacing
%
% this is to set up for the main text, include only once.
%
\pagestyle{plain}
\pagenumbering{arabic}
\setcounter{page}{1}
%
\makeatletter
\def\@evenfoot{}
\def\@evenhead{\hfil\thepage\hfil}
\def\@oddhead{\@evenhead}
\def\@oddfoot{\@evenfoot}
\makeatother
%
%  start including the actual text...
%
\begin{center} {\huge Copyright} \end{center}
\hfil \break \hfil \break \singlespacing
This manual and the program it describes, along with all source files, is
\copyright 1994, by Ronald T. Kneusel.  All rights reserved.  Non-profit
distribution permitted as long as this manual is included and all 
copyright notices remain intact.  Please inform me of any changes you 
make to \ftl at the email address below.
\hfil \break \hfil \break
\leftline{{\bf Ronald T. Kneusel}}
\leftline{{\bf 8725 West Burdick Avenue}}
\leftline{{\bf Milwaukee, WI 53227 USA}}
\leftline{{\bf (414) 545-7557}}
\leftline{{\bf Internet: kneusel@studsys.mscs.mu.edu}}
\clearpage \doublespacing
\section{What is it?}

\ftl is a program designed to format \forth source code for \LaTeX.  It 
presently runs in Modula-2 and C on the Macintosh and in C on Unix, VMS, and 
MS-DOS.  This manual describes all versions noting differences where appropriate.
Source code for both the C and Modula-2 versions is included for those 
interested in modifying the program to suit their own needs.  \ftl intentionally
knows little of \forth.  It knows what a  $backslash$ comment is and the 
words {\tt :} (colon), {\tt VARIABLE}, {\tt CONSTANT}, {\tt CREATE},
{\tt FVARIABLE} and {\tt FCONSTANT}.  This does not tie it to a specific 
\forth system making \ftl useful to the widest possible audience.

\ftl features include:

\singlespacing
\begin{enumerate}
 \item Ability to {\bf bold} word names when defined.
 \item Creating an index of defined words and the line on which the
       word was defined.
 \item Printing useful program information.
 \item Complete \LaTeX\  access from within the source code in three 
       different ways.
 \item Different type styles for code and comments.
 \item Ability to create a table of contents and section the code in a 
 way similar to \LaTeX.
 \item Command files allow processing groups of files at a single time.
\end{enumerate}
\doublespacing

\ftl {\em does} impose one minor constraint on the programmer, namely, it 
only recognizes $\backslash$ comments and therefore will treat comments in
parentheses as code.  This is really a minor inconvenience as parentheses 
are usually reserved for stack effects comments.

\section{Getting Started - A Guide for the Impatient}

If your copious free time is insufficient to allow a complete reading of 
this little manual, this is a good place to start.  The guide is divided 
by computer: Macintosh or Everyone Else.

\subsection{Macintosh}

Double-click the \ftl application to get it going.  All parameters can be 
set via the {\bf Settings} menu.  Just choose the setting and it toggles 
between on or off.  Switching between {\bf report} and {\bf article} for 
the style will use the respective \LaTeX\  document style.  Typically, 
longer programs make sense as reports while shorter programs are 
articles.  Chapter sectioning may only be used (or rather is ignored 
unless) the style is set to {\bf report}.  Leave the {\bf Comments} as
{\bf FORTH} unless you have included \LaTeX\  code in the comments.

Choose {\bf Open...} from the {\bf File} menu and select a \forth source 
code file.  If the filename ends in {\tt .4th}, {\tt .fth}, or
{\tt .forth} the extension will be stripped.  Select an output filename 
using either the one suggested or your own with {\tt .tex} appended.  
\ftl will process the file and tell you how many lines it processed when finished.

\subsection{Everyone Else}

Enter {\tt Forth2LaTeX} on the command line to see a quick help screen listing 
the format and switches.  Most a self-explanatory in nature, the rest are 
described below.

\section{Controlling \ftl}

There are two ways of controlling the operation of \ftl: via menu or 
command line switches, or via \forth comments within the source code.  
The latter will always override the former.  Needless to say, only the 
Macintosh version uses menus, the rest use command line switches.

\subsection{Source Code}

All versions of \ftl can be controlled by comment statements within the 
\forth source code.  It is important to note that spacing and 
capitalization {\em are} important.

\subsubsection{Settings}

\ftl settings and information about the program are entered in the 
following form:

\singlespacing
\begin{verbatim}
   \ Program: <program name>   -- name of the program
   \ Author: <author name>     -- name of the author, appears in the title
   \ Started: <date>           -- date program begun
   \ Modified: <date>          -- date of last modification
   \ Modify By: <name>         -- person doing the modification
   \ Summary: <single line>    -- a one line summary of the program
   
   \ Comments: FORTH           -- comments are as normal
   \ Comments: LATEX           -- comments are treated as LaTeX code
   
   \ Uppercase: ON or OFF      -- force all but strings and comments to
                                  uppercase
                                  
   \ Table of Contents: ON | OFF  -- make a table of contents, use with
                                     sectioning
   
   \ Index: ON | OFF           -- output an alphabetical index of defined words
   
   \ Bold: ON | OFF            -- bold colon definitions
   
   \ Style: REPORT             -- use \documentstyle{report}
   \ Style: ARTICLE            -- use \documentstyle{article}
\end{verbatim}
\doublespacing

Certain characters have a special meaning to \LaTeX\ and need to be escaped
by prefixing with a $\backslash$ when using normally. \ftl does this 
automatically for code, 
including the spaces to force \LaTeX to preserve the indentations, but 
can be told to stop this for comments.  The default setting is {\tt 
FORTH} which escapes the text in comments as elsewhere.  Changing 
{\tt Comments} to {\tt LATEX} allows the programmer to include \LaTeX\  
code in the comments, but also makes the programmer responsible for 
using appropriate escape sequences when necessary.
Note that the settings above can appear anywhere within the source code, 
but must appear in the first file to be processed when using multiple files.

\subsubsection{Sectioning}

\ftl recognizes the standard \LaTeX\  sectioning commands, though it ignores
chapters unless in {\tt REPORT} style.  Sectioning provides a convenience 
way to organize the source code and to create a table of contents that 
outlines the program structure.  To use sectioning, include statements 
giving the name of the section prefixed by the type of section:

\singlespacing
\begin{verbatim}
   \ Chapter: <chapter-name>   -- start a chapter (LaTeX \chapter)
   
   \ Section:                  -- sections and subsections
   \ Subsection:
   \ Subsubsection:
\end{verbatim}
\doublespacing

\subsubsection{Other Ways of Including \LaTeX\  Code}

The {\tt Comments:} setting described above is only one of three ways to  
include \LaTeX\  code in the \forth source code.  The others are to use a 
special \LaTeX\  escape character or to use a $\backslash$\verb+ .+ to 
prefix a line that will be passed as is into the output file.  The former 
is most useful for inserting a small piece of code:

\verb+\  `$c_{m}$` is set here+ appears as $\backslash c_{m}$ is set here

The escape character is \verb+`+ (backquote).  Everything between backquotes is 
immune to special character escaping and can include valid \LaTeX\  statements.

To include an entire line, useful for entering normal text, prefix the 
line with a $\backslash$\verb+ .+ where every character after the period 
is sent as is into the output file without escaping or forcing into a 
single line:

\singlespacing
\begin{verbatim}
\ .This will appear in the output as if it were entered into a normal
\ .\LaTeX document.  This could be used to insert large blocks of text
\ .describing the code, or to even include graphics.
\end{verbatim}
\doublespacing

\subsection{Command Line Switches and Menu Settings}

It is possible change \ftl settings without specifically stating the 
settings in the source code.  The Macintosh uses a menu called 
(surprisingly) {\bf Settings} to adjust \ftl values prior to processing a 
file.  Each of the menu items has a direct counter part in the source 
code settings given above.

Other computers use command line switches to alter the functioning of \ftl.
The general format is: {\tt Forth2LaTeX\ \ source-file\ \ switches} 
where the {\tt switches} consists of a string of characters (case is 
irrelevant) prefixed with a {\tt -} (dash).  The options are listed below:

\singlespacing
\begin{verbatim}
	u  -- uppercase code (does not alter comments)
	l  -- comments LATEX (default is FORTH)
	t  -- generate table of contents
	i  -- index of defined words
	b  -- bold colon definition names
	r  -- style is REPORT (default is ARTICLE)
\end{verbatim}
\doublespacing

\subsection{Multiple Files}

If \ftl is presented a file with a {\tt .f2l} extension it will 
assume it to be a command file that contains the names of a series of files 
to be processed.  Comments, preceeded by a \# character, may be added to 
the file.  A sample command file could be:

\singlespacing
\begin{verbatim}
# The following specifies the output file name, default is 'a.tex'

# Output: Alexis.tex

# These are the files to be processed, in order:

     Setup.4th         # mainly memory management, constants, etc.
     Arith.4th         # big integer and rational arithmetic and utilities
     Poly.4th          # univariate polynomial routines and utilities
     Command.4th       # Yerk code and command processor
     Intrinsic.4th     # Built-in commands

# That's all folks!
\end{verbatim}
\doublespacing

The third line above is used to specify the output file name, which 
defaults to {\tt a.tex}.  Unless complete path names are given in the 
command file \ftl assumes that the files can be found in the current 
directory.  Use a command file when working on a larger project with 
multiple files.

\section{Conclusion}

It is sincerely hoped that \ftl will be of use to you.  It was originally 
designed to spice up the output for a project (the command file for the 
project is the example above) and has evolved into a bit of a project 
itself.  It is also hoped that users will feel free to alter the source 
code for any of the versions, provided that the author is sent a copy if 
the modified version is to be released publicly.

Suggestions and bug reports (Bugs? What are those?) are to be sent to the 
email address given at the beginning of this document.  The author assumes no 
responsibility of any kind for any loss of data or time that may be 
caused by the use of this program.  While it is unlikely that something 
will happen, if it does, I'm not to blame.

\end{document}