May 2000
editor@os2voice.org

## TEXnical stuff for OS/2 First steps

By: Stefan Schwarzer <s.schwarzer@ndh.net>

## What are TeX and LaTeX?

TeX, and especially its much more user-friendly descendant LaTeX, are used to generate text documents, mostly of scientific nature. Both are available for many operating systems. That's the short answer.

A more detailed answer is that both programs are typesetting systems, not word processors like StarWriter, to mention an example. In a word processor, you usually determine the appearance of a piece of text by selecting menu entries (or buttons) like "12 point, bold". This is called visual markup.

In LaTeX, you use logical markup, that is, instead of determining the appearance of the text directly, you assign it a function; perhaps you tell LaTeX that the string you just entered is the headline of a new chapter. Also, in contrast to word processors, you write your documents in a text editor of your choice, e. g. OS/2's Enhanced Programmer's Editor (EPM). The markup is mixed in the text by means of formatting instructions. Then, the text file is processed by a translation program. The output is a DVI file (from "device independent"), which then is converted to the final file format, e. g. PostScript or PDF, by use of a driver program. (Though this might sound complicated, it isn't anymore if you have done it a few times.)

If you are now curious how LaTeX code might look like, here is some.

## A small example

If you want to write a short text, you may type in your editor

\documentclass{article}         % write an article (or other short text)

\begin{document}                % begin with the document
\tableofcontents                % put a table of the contents here
% articles normally don't have a table
% of contents but we put one here for
% illustration

\section{A \LaTeX{} example}    % start a new section

\subsection{A very short subsection}
Some text goes here \dots       % three literal dots would be too close together
% plain text doesn't need special formatting

\subsection{A somewhat longer subsection}
Now we type a bit more text to show how \LaTeX{} formats paragraphs.
Irrespective of how many consecutive spaces     you type, they
come out as a single space. A line break is handled like a
space character, too.

As a special case, two consecutive line breaks tell \LaTeX{} to
start a new paragraph. Note that the line breaks in the editor
are not the same as those done by the typesetting system.

This is an unordered list:
\begin{itemize}
\item  You don't have to think of vertical space above and below
the list.
\item  The indentation is also handled for you.
\end{itemize}
Here the text continues. Since we wrote it directly---without
an empty line---under the list commands, we didn't begin a new
paragraph.

\end{document}

and the result is:

Nice, isn't it? All the numbering and formatting has been done for you.

• Page layout
LaTeX does a very good job not only at line breaks but also at page breaks. Figures and table can "float" through the text if you want. That is, LaTeX will normally put the pictures etc. on the top or bottom of the page but is able to fill the gaps also with text that you wrote below the floating items.

• Mathematical formulas
LaTeX is especially known for its ability to typeset mathematics. For example,
A test formula:
$$\int \limits _0 ^\infty \frac{\sin bx}{x^s} = \frac{\pi b^{s-1}}{2 \Gamma(s) \sin s\pi/2} \quad , \quad 0 < s < 2 \label{Eq:integral} % see next item$$

will give

The label on the right is set automatically. More formulas will get ascending numbers.

• Handling of labels and references
You may use as many labels as you want. An example of a label is given above; you could reference it with \ref{Eq:integral} to let the number of the formula, 1, appear at the place of the reference command.

• Helper applications
LaTeX comes with several programs that are very useful, especially for scientific documents. One is BibTeX, a program to handle references that are used in your document. To do this, BibTeX accesses a literature database you supply and inserts appropriate text in the place of the reference in your text, and puts a formatted list of all literature you used at the end of the document. You can use the same database for multiple documents and choose the layout of the reference list on a per-document basis.

Another program is makeindex. As you may guess, it is used to generate indices with keywords and their corresponding page numbers.

Conversion from DVI to PostScript format is easily done with dvips, which is also delivered with LaTeX.

• Stability and reliability
LaTeX and its supporting programs are thoroughly tested and very stable. Additionally, LaTeX only reads your file but never writes to it, so it can't modify (and thus damage) it.

In contrast to almost all word processors, you see every single command in your document, so you won't be surprised by effects of "invisible" commands.

## LaTeX distributions for OS/2

LaTeX usually comes in form of so-called distributions, that is, LaTeX and its accompanying helper applications are bundled in different ways. Though there is a common set of applications (see above) in each distribution they differ in the supplied viewer programs and the number of packages (files used to add or extend LaTeX commands to provide more functionality). The following distributions are available for OS/2; you can find all of them on a CTAN ("comprehensive TeX archive network") server, e. g. at ftp://tug.ctan.org/tex-archive/ (in the USA) or ftp://ftp.dante.de/tex-archive/ (in Germany). Notes: You should get the current versions always from the CTAN archives, not from Hobbes or similar sites. You can get whole directories in a ZIP file if you append .zip (notice the dot) to the directory name.
• "Classical" emTeX
Probably the most used free LaTeX distribution is emTeX. The "em" in its name comes from its maintainer, Eberhard Mattes (who is known even more for his port of the Gnu C compiler, emx). Unfortunately, emTeX is a bit outdated now.

• emTeX/TDS
This is the emTeX port, repackaged with additional LaTeX packages and organized in the TeX directory structure (to which LaTeX distributions for most operating systems comply). This distribution, maintained by Walter Schmidt, is also freely available. He also has written an extension (called TeX front end, TFE) for OS/2's EPM editor, so you can typeset and view your documents from the editor.

• OS/2TeX
OS/2TeX is a shareware distribution, made by Jürgen Kleinböhl and sold for 70 DEM (about \$35). It goes beyond the classical emTeX distribution by an editor (with syntax highlighting) which also provides menu access to LaTeX's translation and to the DVI preview.

• VTeX/2
This is a more recent distribution which origins from the company MicroPress Inc. (also see the VTeX/2 page). The distribution is also free (though it's not allowed to bundle it with commercial products). VTeX/2 is special in the regard that it translates directly from LaTeX source code to Adobe's PDF file format. The generated files can also use links to jump to another place in the document or access URLs on the internet!
Because I personally prefer and use emTeX/TDS, I'll describe its installation and use in more detail. My next article will concentrate on VTeX/2.

## Installing emTeX/TDS

The current version at the time of this writing is 0.53 from March 22nd, 2000. You need a file system that supports long filenames and a partition with about 30 MB free to install emTeX/TDS. Furthermore, you should get and install GSView and Ghostscript to view PostScript files. (You need the archives gsv29os2.zip and gs601os2.zip.) GSView is described in the March issue of the V.O.I.C.E. newsletter- http://www.os2voice.org/VNL/past_issues/VNL0300H/vnewsf5.htm. Both GSView and emTeX/TDS require the latest emx runtime package (version 0.9d). To get the complete distribution go to ftp://CTAN/systems/os2/emtex-contrib/emtexTDS/ (for "CTAN" you can substitute any CTAN mirror site, s. a.).

The file readme.eng which you fill find there, is the determining source for installation instructions. Though, I'll summarize it in short, assuming you install emTeX/TDS from scratch:

1. Install GSView and Ghostscript (see the March issue of the V.O.I.C.E. newsletter for this).
2. Create a temporary directory.
3. Put there the files from the emTeX/TDS directory on CTAN, namely readme.eng, tdsinst.cmd, config.zip, and texmf.zip .
4. Get the files bibtex4b.zip, dvid16h1.zip, dvid16h2.zip, makeindx.zip, mf4b.zip, mfjob12d.zip, mfware.zip, tex4b.zip, and texware.zip from the original emTeX directory. Place them also in the above mentioned directory.
5. Change to the directory where you placed the installation script  tdsinst.cmd, start it, and follow its instructions.
6. Copy the fix file config.ps into the directory \texmf\dvips\base\ of your emTeX/TDS installation, overwriting the old file. (This is an official bugfix.)
7. Reboot OS/2!
8. Open a command window and enter  makelatex  at the prompt in any directory.
9. Issue  makemf  next.
10. Read \texmf\doc\emtextds\manual.eng which can be found in your emTeX/TDS installation partition.

After the installation, sit back, and drink a cup of coffee or tea :-) . Then, let's typeset and view the introductory example from above.

## Using emTeX/TDS

### Translating a LaTeX file

First, you should create a directory for your LaTeX files, whether from the WPS or the command line. Then open an OS/2 window if you don't already have and make that working directory the current, i. e. change to it.

Next, you have to enter the LaTeX source code from above in your favorite editor. Create a file example.tex in your working directory and copy the LaTeX source from your browser window to the editor. Don't forget to save the file.

Change to the command line and type

[C:\WORKDIR\]latex example

(You may omit the suffix .tex.) The latex command will output something like
This is emTeX (htex386), Version 3.14159 [4b] (no format preloaded)
**&latex example
(example.tex
LaTeX2e <1999/12/01> patch level 1
(e:/texmf/tex/latex/base/article.cls
Document Class: article 1999/09/10 v1.4a Standard LaTeX document class
(e:/texmf/tex/latex/base/size10.clo))
No file example.aux.
No file example.toc.
(e:/texmf/tex/latex/base/omscmr.fd) [1] (example.aux) )
Output written on example.dvi (1 page, 1616 bytes).
Transcript written on example.log.

The second last line is the most important; it tells you that a DVI file of your LaTeX source has been created and that it contains one page.

### DVI preview

Now, you can view the DVI file. Type
[C:\WORKDIR\]start vp example

When you are asked to create missing fonts, answer with "Yes". LaTeX (more exactly, its companion program Metafont) creates the character bitmaps for the fonts. Confirm the question in the message box to load the fonts.

So type again (you can use the arrow-up key)

[C:\WORKDIR\]latex example

and reload the DVI file into the previewer program. (If you have "Auto reload" under the "File" menu enabled, the file will be loaded automatically.) Compare the outputs of the two LaTeX runs: The both lines
No file example.aux.
No file example.toc.

from the previous run no longer show up.

This is the viewer main window you get.

### Creating PostScript documents

We can convert the DVI file to a PostScript document easily:
[C:\WORKDIR\]dvips -P cmfonts example

which outputs
This is dvips 5.83 Copyright 1998 Radical Eye Software (www.radicaleye.com)
dvips: *** HP LaserJet/600dpi ***
' TeX output 2000.04.17:2113' -> example.ps
<texc.pro><texps.pro>. <cmsy10.pfb><cmr7.pfb><cmbx12.pfb><cmr10.pfb>
<cmbx7.pfb><cmbx10.pfb>[1]

Don't worry, if you don't have a Laserjet printer. It is not needed to print the PostScript file, though the second line seems to imply that.

Start GSView to look at the PostScript file by clicking the GSView icon on your desktop and opening example.ps in your working directory. Alternatively, you may open your working folder and double-click on example.ps. (Similar to the DVI previewer, the reloading of the file upon changes can be automated if "Auto Redisplay" under the "Options" menu is enabled.) The file looks like

To print the file, select "File", then "Print ..." from the menu, and choose an appropriate printer driver (see the GSView and Ghostscript documentation for this). If you want to generate a PDF file, you may use the following settings:

After clicking on "Ok", you will be prompted for a filename to write the data to.

### Working more effectively

This was an introduction, step by step. In practice, the work is not that clumsy. Instead, you might work as follows:
1. Start GSView and your editor, and open an OS/2 command window.
2. Change to your working directory.
3. Edit your text and save it.
4. Change to the command window and type once
    latex example & dvips -P cmfonts example

For further invocations you only need the arrow-up key. It may be necessary to repeat the command to update the table of contents or references in the text.
5. Load the result in GSView; if you have "Auto Redisplay" from the "Options" menu enabled, you also have to do this only once.
So all you have to do from now on is editing and pressing the arrow-up key in turn :-) . If you use EPM as your editor, you may use Walter Schmidt's TeX front end instead.

