%% This document created by Scientific Word (R) Version 2.0
%% Starting shell: article


\documentstyle[code,keywords]{article}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%TCIDATA{OutputFilter=Latex.dll}
%TCIDATA{Created=Thu Sep 04 17:31:55 1997}
%TCIDATA{LastRevised=Wed Aug 05 12:26:31 1998}
%TCIDATA{<META NAME="GraphicsSave" CONTENT="32">}
%TCIDATA{Language=American English}
%TCIDATA{CSTFile=LaTeX article.cst}

\input tcilatex

\begin{document}

\author{Theo Norvell \\
%EndAName
Faculty of Engineering\\
Memorial University of Newfoundland}
\title{Typesetting Algorithms in Scientific Word}
\date{1996 October 30, revised for SW 3.0 1998 August 5}
\maketitle

\section{Compiling this file}

This file uses two style files of my own. These are included in verbatim
environments in the appendix. They must be copied out of this file and into
files called keywords.sty and code.sty in a directory in which the \LaTeX{}
compiler will look for input files.

\section{The problem}

Typesetting programs and algorithms is a common problem for me. As I use
Scientific Workplace 3.0 to do my typesetting, I\ have had to find nice ways
to typeset programs and algorithms with this product.

Typesetting algorithms and programs in \LaTeX{} is normally done using
either the tabbing or the verbatim environments. The tabbing environment is
not supported as yet by Scientific Workplace and the verbatim environment is
not very flexible. This raises the question of whether there is a good
method to typeset algorithms and programs using Scientific Workplace. A good
method should have the following properties:

\begin{enumerate}
\item  The typeset results should look great.

\item  Entry should not be difficult.

\item  The on-screen appearance should be easy to read.

\item  Programs and algorithms should be easy to edit.

\item  It should be easy to mix math and text in algorithms.

\item  It should be possible for page breaks to appear in programs.
\end{enumerate}

At this point I am reasonably satisfied with the set of tricks that I\ use
and thought it might be nice to share them with other users of Scientific
Workplace.

\section{My solutions.}

\subsection{Indenting}

The main problem is in indenting code. Tabbing is not supported by
Scientific Word, so I use \LaTeX{}'s {\tt description} environment instead.
To get produce \LaTeX's{} {\tt description} environment with Scientific
Word, you use `Description List Items', like this:

\code 

void split(\ Node *list, Node *\&new0, Node *\&new1) \{

\begin{description}
\item  if(\ list == 0 )\ \{new0 = 0 ; new1 = 0 ; \}

\item  else \{

\begin{description}
\item  new0 = list ;

\item  split( list-\TEXTsymbol{>}\ next, new1, new0-\TEXTsymbol{>}next) ; \}
\end{description}
\end{description}

\}

\endcode 

In order to use the `Description List Items' tag without the mouse, I used
the {\sf Function Keys} command on the {\sf Tag} menu to globally assign
CNTL-F7 to Description List Item.

Most screen styles (i.e. .cst files) that come with SW 3.0 do not properly
indent Description List Items. If you are viewing this document in the SW\
editor and the above code does not look indented, do as follows. Select from 
{\sf Appearance} from the {\sf Tag} menu. Select {\sf Description List Item}
from the {\sf Properties list}; select {\sf Paragraph} from the {\sf %
Properties} list; and click on {\sf Modify}. Now, under {\sf Indentation}
set {\sf All} to about 0.63cm, {\sf First} to 0.0cm and {\sf Rest} to 0.0cm.
Now save your changes. I\ also set the background colour of the lead-in to 
{\sf White}, so that it is not visible. These changes affect only how code
looks in the editor and when printed without typesetting.

