VOICE Newsletter 06/2000 - TeXnical stuff for OS/2 - Creating PostScript and PDF documents with VTeX/2

VOICE Home Page: http://www.os2voice.org

[Newsletter Index]
[Previous Page] [Next Page]
[Features Index]

June 2000
editor@os2voice.org

T_EXnical stuff for OS/2
Creating PostScript and PDF documents with VT_EX/2

By Stefan Schwarzer ©June 2000

Micropress, Inc. : http://www.micropress-inc.com/
VTeX/2 : http://www.micropress-inc.com/os2/
Installation Files: ftp://tug.ctan.org/tex-archive/systems/vtex/

Introduction

In the previous issue of the V.O.I.C.E. Newsletter, I described what TeX and LaTeX are, which distributions exist and how a particular LaTeX distribution, emTeX/TDS, can be installed and used. If you are new to LaTeX, you should read that article before you try to understand this one ;-) .

In my last article, I also mentioned VTeX/2, a typesetting program to convert LaTeX source code directly to PDF files, Adobe's Portable Document Format. Meanwhile, version 7.00 of VTeX/2 has been released and now includes more documentation and a PostScript generation mode.

VTeX is freely available for OS/2 and Linux. Contrary to what VTeX's output during the translation suggests, these versions can be used at no charge for personal or commercial applications. However, it is not allowed to include VTeX in other software without explicit permission from MicroPress.

From now on, I will omit the "/2" part in the name of the distribution and refer to "VTeX" only.

If you plan to generate either PostScript or PDF as final output file format (which satisfies almost all users), you may use VTeX which contains all standard macro packages and fonts but lacks the tools BibTeX and makeindex.

If you need them, you have to obtain them from CTAN separately or have to install emTeX/TDS in parallel on the same partition. (This is described in my previous article.) Because emTeX/TDS contains an installation program it is easier to install, hence, I recommend the latter way. For this, you need an emTeX/TDS version numbered 0.52 or higher. In the parallel installation, VTeX and emTeX/TDS will share the same packages and fonts.

Installing VTeX

To install VTeX you need a file system that supports long filenames, e. g. HPFS.

The needed files for the installation can be retrieved from ftp://tug.ctan.org/tex-archive/systems/vtex/; they are contained in the directories common and os2. Get all the files in these both directories.

After having downloaded them you have to follow the instructions in the file readme-os2.eng. Don't forget to reboot.

To try the examples below, you should also get GSView and Adobe's Acrobat Reader and install them as well.

Examples

Generating a PostScript document

After having set up VTeX we will translate a small LaTeX document to PostScript and then PDF. (You may copy the following LaTeX source code into your favorite editor via the OS/2 clipboard.) Our text is

\documentclass{report}              % we write a report

% This line is yet commented out but needed later:
%\usepackage{hyperref}              % enable hypertext links
                                    % in the table of contents

\begin{document}

\tableofcontents                    % put a table of contents here; this
                                    % will also generate the PDF index

\chapter{Introduction}              % our first chapter

In the previous issue of the V.O.I.C.E. Newsletter, I described what
TeX and LaTeX are, which distributions exist and how a particular
LaTeX distribution, emTeX/TDS, can be installed and used. If you are
new to LaTeX you should read that article before you try to understand
this one ;-).

\noindent\dots

\chapter{Installation of VTeX}

\section{Dummy section}

This section is only inserted to cause nested entries in the table
of contents.

\section{Second section}

This is---almost---useless as well.

\chapter{An example}

After having set up VTeX we will translate a small LaTeX document to
PDF. (You may copy the following LaTeX source code into your favorite
editor via the OS/2 clipboard.) \dots

\end{document}

Now, save the text file as voice2.tex to a working directory of your choice. Then, open an OS/2 command window and change to that directory and translate the LaTeX file. (The drive letter has, of course, to be substituted with that of your actual partition where your working directory resides.)

c:
cd workdir
vlatexp voice2
vlatexp voice2

Note: You have to repeat the last command to build the table of contents. (The reason why you need this is discussed in my previous article.) The output of the last command should look about like

MicroPress (R) vTeX/32, version 7.00
Copyright  (C) 1988-2000 by MicroPress. All rights reserved.
[Personal non-commercial use allowed.]

*** Target: PostScript; generator version 7.00

**@latex voice2
% FORMAT="latex.fmt"
% HYPHEN="latex.hft"
% INCDIR="e:\texmf\vtex\config\;e:\texmf\tex\latex\+;e:\texmf\tex\generic\+;"
(F:/home/text/html/voice2.tex
Verifying format fonts..........................
LaTeX2e <1999/12/01> patch level 1
(e:/texmf/tex/latex/base/report.cls
Document Class: report 1999/09/10 v1.4a Standard LaTeX document class
(e:/texmf/tex/latex/base/size10.clo)) (F:/home/text/html/voice2.aux)
(F:/home/text/html/voice2.toc) [1]
Chapter 1.
[2]
Chapter 2.
[3]
Chapter 3.
[4] (F:/home/text/html/voice2.aux) )
...Processing fonts...
*** Font: e:/texmf/fonts/type1/micropress/cm/cmbx12.pfb (24262->9440b, 31c)
*** Font: e:/texmf/fonts/type1/micropress/cm/cmbx10.pfb (26403->9316b, 26c)
*** Font: e:/texmf/fonts/type1/micropress/cm/cmr10.pfb (26862->13065b, 50c)
Output written on voice2.ps (4 pages, 57385 bytes).
Transcript written on voice2.log.
VTeX was active for 2.66 seconds.

