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.