# Documentation of hypertex

Updated on July 9, 2008.

## Introduction and installation

Basically, hypertex is a program that allows you to write HTML pages more easily, and especially to include mathematical formulas with no effort. All HTML tags and a few tags can be used directly.

formulas will be converted to images, then a little bit of Javascript is used to position and scale the images properly. Note that the result may not be satisfying on low-resolution screens or browsers with poor image-scaling capabilities.

A typical hypertex source file with a mixture of and HTML may look like:

\title{My Title}

We are going to study the function $f(x)=\sqrt{x}$ defined by <A HREF="http://en.wikipedia.org/wiki/Pythagoras">my colleague Pythagoras</A>...

and the HTML file may be obtained by running hypertex on that file. Look at the result.

The standard distribution includes a sample file: see the result obtained and the source file.

To install the program, download this file, uncompress it with tar -xzf hypertex.tar.gz go into the hypertex directory and type make (or make hypertex.fr for the French version). You will need reasonably up-to-date versions of Ghostscript and ImageMagick installed on your system.

Note that hypertex is not a LaTeX to HTML converter: basically it waits for a HTML file with some mathematical formulas and sectioning commands. However, a similarity with TeX is that you make paragraphs simply by leaving a blank line.

## Use

If your source file is myfile, you run hypertex with :

hypertex myfile

This will generate myfile.html. If you want this file to bear another name, such as strangename.html, insert \name{strangename} in the document.

The -suffix option allows you to specify another file extension (eg .php). Thus, hypertex myfile is equivalent to hypertex -suffix .html myfile

With the -reuse option, hypertex will reuse the TeX formulas obtained in the previous compilation (which saves a fairly big amount of time). However, these formulas must be exactly the same, in the same order as when the last compilation occurred.

The -notex option prevents hypertex from generating images for TeX formulas.

The -verbose option prints additional information during compilation.

## Using LaTeX formulas

You can type LaTeX formulas directly by enclosing them into the right delimiters. hypertex recognizes the following ones:

• $...$
• $...$
• $$...$$
• \begin{equation[*]}...\end{equation[*]}
• \begin{eqnarray[*]}...\end{eqnarray[*]}

(If you want these genuine symbols to appear in your file, prefix them with a \.)

\tex{mytextext} and \texcommand{mytextext} in your file will send any command yourtextext to LaTeX (in standard text mode). The former will include the resulting output in your HTML file (useful e.g. for invoking the mathematical environments defined by LaTeX), while the latter will not (useful to define LaTeX macros to be used later on).

If a file named texhead is found in the current directory, it will be used as beginning of the temporary TeX file used by hypertex. This is very useful to define TeX macros or include TeX packages. The default texhead file, which is used if none is provided, contains:

\documentclass[12pt]{article}
\begin{document}
\boldmath

(Note that \begin{document} is mandatory in the texhead file.)

Similarly, a texfoot file may be provided. The default contains only \end{document} (which is mandatory as well).

## Macro definitions and .htxrc

You can define macros in your files with the command \def. The syntax is:

\def{\myfunctionname}{definition}

Macros can take 0 or 1 argument. In the definition, the argument is invoked with the # symbol (type \# if you want a genuine #).

The macro is simply invoked with:

\myfunctionname{myargument}

If the same macro is defined several times in the file, only the last definition in the whole file will be used.

