Version 1.3
March 1995

                        Hyperlatex
                        ==========

Introduction
============

This is version 1.3 of the Hyperlatex package.  Hyperlatex allows you
to use LaTeX to prepare documents in HTML (the hypertext markup
language used by the world wide web), and, at the same time, to
produce a fine printed document from your input. You can use all of
LaTeX's power for the printed output, and you don't have to learn a
new language for creating hypertext documents.

Note that Hyperlatex is not meant to translate arbitrary Latex files
into Html. Rather, it provides an authoring environment for writing
printed documents and Html documents at the same time, using an
extended subset of Latex (excluding concepts that have no Html
counterpart and adding commands for new Html concepts such as
hyperlinks or included images).

Hyperlatex is ``free,'' this means that everyone is free to use it and
free to redistribute it on certain conditions. Hyperlatex is not in the
public domain; it is copyrighted and there are restrictions on its
distribution as follows:
  
Copyright (C) 1994, 1995 Otfried Schwarzkopf	
  
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.
     
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.
    
A copy of the GNU General Public License is available on the World
Wide web at "http://www.cs.ruu.nl/people/otfried/txt/copying.txt".
You can also obtain it by writing to the Free Software Foundation,
Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


Please report any bugs, preferably with fixes, to me.

	Otfried Schwarzkopf <otfried@cs.ruu.nl>



Disclaimer
==========

Please note that Hyperlatex is just a by-product of Ipe--I wrote it to
be able to write the Ipe manual the way I wanted to. I am making
Hyperlatex available because others seem to find it useful, but please
understand that I'm not in a position to provide professional
support. You can send bug reports to me, and even requests for
features, but as I will only work on Hyperlatex in my free time and
when I have nothing better to do, don't expect an immediate reply.

There will be no new release of Hyperlatex before the fall. Yes, I do
have a list with desired features, and footnotes, customizable
navigation panels, a tabular environment using HTML3 tables,
\newcommands with arguments, and a better math mode are all on
there...


Contents
========

The tar file "Hyperlatex-1.3.tar.gz" contains the following files.

	README			What you are reading
	hyperlatex*		A shell script to execute Emacs macros
	hyperlatex1.el		The Emacs macros to convert Latex->Html
	hyperlatex.el		Emacs macros to go with AUC-Tex
	hyperlatex.sty		The LaTeX macros 
	hyperlatex.tex		The documentation 
	hyperlatex.ind		 ... and its index
	ps2gif			A shell script to convert PS files to Gif
	giftrans.c		A copy of the giftrans program
	next.xbm		Three little bitmaps with icons
	previous.xbm
	up.xbm

Note that the Hyperlatex converter requires that you have Emacs
installed on your system. In fact, I have only tried the macros with
FSF Emacs 18 and 19. I have no idea whether they are going to work
with earlier versions of FSF Emacs, or with other Emacsen.


Installing Hyperlatex
=====================

Installing Hyperlatex is very easy--you just have to copy all the
files into the appropriate places. Here is what you have to do.

(1) Copy "hyperlatex.sty" into your system's TeX macro directory.
    (This is often "/usr/local/lib/tex/inputs").

(2) Copy "hyperlatex1.el" into a directory. Normally that would be
    your Emacs lisp directory (this is often something like
    "/usr/local/lib/emacs/local/lisp"), but it can be anywhere if
    you only call "hyperlatex" from the shell (i.e. not from emacs).

(3) If you want, you can install the three bitmaps "next.xbm",
    "previous.xbm", and "up.xbm" on your WWW server. In that case you
    should change the definition of 'hyperlatex-button-url' right at the
    beginning of "hyperlatex1.el". (If you don't know how to do this,
    you can omit this step. In the case, *our* copy of the icons will
    be accessed---which is okay, but may be somewhat slower).

(4) Byte-compile the Emacs macros in "hyperlatex1.el" (This is not
    strictly necessary, but the Latex->Html conversion will be *very*
    slow otherwise).
    If you don't know how to byte-compile, here is one possibility:
    Go into the directory where you have put "hyperlatex1.el", and type
	emacs -batch -q -no-site-file -l hyperlatex1.el -f hyperlatex-compile
    Byte-compiling will result in a lot of compiler warnings, which
    you can happily ignore.
 
(5) Edit the shell script "hyperlatex" and replace DIRECTORY with the
    directory where you have put "hyperlatex1.el".  Then copy the
    script into a location where it can be executed (e.g. "/usr/local/bin").

(6) That was all! Hyperlatex should be working now...
    You'll test it right away, since you want to look at the
    documentation, which is itself in Hyperlatex format.
    Type
	latex hyperlatex.tex
    to generate a DVI file that you can preview and print as usual.
    (See below if you get a Latex error when you do this.)

    Type (maybe you will need "rehash" first)
	mkdir html
        hyperlatex hyperlatex.tex
    to generate the HTML version of the documentation (It will be
    created in the subdirectory "html", that's why you had to create
    that first). You can browse it with any HTML browser such as
    Mosaic, e.g. by typing: 
	Mosaic html/hyperlatex.html

(7) If you are using AUC Tex to write your Hyperlatex files, the
    macros in "hyperlatex.el" will make your life a bit easier. They
    define the macros and environments of the hyperlatex package.
    Simply make sure that the file "hyperlatex.el" is in a directory
    searched by AUC Tex (see the AUC Tex instructions).

(8) If you plan to convert TeX objects to bitmaps in your HTML documents,
    you should also install the shellscript "ps2gif". Change the
    definition of $PSTOPPM to point to your system's ghostscript
    directory, and install the script in a suitable location (probably
    the same as in (5)). Note that the script calls "giftrans" to make
    the created Gif files transparent. If you like this, you'll need
    to have version 1.8 or higher of "giftrans" installed. The source 
    of "giftrans" is included in this distribution (see the file on
    where it comes from and on its copyright). Just compile it and put
    it somewhere where it can be found. If you already have "giftrans"
    installed, make sure that it is at least version 1.8.


Problems?
=========

The "hyperlatex.sty" package loads another LaTeX2e package
"verbatim.sty" by Rainer Schoepf which has an improved definition of
'verbatim' and (more important for hyperlatex) a definition of a
'comment' environment. You will get a "Environment ifhtml undefined"
error if your version of "verbatim.sty" does not define 'comment'
suitably.  (And of course you will get an error if you do not have
"verbatim.sty".)  If that happens, I recommend that you get a recent
version of "verbatim.sty" from your closest CTAN-site. (There is a nice
Web interface at "http://jasper.ora.com/ctan.html". If you don't have
Web access, look in the TeX FAQ for you nearest CTAN site.)

If you get an error message because you Latex doesn't find 'a4.sty',
your site probably doesn't use A4 size paper. Just remove the
reference to 'a4paper' and to 'a4' from "hyperlatex.tex".


Acknowledgments
===============

The Hyperlatex code is based on the Emacs Lisp macros of the
"latexinfo" package.



Changes
=======

The manual contains a section describing all changes since Version 1.0

