                 armTeX 3.14159 - Release 3  8. June 1998
                 

This distribution contains armTeX 3.14159 with pre-installed versions of
plain TeX and LaTeX2e and the tools and graphics packages. It was put
together by Jakob Stoklund Olesen and Reuben Thomas.

TeX, LaTeX and Metafont is free software and may be freely copied. Source
code is provided. There is NO WARRANTY.

TeX requires filenames which are longer than 10 characters. Use Richard
Atterer's raFS, Jason Tribbeck's LongFiles or the RISC OS 4 FileCore. It
may also be possible to use an MS-DOS disc as almost all filenames fit
in 8+3 characters. 

You can get the latest version of raFS from
   http://home.augsburg.baynet.de/richard.atterer/
and LongFiles from
   http://www.tribbeck.com/


What is TeX?


TeX is a typesetting system. TeX itself is quite primitive,
concentrating on the typesetting of words, paragraphs, and mathematical
equations. Most people use the LaTeX package, which sits on top of TeX
and provides commands used to structure documents, dealing with
sections, tables of contents, indices, figures, tables, cross-references
and so on.

(La)TeX is a command-driven system: files are edited as plain text
containing commands rather than using a WYSIWYG editor (if you can't
live without WYSIWYG, try Icon's TechWriter). The file is then processed
by TeX into a DVI (DeVice Independent) file which can be viewed and
printed with DVIView.

This may seem like stone-age technology at first, but it has some
advantages:

1. Because TeX is not WYSIWYG, it can take longer to process text than a
wordprocessor, and typeset it to a far higher quality, choosing better line
and page breaks, for example.

2. LaTeX is designed to make you concentrate on the logical structure of
the document rather than its look, which avoids the temptation to fiddle
with small details, and makes it easier to produce consistent
well-designed documents (the standard document formats have been
designed by typographical experts).

3. Because TeX is programmable, it has been extended enormously, and
there is an extension package for just about every job you can imagine.
There are even music typesetting extensions.

Also, good editors such as StrongEd and Zap have syntax-colouring modes
for editing (La)TeX files that make them much easier to read during
editing.

For another view of TeX, see the file ReadMe-Watts.


Getting Started


If you are new to TeX you should consider buying a book to help you
getting started; TeX has a rather steep learning curve. We recommend the
following books:

LaTeX


Helmut Kopka and Patrick W. Daly: `A guide to LaTeX2e'
    An excellent up-to-date introduction to LaTeX. Recommended as a
    first book, it is also a good reference work.

Goosens, Mittelbach and Samarin: `The LaTeX Companion'
    The second book you should buy for LaTeX. It has descriptions of
    many extension packages for LaTeX, most of which are available on
    CTAN (see "Finding out more"). The LaTeX Companion saves you time
    trawling through CTAN to find them and acts as a quick reference for
    the packages you use. The packages themselves make many tasks
    easier, and improve the quality of various aspects of LaTeX's
    typesetting enormously. The book also contains in-depth explanations
    of the more obscure corners of LaTeX, so it is an excellent
    reference for experts and those who wish to write LaTeX packages.
    See the file texmf:doc.latex.base.compan/err for errata.

Goosens, Mittelbach and Rahtz: `The LaTeX Graphics Companion'
    This book is in the same style as `The LaTeX Companion', but with
    much greater coverage of graphics. Graphics can be hard to use in
    LaTeX, and this book discusses many ways of overcoming the
    difficulties. Recommended for those who need to produce diagrams or
    add graphics from other sources to LaTeX documents.

Leslie Lamport: `LaTeX - a Document Preparation System'
    The definitive LaTeX manual by the author of LaTeX. Be sure to get
    the second edition which covers LaTeX2e. There is a list of errata
    in texmf:doc.latex.base.manual/err. This book is mainly of interest
    to advanced users and programmers.

TeX


Paul W. Abrahams et al: `TeX for the Impatient'
    A good introduction and reference for TeX. Especially useful for
    LaTeX users who occasionally need to get their hands dirty and delve
    into TeX's innards.

Donald E. Knuth: `The TeXBook'
    The definitive manual for (plain) TeX by the author of TeX. This
    book is probably not for beginners. An electronic version is
    available from CTAN:systems/knuth/tex/texbook.tex.

All of these books are published by the Addison-Wesley Publishing
Company. If you have no money to spend you should be able to learn the
basics from the files in the Examples directory and some of the other
files in this directory (texmf:armtex.doc).


Running TeX and LaTeX


The Examples directory (in base.zip) has a few examples of TeX and LaTeX
input. Double-click on a file to run it through (La)TeX. This will create
files with extensions /dvi and /log. The /dvi file is the typeset output
which can be displayed with !DVIview. The /log file is a transcript of the
session. LaTeX also creates an /aux file with cross-reference information.
The input files must have an extension, otherwise TeX will not know how to
name its output files. Usually the extension is /tex but any extension will
do.

If the input file has no extension, TeX will simply create files called
dvi and log. This is for compatibility with the old version of armTeX
which used '.' as the extension separator. To try this create a
directory called story2, copy the file story/tex into it and rename it
to tex. Double-clicking on this file will create files story2.dvi and
story2.tex. Some people (like me) prefer it this way because it gives
you cleaner directory displays.

You can also run TeX and LaTeX from the command line. Change directory to
Examples and open a task window. Type

    LaTeX small2e/tex

which has the same effect as double-clicking the file. You can also say

    LaTeX small2e.tex

or just

    LaTeX small2e

TeX will use the /tex extension if none is given. Use the TeX command to
run TeX with the default plain format like this:

    TeX story

or, to preload another format say:

    TeX &texinfo diff.texi

Note that the GNU Texinfo format is not supplied with this distribution
(but texinfo.tex is in extras.zip). See the file Technical/tex for how
to build your own formats.


Finding out more


The file Changes/tex lists the differences from the old release 2. There
has been some major changes so you should read it if you have used TeX
on RISC OS before.

The file Technical/tex contains some technical details about armTeX
which you need to know if you want to change the setup.

If you have Internet access you can get all sorts of packages and other
TeX resources for TeX at the CTAN (Comprehensive TeX Archive Network)
sites. The primary sites in Europe are

    ftp://ftp.tex.ac.uk/tex-archive/
    ftp://ftp.dante.de/tex-archive/

The file CTAN/sites has a list of mirrors. The primary CTAN sites are
heavily loaded and it is recommended to use a mirror close to you. If
you are in the UK then sunsite.doc.ic.ac.uk is a good place to start.


The TeX Directory Structure


Most of the files in this distribution are organised in the TeX
Directory Structure (TDS). This is a standard way of organising TeX
installations which is used almost everywhere. You can open the root of
the primary TDS tree by double-clicking on the !TeX application. I have
scattered files called !Contents throughout the tree with short
explanations of what goes where. A really detailed description of the
TDS is in the directory texmf:doc.general.tds. This paper is also
available from CTAN in the directory CTAN:tds/standard/

The only files which aren't kept in the TDS are the fonts. They are
better off in Paul Field's !TeXFonts directory.

The directory !TeX.texmf.local is meant to hold another TDS tree which
is maintained by you. When you install new packages you can put them in
there and future upgrades to armTeX will leave them alone.

The TDS was designed to work well in installations. It is not the same
as the directory layout found on CTAN. With the TDS files are organised
with respect to their function. On CTAN files are collected in packages
that should be distributed together.


Acknowledgements


This port of TeX to RISC OS was not done by me. It is just a few changes
made to Mark Sinke's port of web2c-TeX from 1993.

Carol Carpenter is kindly donating FTP space for this distribution at
ftp://freenet.barnet.ac.uk/pub/Acorn/armtex/

Reuben Thomas helped me put this distribution together, keeping me at it
with lots of ideas, questions and criticism.

Graham Toal made the first TeX port for RISC OS.

Robin Watts did a lot of work on the previous release 2 from 1996 and
provided FTP space for it.

Bryan Scattergood put the previous distribution together.

Paul Field wrote !DVIview and designed the !TeXFonts directory structure.

Olly Betts wrote the AddToPath utility.


Contacting me


If you have any problems, questions, comments, ideas, anything really,
please feel free to contact me.

Jakob Stoklund Olesen <stoklund@usa.net>