You can define standard macros for all your documents by putting them into the .htxrc file, either in the current directory or in your home directory. For example, it may contain something like
\def{\section}{<hr><h2>#</h2>}

A sample .htxrc file goes with the distribution. See also the .htxrc file I use for this site.

## Links and document structuration commands

There are several commands to generate complex documents.

• \title{}. This specifies the document title.

• \maketitle. This inserts the document title.

• \page{link}{subpage}. This creates link to a new subpage. link is the text of the link, and subpage, which follows the same syntax as the main file, is the contents of the subpage.

• \include{filename}. This will insert file filename and process it.

• \name{myname}. This specifies that the output of the currently processed file will be named myname.html.

• \toparent{link}. In a subpage, inserts a pointer to the parent page, with text link.

• \newpage. Cuts the document here, and puts the following in a separate HTML file. From now these files will be referred to as the preceding and following file of each other.

• \tonext{link}. Inserts a pointer to the following file, with text link.

• \toprev{link}. Inserts a pointer to the preceding file, with text link.

• \makeparenttitle, \makeprevtitle, \makenexttitle. Inserts the titles of the parent, preceding or following file.

• \ifparent{}, \ifnoparent{}, \ifprev{}, \ifnoprev{}, \ifnext{}, \ifnonext{}. Insert their argument if there is, respectively, a parent file, no parent file, a preceding file, etc.

• \meta{text}. Memorizes the text in a buffer that can be invoked with \makemeta (in my standard HTML headers, used to define the contents of the <meta http-equiv="Keywords" content=> HTML tag, cause it couldn't be reached another way).

The files htmlhead and htmlfoot (suffixed with .f for the French version) will be included and processed at the beginning and at the end of each HTML file produced. They apply to all documents located in the current directory.

This is useful e.g. to include CSS files, document type specification etc.

The standard htmlhead file, which is used by default, contains:

<html>
<title>\maketitle</title>
<style type="text/css">img.hyperteximg{vertical-align:middle;}</style>
<script type="text/javascript">
function ResizeImage()
{
var nodes=document.images;
for(var i=0;i<nodes.length;++i)
if(nodes[i].className=="hyperteximg"){
nodes[i].style.height=nodes[i].height/48+"ex";
nodes[i].style.display="inline";
}
}
</script>
<h1>\maketitle</h1>
\totable{
Table
<br><br>}
\toparent{
Up
<br><br>}
\ifprev{
Previous page: \toprev{\makeprevtitle}
<br><br>}



while the standard htmlfoot is:

\ifnext{<br><br>
Next page: \toprev{\makeprevtitle}
}
\toparent{<br><br>
Up
}
\totable{<br><br>
Table
}
</body>
</html>


Note in particular the Javascript code included in the htmlhead file to handle image resizing. This should be included in any htmlhead file you might write, so that it is recommended to start with the above and instead of writing them from scratch.

In order not to run into a loop, there should be no \newpage command in the html* files.

## Other commands

The \shell{command} command sends command to a shell, then puts the result in the file. Note that the result itself is scanned by hypertex, but it may not contain structuring commands (no \newpage, \title...).

The \date command will output the compilation date in long format (in French for the French version).

As you can see, all HTML tags can be included in an hypertex file. Provided that your html(head|foot) files are empty, you could also theoretically send a genuine HTML file to hypertex, which in return will send it back to you (that's a useful program)... except if it contains some \$ or any other symbol which could be interpreted as a hypertex command (prefix them with a \).

But a nice difference between writing HTML and hypertex files is that the latter don't require to put these nasty <P> tags at each paragraph (simply leave a blank line).

The French version also takes into account some French typographical conventions such as inserting a non-breakable space before a semicolon, French quotation mark...

Special characters that would otherwise be interpreted as hypertex commands can be obtained by prefixing them with a \.

## Restrictions and bugs

Non-HTML material (TeX formulas, macros...) MAY NOT be put, in general, in titles, link names, command arguments, etc.

It is extremely easy to have the program run into a crash. For example, there is no test for recursivity of the macro definitions. Or there is no test for the presence of \newpage in the HTML header/footer files, which would send the program into a loop.

Generally speaking, the program has been written to run on casual files, but very few code was included to avoid errors while handling too complex files.

## Copying

Copyright Yann OLLIVIER 1998-2000 (contact (domain) yann-ollivier.org )

This software may be freely distributed as is, including this notice.

There is absolutely no restriction regarding the documents produced by running this software.

The software may be modified, but any modification should include this whole notice as is and a description of the changes made.

This software may not be sold.

This software or any modified version of it may be freely used in free programs. The program should include a copy of this whole notice. If you want to use it in a program you sell, contact me

This software comes with absolutely no warranty.