Version 2.2
April 1997

                        Hyperlatex
                        ==========

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

This is version 2.2 of the Hyperlatex package.  Hyperlatex allows you
to use a LaTeX-like language 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, see the end of this document.

The Hyperlatex home page "http://www.cs.ust.hk/~otfried/Hyperlatex/"
has links for the Hyperlatex manual and for downloading the most
recent versions, as well as a few philosophical notes about Hyperlatex.

There is also a mailing list for Hyperlatex, maintained by Roland
Jesse.  This list is for discussion of Hyperlatex and anything that
relates to it.  This is also where new versions of Hyperlatex are
announced. To subscribe to the list send mail to:

	majordomo@cs.uni-magdeburg.de		or
	hyperlatex-request@cs.uni-magdeburg.de

with the following line in the body (not subject):

	subscribe hyperlatex

To send Email to the list, mail to "hyperlatex@cs.uni-magdeburg.de".

The mailing is the only "official" place where you can find support
for problems with Hyperlatex.  In fact, I can no longer answer
personal mail with questions. Please understand 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, and I'm trying to make the manual and
installation instructions as clear as possible, but I absolutely
cannot answer mail about Hyperlatex anymore.  If you have problems
installing or using Hyperlatex, or if you think that you have found a
bug, please mail it to the Hyperlatex mailing list at
"hyperlatex@cs.uni-magdeburg.de".  One of the friendly Hyperlatex
users will probably be able to help you.  And I do read the list
regularly and will try to fix real bugs promptly.

But most of all, enjoy this tool.

  Otfried Cheong



Warning
=======

There has been a considerable revision between Hyperlatex 1.3 and
Hyperlatex 1.4, and between Hyperlatex 1.4 and 2.0. There have been
some changes that make files that worked for Hyperlatex 1.3 (and
earlier) fail with Hyperlatex 1.4 and 2.0.  The manual explains what
exactly those changes are and how to make sure your old files will
work for Hyperlatex 2.0.  However, to be on the safe side, you may
want to leave Hyperlatex 1.3 or 1.4 installed on your system.  In
particular if you are the system administrator installing Hyperlatex
for several users, you should make sure that your users are aware of
the update!


Contents
========

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

	README			What you are reading
	hyperlatex		A shell script to execute the Emacs macros
	hyperlatex.el		The Emacs macros to convert Latex->Html
	hyperlatex.sty		The LaTeX macros 
	hyperlatex.tex		The documentation 
	hyperlatex.ind		 ... and its index
        *.hlx                   Hyperlatex packages
	ps2gif			A shell script to convert PS files to Gif
	*.xbm			Six little icon bitmaps

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


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

Installing Hyperlatex is 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.

(2) If you are going to use them, you should copy the six bitmaps
    "*.xbm" to the icon directory of your WWW server, or, if you
     cannot do that, to your personal icon directory.

    Edit the file "siteinit.hlx". Right at the beginning is the
    definition of "\HlxIcons". Change it to the URL of the
    directory where you put the icons (you must include the trailing
    slash "/"). If the URL for that directory contains a "~", you'll
    have to write that as "\~{}".

    If you don't have a WWW server, or don't understand these
    instructions, then define "\HlxIcons" as the empty string,
    i.e. "\newcommand{\HlxIcons}{}". In that case you'll always
    have to copy the bitmaps into the directory containing your
    output Html files.

(3) Create a directory for Hyperlatex's package files.
    A typical choice could be "/usr/local/lib/hyperlatex".
    Let's call this directory HYPERLATEX_DIR. Copy all files ending
    in ".el" and ".hlx" in the distribution to this directory.

(4) Edit the script "hyperlatex", and set HYPERLATEX_DIR to the
    directory from step (3).

(5) Copy the shell script "hyperlatex" into a location where it can be
    executed (e.g. "/usr/local/bin"). 

(6) Byte-compile the Emacs macros in "hyperlatex.el".
    This can be done as follows (under Unix):
    Change the current directory to HYPERLATEX_DIR, and type
      emacs -batch -q -no-site-file -l hyperlatex.el -f hyperlatex-compile
    On GNU Emacs, this should not give you any error message. If it
    does, you can probably ignore them, but please mail me the error
    messages and the exact version of GNU Emacs that you are using.
    If you are using XEmacs, you might get a few messages about
    variables "bound but not referenced". You can ignore these.
 
(7) 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 (maybe you will need "rehash" first)
        hyperlatex hyperlatex
    to generate the HTML version of the documentation. You can browse
    it with any HTML browser such as Mosaic or Netscape, e.g. by typing: 
	netscape html/hyperlatex.html

    You can also type 
	latex hyperlatex
    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.)

(8) If you plan to convert TeX objects to bitmaps in your HTML documents,
    you should also install the shellscript "ps2gif". Install it
    in a suitable location (presumably the same as in (5)).

    Note that the script calls ghostscript and the two functions
    "pnmcrop" and "ppmtogif". The latter needs to have the
    "-transparent" option to make the created Gif files
    transparent. You can get these 
    programs from the "netpbm" library. If you don't have these
    programs, use archie to find a copy of "netpbm" nearby. You can
    also get "netpbm" from "wuarchive.wustl.edu" (128.252.135.4), in
    directory "/graphics/graphics/packages/NetPBM".


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 your Latex doesn't find
'babel.sty', comment out the "\usepackage[german]{babel}". (The
section explaining this package will look a bit funny then, but
otherwise there is no problem.)


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

The Hyperlatex code was once based on the Emacs Lisp macros of the
"latexinfo" package, but has probably changed beyond recognition since
then. 


Copyright
=========
  
Copyright (C) 1994, 1995, 1996, 1997 Otfried Cheong	
  
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.gnu.org/copyleft/gpl.html".
You can also obtain it by writing to the Free Software Foundation,
Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

