Producing Technical Documents


Introduction

This is based on a short series of articles I wrote for Archive reviewing some of the software available to produce scientific documents. It came out of attempts I made in 1996/7 to solve some problems in doing just that, and I present my experiences here in the hope that they will be of interest to others in the same situation. I am trying to deal with some specific needs that aren't served on Acorn machines by the same amount of software as exists for scientists using PCs (although as I hope I'll show when I get to TechWriter, there is an excellent solution available to us).

The Need

Since I started using a computer to write with, one of the constant sources of irritation has been how to produce equations in documents. Simple ones like:

have never been a problem, as you just use an italic font, and add a few spaces to make it look right. Even things like:

can be dealt with by using superscripts. The really tricky problem comes when something more complicated is needed, for example:

equation

equation

equation

Now that is something of a challenge with most word processors! I've always tended to deal with these by the rather tedious method of creating frames in Ovation and using Beebug's SymbolB or Acorn's Sydney fonts combined with Draw, however this can be extremely awkward, and I've recently been looking around for better ways of achieving the same result.

The Solutions

There are many ways of doing this, some cost more money, while others cost more in time to learn. The ones that occur to me are:

The first two will cost you nothing apart from telephone time to download, or whatever a PD library will charge to supply them. Formulix and Formulate are both add-on equation editors that allow you to create complex lines of mathematical or scientific expressions, which can then be embedded in a document. I'll look at each one in turn, and then deal with the latest versions of TechWriter and its Professional cousin, which provide the most expensive, but by far the best, most elegant, and most realistic method for serious equation users.


This is an Acorn port of a multi-platform scientific word processor. It is available free from at least two FTP sites: Hensa, and from Robin Watts (who is responsible for turning it into a useable application most folk have a chance of installing). It can also be obtained on the Datafile's PDCD-3. A full installation takes up around 8-10Mb of disc space, including some 4Mb of its own fonts (any standard outline fonts you have cannot be used), so getting it on CD can be a great help. The following quote from the ReadMe file will perhaps give you an idea of what is like:

" is a professional typesetting program used especially for typesetting technical or mathematical material. Using plain is a bit like trying to mow Wembley Stadium with nail clippers, so Leslie Lamport produced a set of macros for , called La, that drastically reduce the work required to produce high quality documents.
was designed by Knuth for him to write his (still unfinished) epic "The Art of Computer Programming" with, and has since been adopted by (among others) the American Mathematical Society. Many technical publications now only accept submissions in or La format.
Many books on and La are available - among the best are "The book" and "The LaTeX book" by Knuth and Lamport respectively.
If you still don't have a clue what I am going on about then don't worry - is probably not for you."

I know a lot of folk (mainly graduate scientists) who use and are very competent at working with it, however it is not simple to use, and takes a while to learn. If you search around on WWW sites, you can find some documentation to help in that process. To use it, you type your text into Edit, or whatever text editor you prefer, along with an assortment of formatting and character commands as well as pointers to illustrations you want to include. A couple of extra files provide a mode for StrongEd to simplify some of this, and Zap has some built-in facilities to help as well. After saving it as a (filetype &2A7) or La (filetype &2A8) file it can be double-clicked to translate it into a DVI (DeVice Independent) file. That file can't be viewed directly, but has to be double-clicked to load it into DVIview, which allows you to check to make sure you've typed in the right commands. For example, the passage below is taken from "A Gentle Introduction to ":

\section{No math anxiety here!} 

\TeX{} is at its best when typesetting mathematics.  The 
conventions for doing this are many and complex, and the ability 
of \TeX{} to take them into account makes the production of high 
quality, attractive mathematical output possible.  If you plan to 
produce papers with mathematical symbols in them, this section 
will give you all the basics necessary for creating beautiful 
output in almost all circumstances; \TeX{} may be used without 
any mathematics, of course, and if this is your goal, then the 
following two subsections are probably sufficient for your needs. 
 
\subsection{Lots of new symbols} 
 