The line

Output written on voice2.ps (4 pages, 57385 bytes).

tells you that a PostScript file with four pages was generated. LaTeX starts each chapter on a new page; the first page is for the table of contents.

Start GSView to inspect the generated PostScript file voice2.ps:

PostScript output from the LaTeX example

Making a PDF file with links for the table of contents

Now return to your editor and remove the "%" in the first column of the second line to cause the inclusion of the hyperref package.

The file is typeset with

c:
cd workdir
vlatex voice2
vlatex voice2

on the command line which generates a program output similar to the one shown above. Again, you get four pages.

To view the result of the translation, double click the Acrobat Reader icon and open the freshly generated file. The Acrobat Reader window should look like the screenshot below.

Our first example viewed in the Acrobat Reader

On the left side (pointed to with the mouse) you see an overview of the document's structure, derived from the table of contents that the LaTeX document supplied by means of the \chapter and \section commands. If you click on the hollow triangle, the sections of the corresponding chapter become visible. From here, you may jump to the contained chapters and sections.

On the right side the first page of the document is shown. Note that some text lines are blue; these are links. Try them as well to jump to the chapters and sections. (Of course, you may also flip through the document with the black triangle buttons on the top.)

Adding more links to the document

A reference to a chapter

Now, we will add more references to the text. In your editor, go to the line that reads

\chapter{Installation of VTeX}

After it, insert

\label{installation}

This command attaches a label to the chapter so that it can be referenced from other places in the text. To insert such a pointer, search for

After having set up VTeX we will translate a small LaTeX document to
PDF. (You may copy the following LaTeX source code into your favorite
editor via the OS/2 clipboard.) \dots

and add

This link points to chapter \ref{installation}.

to below the last line of the text. (There has to be a blank line above the added sentence to introduce a new paragraph.) Note that the name of the label, 'installation', is the same for both commands.

A reference to a label in the text

Update the chapter 'Introduction' to read

In the previous issue of the V.O.I.C.E. Newsletter, I described what
TeX and LaTeX are, which distributions exist and how a particular
LaTeX distribution,
\hypertarget{target:emTeX}{emTeX/TDS},
can be installed and used. If you are
new to LaTeX you should read that article before you try to understand
this one ;-).

and add the lines

This link points to the mentioning of the
\hyperlink{target:emTeX}{emTeX/TDS distribution}.

after the last line of the last chapter (leaving an empty line above the insertion). The \hypertarget command is similar to the LaTeX \label command while \hyperlink is comparable with \ref. However, \hyperlink needs an additional text argument; \ref gets the reference text through the position of the corresponding label.

A link into the World Wide Web

You may even link from your PDF document into the WWW. As an example, add

This is a link to the
\href{http://www.micropress-inc.com/os2/}{VTeX/2 homepage}.

(again with an empty line above) to the last chapter, "An example".

What will we get?

After all the modifications (which are summarized here), translate the LaTeX file again. Remember to process it twice to resolve all references. If you reload it into the Acrobat Reader - by closing and re-opening the PDF file - and advance to the last page, you will see something like

You see three colored links:

The first is the result of the LaTeX \ref command, pointing to the \label "installation".
The second is a link pointing to a target contained elsewhere in the same document.
Finally, the third even links "out of" the Acrobat Reader. If you click on it, an instance of your set web browser (e. g. Netscape Communicator) will be launched (though this will only work if a browser is associated with URLs).

To trigger the links, you have to position the mouse pointer over them, so that the hand turns into a pointing finger.

Conclusions

VTeX/2 is a free TeX and LaTeX system for OS/2 that is able to generate PostScript and PDF output without the intermediate DVI file needed by other distributions. Unfortunately, the distribution doesn't contain the tools BibTeX and makeindex; if you need them, the installation process becomes rather protracted.

We have seen that PDF files not only allow to incorporate links with their corresponding targets but also that this feature can be used with VTeX/2 in several ways, depending on the type of the link.

Thus, you get the ability to typeset scientific (and other) documents in high quality and additionally make use of hyperlinks in the text, either generated by standard LaTeX commands like \ref or by special commands contained in the hyperref package. In contrast to programs like Acrobat Distiller, you get the native OS/2 software for this at no charge. (Though this hasn't been covered in this article, VTeX, like the Distiller, is able to include PostScript graphics files into PDF documents.)

I thank Walter Schmidt for his valuable comments during the preparation of this article.

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 :-)

Features
editor@os2voice.org
[Previous Page ] [ Index] [Next Page ]
VOICE Home Page: http://www.os2voice.org

TEXnical stuff for OS/2 Creating PostScript and PDF documents with VTEX/2