Directory support/hyperlatex

Version 2.9
November 2006

                        Hyperlatex
                        ==========

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

This is version 2.9 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://hyperlatex.sourceforge.net"
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.  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 see the link at hyperlatex.sourceforge.net.

To send Email to the list, mail to "hyperlatex-users@lists.sourceforge.net".

The FAQ and the mailing list are the only "official" place where you
can find support for problems with Hyperlatex.  

But most of all, enjoy this tool.

  Otfried Cheong & subsequent collaborators


Contents
========

The tar file "Hyperlatex-2.9.tar.gz" contains the following files and
directories: 

   README             What you are reading

   bin                Executable files, including:
     hyperlatex       A shell script to execute the Emacs macros
     ps2image         A shell script to convert PS files to images.
     normalize-eps.awk An awk script for manipulating PS images.

   hlx                Style and emacs files including:
     hyperlatex.el    The Emacs macros to convert Latex->Html
     *.hlx            Hyperlatex packages
     contrib/*        Contributed hyperlatex packages 
                      that may or may not work for you

   etc                Miscellany, including:
     hyperlatex.sty   The LaTeX macros 

   doc                Documentation files, including:
     hyperlatex.tex   The documentation 
     hyperlatex.ind   ... and its index
     *.png            Four icon bitmaps

Note that the Hyperlatex converter requires that you have Emacs
installed on your system.  Emacs 20 and 21 are supported.  Previous
versions may work, but it's up to you to figure that out.

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 TeX macro directory.  It's in the
    etc subdirectory of the discribution.  Note that if you are the
    administrator and put the file in the system-wide macro directory
    (a natural place would be 
    /usr/share/texmf/tex/latex/misc/hyperlatex.sty on many systems), 
    you may have to run "texhash" as root to remake the index that is
    needed to find the file.

(2) If you are going to use them, you should copy the bitmaps "*.gif"
    to an 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.  This is the default behavior.

(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.  They are all in the
    hlx subdirectory.

(4) Edit the script "hyperlatex", and set HYPERLATEX_DIR to the
    directory from step (3).  In other words, change the following
    line 

       HYPERLATEX_DIR="$HOME/Hyperlatex/Hlx"

    to be 

       HYPERLATEX_DIR="your_hyperlatex_directory"

    where of course `your_hyperlatex_directory' is the directory you've
    picked for your Hyperlatex files.
	
(5) Copy the shell script "hyperlatex" (it's in the bin subdirectory)
    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 post the error
    messages and the exact version of GNU Emacs that you are using to
    the mailing list.  If you are using XEmacs (which is unsupported,
    but seems to work), you'll get quite a few warnings that you can
    safely ignore. 
 
(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 "ps2image". Install it
    in a suitable location (presumably the same as in (5)).
    Also install the awk script "normalize-eps.awk" in HYPERLATEX_DIR. 
    These are both in the bin subdirectory.

    Note that the script calls awk, ghostscript and the two functions
    "pnmcrop" and "ppmtogif". The latter needs to have the
    "-transparent" option to make the created image files
    transparent. You can get these programs from the "netpbm"
    library. 


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 line "\usepackage[german]{babel}". (The
section explaining the babel 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 changed beyond recognition since then.


Copyright
=========
  
Copyright (C) 1994-2002 Otfried Cheong	
Copyright (C) 2002-2006 Tom Sgouros
  
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.