## Conclusion

Now, you may ask, if LaTeX is the right tool for your everyday texts. If your documents are rather simple, I think not. However if your text contains, for example,
• many pages
• many pictures and/or tables
• complex and/or many mathematical formulas
• more than a few cross references
• bibliography sections whose styles changes from text to text (e. g. for different journals)
you should examine LaTeX further before giving up too early. It may be that the (at first) steep learning curve pays off. By the way, the cycle described above is very simple once you have learned it. The more difficult thing is to learn to do certain things with LaTeX commands. A good starting point is the The not so short Introduction to LaTeX2e by Tobias Oetiker and others.

## What comes next?

A new improved version of VTeX/2 (version 7.00) will be released at about the time you read this. It will be able to generate PostScript or PDF files directly from LaTeX source. In contrast to GSView's output, these PDF documents can contain links to other places in the document or into the WWW.

Therefore, I would like to present an article on VTeX/2 in the next issue of the V.O.I.C.E. newsletter.

For comments and wishes regarding articles on LaTeX and OS/2 please send a mail to Stefan Schwarzer.

## Appendix: Some resources

As I said, the most difficult thing is not to operate the programs latex and dvips, but to learn the LaTeX language.

There are several resources on the internet and in printed form available. (LateX2e is the official name of the latest LaTeX version.) Online resources are

Recommended printed documentation is
• LaTeX: A Document Preparation System by Leslie Lamport. Addison Wesley, ISBN 0-201-52983-1 (a very good start)
• The LaTeX Companion by M. Goossens, F. Mittelbach, and A. Samarin. Addison Wesley, ISBN 0-201-54199-8 (describes more sophisticated topics, not a good book to learn LaTeX from the beginnings)

Stefan Schwarzer is a Chemical Engineer living in Germany and working with OS/2 for three years. He uses LaTeX for his work and privately for two years now. Stefan currently works on his PhD thesis which will be written with LaTeX under OS/2, of course :-)