Mathematical text is inserted into normal text in two possible 
ways: it can be {\sl in-line\/}, that is, as part of the usual 
lines of text.  It can also be {\sl displayed}, that is, \centred{} 
in a gap between the usual text.  The results in the spacing and 
placement of symbols can be quite different in each case.  The 
in-line equation $\sum_{k=1}^{\infty} {1\over k^2} = {\pi^2\over6}$ 
is easily seen to be different from the same equation when 
displayed: 
$$\sum_{k=1}^{\infty} {1\over k^2} = {\pi^2\over6}.$$ 

and turns into:

In some ways, it is reminiscent of the sorts of control codes that Wordwise and View used to control the effects that specific printers produced, except that you can produce much more than just text effects and a few non-alphanumeric characters.

The greatest advantage of is that you can interchange files with users on a wide variety of platforms: I've successfully taken files from PCs and UNIX systems, and read them on my Risc PC. Pages can be printed from DVIview, or saved as Draw files, and superb results produced very easily once some familiarity with it has been gained.

The biggest disadvantage is that it is most definitely not WYSIWYG. You only see what you get after the translation and viewing processes have been completed, and that can become a bit tedious after a while. You can spend ages typing in text and commands, only to find that the final version isn't quite what you wanted. That entails going back around the loop until the mistakes have been corrected, and as it takes two or three seconds per page (on an ARM 610 machine) before you see the final effect, editing long documents can become a bit tedious. I'd recommend getting hold of, and working through, some of the tutorial documents available, or buying one of the books on to help in the learning process. A benefit of it being a multi-platform standard is that you can find plenty of help and other resources both in print and on the Internet, so you're not totally on your own.

Where Do I Get It?

The best way of getting hold of a useable version of is by anonymous FTP from Robin Watts) as he is trying to make it as easy to set up as he can. For those without Internet access, both The Datafile PD library and APDL have a recent version, and others may be able to supply it as well. APDL also have the "Gentle Introduction to ", and had I realized it, could have saved me trawling through numerous WWW pages trying to find something to use as a tutorial guide! As translating and viewing a document can take around 2Mb, I'd suggest 4Mb is the minimum memory configuration for easy use. Any less, and things might get a bit awkward at times. All those fonts can upset some other applications as well, especially if you already have a lot of outline fonts installed. Certainly I've had a few normally well-behaved applications crash spectacularly (even taking the whole machine down with them) whilst using ! It is well worth rebooting after finishing a session to clear its fonts from memory, and I wouldn't recommend installing them with your regular outline fonts unless you'll be using a great deal. I have a directory set up with just the files and fonts needed, so that none of them are loaded unless I open that directory, which prevents the fonts from being found by the Filer unless I want them to be.

Sem and Da are two alternative front ends for . To quote Robin Watts' ReadMe file again, they are "for people that are scared of the command line", which probably covers a lot of folk these days! If you do get the version of prepared by Robin and friends, and have problems installing it, he offers to help if he can. He does, however, point out that it is not a Warm Silence Software product, and so I think it would be unfair to expect the same level of support as you'd get for a commercial release.

Conclusions

Given that is free, and is an implementation of a standard typesetting program, it would be churlish to complain about it, and I don't intend to do that. It is something that you will either take to or not, and that you must be prepared to invest time in to learn. If you can cope with it, you will be able to produce just about all the scientific literature you need to far easier than would be possible with programs like Impression, Ovation or Fireworkz. If you absolutely must produce files for whatever reason, then you only have one other choice that I am aware of and that's TechWriter Professional, but I'm getting a bit ahead of myself here. The next article moves onto Formulate and Formulix, the add-on programs for existing DTP and WP packages.


Connectivity - Support - Education - Programming - Acorn Reviews - EPOC32 Reviews - Acorn Links - Psion S5 Links - Home


Any comments? Please let me know.
The pages on this site are all © John Woodthorpe, and are my personal opinions. All trademarks are acknowledged.