The {\tt description} environment spaces things rather poorly. So I enclose
the whole program fragment with \TeX- fields containing `{\tt \TEXTsymbol{%
\backslash}code}' and `{\tt \TEXTsymbol{\backslash}endcode}' commands
respectively. The `{\tt \TEXTsymbol{\backslash}code}' command alters the 
{\tt description} environment so that the spacing is more even. It also
changes the font to {\sf sans-serif} and places horizontal lines above and
below the code to set it off from the text{\sf .} The `\TEXTsymbol{\backslash%
}{\tt endcode}' command undoes the effect of the `{\tt \TEXTsymbol{\backslash%
}code}' field. Entering the two \TeX{}-fields is facilitated by putting them
both within a `fragment' file.

The definitions of the {\tt \TEXTsymbol{\backslash}code} and {\tt 
\TEXTsymbol{\backslash}endcode} commands are located within a style file. I
use {\sf Typeset/Options and Packages/Modify/Go Native }to add this file
(called code.sty)\ to the list of style options.

There are a few limitations to this method:\ One is limited to 5 levels of
indentation. Indentation is regular --- one cannot, for example, typeset
LISP\ programs in the conventional way where the level of indentation may
depend on the text of the preceding line.

When using the {\tt typewriter} font, as I sometimes do for programs, one
must take care in typesetting the double-quote character. SW's output filter
converts the {\tt 
%TCIMACRO{
%\TeXButton{"}{{\char34}%
%}}%
%BeginExpansion
{\char34}%
%
%EndExpansion
} character to two apostrophes. I\ use a fragment containing a \TeX{}-field
that contains the magic \TeX{} code of {\tt \TEXTsymbol{\backslash}char34}.

\subsection{Mixing math and programs}

For expressing algorithms in a more abstract form than afforded by
programming languages limited to the ASCII character set, it is nice to be
able to use math mode. To do this, one simply has to change to math mode at
the start of each line.

Here is an example.

\noindent \framed\code 

$%
%TCIMACRO{
%\TeXButton{while}{\bwhile%
%}}%
%BeginExpansion
\bwhile%
%
%EndExpansion
W\neq \emptyset 
%TCIMACRO{
%\TeXButton{do}{\bdo%
%}}%
%BeginExpansion
\bdo%
%
%EndExpansion
$

\begin{description}
\item  {\em choose }$(i,j)\in W${\em \ to maximize }$A(i,j)$

\item  $W:=W-\{(i,j)\}$

\item  $F:=F\cup \{(i,j)\}$

\item  $%
%TCIMACRO{
%\TeXButton{for}{\bfor%
%}}%
%BeginExpansion
\bfor%
%
%EndExpansion
k$ {\em such that }$(j,k)\in F\wedge (i,k)\notin F%
%TCIMACRO{
%\TeXButton{do}{\bdo%
%}}%
%BeginExpansion
\bdo%
%
%EndExpansion
$

\begin{description}
\item  $A(i,j):=A(i,k)\oplus A(i,j)\otimes A(j,k)$

\item  $W:=W\cup \{(i,k)\}$
\end{description}

\item  $%
%TCIMACRO{
%\TeXButton{for}{\bfor%
%}}%
%BeginExpansion
\bfor%
%
%EndExpansion
k$ {\em such that }$(k,i)\in F\wedge (k,j)\notin F%
%TCIMACRO{
%\TeXButton{do}{\bdo%
%}}%
%BeginExpansion
\bdo%
%
%EndExpansion
$

\begin{description}
\item  $A(k,j):=A(k,j)\oplus A(k,i)\otimes A(i,j)$

\item  $W:=W\cup \{(k,j)\}$
\end{description}
\end{description}

\endcode\endframed

Keywords such as {\bf while}, {\bf for}, {\bf do}, {\bf if}, {\bf then}, 
{\bf else}, etc. are simply typed in. Using the Automatic Substitution
mechanism of SW, they are converted to encapsulated \TeX{}{}-fields. For
example, the $%
%TCIMACRO{
%\TeXButton{while}{\bwhile%
%}}%
%BeginExpansion
\bwhile%
%
%EndExpansion
$ \TeX{}-field contains {\tt \TEXTsymbol{\backslash}bwhile.} The commands in
these \TeX{}{}-fields are defined in another style file called keywords.sty.%
\footnote{%
This is more complex than necessary. You could dispense with the style file
by simply encapsulating the appropriate \LaTeX{} code, rather than invoking
a user defined macro. E.g. instead of putting {\tt \TEXTsymbol{\backslash}%
bwhile} in the \TeX{} field, you would put {\tt \TEXTsymbol{\backslash}%
mathop\{\TEXTsymbol{\backslash}bf while\}}.} I also rely heavily on
automatic substitutions for the operators I use the most.

Multicharacter identifiers pose a bit of a problem. \TeX{}{}'s default math
font for letters (math italic) is not suitable for typesetting these.
(Compare $foobar$ with {\em foobar}.) One must be careful to enter them in
the standard italic font or go back and convert them to italic font. It is
also possible to convince \TeX{}{} to use another font for math letters
throughout the document.

I\ framed this algorithm using a framing environment defined in code.sty.

\subsection{Conclusion}

How does this stack up against the criteria?

\begin{enumerate}
\item  The typeset results look good.

\item  The use of function keys, fragments and automatic substitutions makes
entry easy. One does not need to remember which characters of the
programming language need to be escaped --- a problem when using raw \LaTeX%
{}. Entry would be easier if fragments could span paragraphs. It would also
be easier, if the mode (math/text) did not revert on beginning a new
paragraph.

\item  The on-screen appearance looks quite similar to the printed output.

\item  Editing is as easy as editing anything else in SW. It is easy to
change the indentation level of each line, to combine adjacent lines, or
split long lines.

\item  Mixing math and text is quite easy owing to SW's math editing
facilities. Using automatic substitutions makes it easy to insert common
pieces of text (such a keywords and types) by only typing in letters.
Multicharacter identifiers are still a bit of a problem. It would be nice to
locally switch the math font to ordinary italic for the duration of a code
section --- I do not know how to do this.

\item  Page breaks can appear in programs. One can also surround code
sections with environments (such as the {\tt framed} environment used in
this file)\ that force all lines to be on the same page.
\end{enumerate}

\section{Where next?}

I\ am currently working on ways to use SW\ as an environment for `literate
programming'. Literate programming is the idea, proposed by Donald Knuth,
that programs and their documentation should be prepared together as a
nicely typeset whole. My literate programming system uses its own .cst file
which includes a {\sf Code} item tag, which takes the place of the `code'
and `endcode' \TeX-fields. This tag is assigned a function key so that
entering {\tt code} environments is even easier. Using the tag also means
that code is shown in the editor in the same font as when typeset.

\appendix 

\section{Style files}

Create these files prior to compiling this file.

\subsection{code.sty.}
\begin{verbatim}
\makeatletter
\newlength{\frameWidth}
\newlength{\frameTopExtra}
\newlength{\frameBottomExtra}
\newsavebox{\chuck}
\newenvironment{framed}
{\setlength{\frameWidth}{\linewidth}%
 \addtolength{\frameWidth}{-2\fboxsep}%
 \addtolength{\frameWidth}{-2\fboxrule}%
 \setlength{\frameTopExtra}{1.0ex}%
 \setlength{\frameBottomExtra}{0ex}%
 \setlength{\frameTopExtra}{\baselinestretch \frameTopExtra}%
 \global\setbox\chuck\vbox\bgroup\hsize\frameWidth \@parboxrestore}%
{\par\vskip\z@\egroup\shortstack{{}\\[\frameTopExtra]\fbox{\usebox\chuck}%
\\[\frameBottomExtra]{}}}
 
\def\code{%
\bgroup%
\parsep 0pt%
\parskip 0pt%
\itemsep 0pt%
\topsep 0pt%
\parindent 0pt%
\def\descriptionlabel##1{\hspace\labelsep \bf ##1}%
\def\description{\list{}{\parsep 0pt \parskip 0pt \itemsep 0pt \topsep 0pt%
       \parindent 0pt \labelwidth\z@ \itemindent\z@ \leftmargin 2em%
       \let\makelabel\descriptionlabel}}%
\let\enddescription\endlist%
        \par\noindent\hrulefill\par\sf}%
\def\endcode{\par\noindent\hrulefill\par\egroup}
 
\makeatother
\end{verbatim}

\subsection{keywords.sty.}

{\ }
\begin{verbatim}
\newcommand{\bif}{\mathop{{\bf if}}}
\newcommand{\bthen}{\mathop{{\bf then}}}
\newcommand{\belse}{\mathop{{\bf else}}}
\newcommand{\bwhile}{\mathop{{\bf while}}}
\newcommand{\bfor}{\mathop{{\bf for}}}
\newcommand{\bdo}{\mathop{{\bf do}}}
\newcommand{\iskip}{\mathord{{\it skip}}}
 
\newcommand{\itick}{\mathord{{\it tick}}}
 
\newcommand{\bbool}{\mathord{{\sf bool}}}
 
 
\end{verbatim}

\end{document}