%*************************************************************************
%                  DEFINITIONS POUR LATEX
%*************************************************************************
%
%
%       Format pour Latex, et autres definitions
%

\documentclass[11pt,a4paper,twoside,frenchb]{article}
     \usepackage[latin1]{inputenc}
     \usepackage[T1]{fontenc}
     \usepackage[usenames,dvipsnames]{color}
     \usepackage{graphicx}
     \usepackage{babel}
     \usepackage{html}
%     \usepackage{/free/latex2html/texinputs/html}
     \usepackage{htmllist}
     \usepackage{verbatim}
     \usepackage{/free/latex2html/texinputs/html}
     
\textheight24.0cm
\textwidth16cm
\topmargin-.5cm
\oddsidemargin 0.cm
\evensidemargin 0.cm
\headheight1.cm
\headsep0.cm
\footskip0.7cm
%\footheight2.5cm
\marginparwidth1.2cm
\marginparsep0.3cm
%
\renewcommand{\baselinestretch}{1.2}
%\pretolerance=10000
%\pagestyle{plain}
%\pagestyle{empty}

%---------------------------------------------------------------------------
%
% Fichiers appelant les déclarations utiles au style article en Français.
%
%---------------------------------------------------------------------------    
%\input{/users/mod/piriou/tex/declar/art.tex}
%\input{/users/mod/piriou/tex/declar/com.tex}
%\input{/users/mod/piriou/tex/declar/fra.tex}

%*************************************************************************
%                  DEFINITIONS POUR LE DOCUMENT
%*************************************************************************

\newcommand{\lp}{\left(}
\newcommand{\rp}{\right)}
\newcommand{\lc}{\left[}
\newcommand{\rc}{\right]}
\newcommand{\la}{\left \{ }
\newcommand{\ra}{\right \} }
%
\newcommand{\dr}{\partial}

% 
%*************************************************************************
%                  DOCUMENT
%*************************************************************************

\begin{document}

\title{A Short Beginner-User's Guide for LaTeX2HTML}
\author{Pierre B\'ENARD}
\date{17 June2002}
\maketitle

\tiny file: DOClatex2html.tex

%--------------------------------------------------------------------------------------------------------------------
 

\latex{\small \sf}

\begin{htmlonly}
\normalsize
\end{htmlonly}

\section{Introduction}
\label{sec:intro}

This is a short expectedly "easy to read" document for describing the utilisation of 
"LaTeX2HTML" as a user, and mainly intented for beginners.

\rawhtml
Click <A HREF="../DOClatex2html.ps">here</A> to download the PostScript version of this document
\endrawhtml

\rawhtml
Click <A HREF="../DOClatex2html.ps.tar">here</A> to download the .tar PostScript version of this document
\endrawhtml


\rawhtml 
<HR> 
<HR> 
\endrawhtml

\subsection{Generalities}


\noindent There is a boring "Installer/Administrator/Reference/User's Guide" by Nikos Drakos,
but it is quasi-impossible to read for a normal people, and most of
people are only users (... and normal !).

\noindent This is why a very simple User's Guide for beginners is proposed here, which
purpose it to help beginners to create **SIMPLE** HTML documents.

\noindent To create more complicated documents, the reader should read a more complete material.

\begin{rawhtml}
<HR>
<HR>
\end{rawhtml}


\subsection{Why using LaTeXtoHTML ?}

\large

\noindent Nowadays, our bosses want us to write both PAPER and ELECTRONIC versions of our
various documentations. Usually, our technical and scientific documentaions
are written in LaTeX , which is a good way to handle complicated mathematical formulae.

\noindent Assuming the paper version is written in LaTeX, the software LaTeXtoHTML is a way
to automatically translate the "file.tex" latex source file into a "file.html"
HTML source file, which more or less will reflect the appearance of the paper 
documentation but in a way more suitable for "screen reading".


\noindent The advantage of HTML form of documentations can be easily understood by the example
of the ARPEGE's code documentation (print of Fortran.f90 files vs. GCO's Source Navigator web page):
The interactivity of the documentation makes it much more powerful.
Another advantage is that it is likely to be accessible for more 
(possibly distant) people.


\noindent Both LaTex and HTML source files are ASCII files, and we could imagine to have
both versions maintained separatety, but this would
need to do twice the maintenance of the documentation,
a job that people are usually reluctant
to serioulsly do even only once!

\noindent Using LaTeXtoHTML for producing both PAPER and ELECTRONIC documentation is a way
to have both documentations maintained from a single source code. This source file
still named "file.tex" can be viewed as a latex source code with HTML directives inside it.

\noindent Schematically, the file is processed normally by LaTeX (with HTML directives ignored) 
to produce a paper documentation, and the same file is processed by LaTeXtoHTML
using the specific directives for optimizing the appearance and allowing interactivity
in the HTML page.

\begin{rawhtml}
<HR>
<HR>
\end{rawhtml}

\subsection{Navigation}


\noindent The possibility to "navigate" in the document is achieved by the existence 
of "Hyperlinks", which are areas of the
page where the user can click to access more detail through a link to another part of the
documentation or even to somewhere else.

\bigskip

\noindent Two kind of hyperlinks can be distinguished:

\begin{htmllist}
\htmlitemmark{GreenBall}%
\item[Active text (hypertext):] This is a short part of the text which is "highlighted"
(i.e. underlined and with a color different from the normal text). 

\noindent Cliking on this HyperText activates a link to another location.

\noindent This feature is decribed \hyperref{below}{in section }{}{sec:hyptxt}

\item[Active image:] This is an image where the pointer becomes a "hand" when moved in the image frame.
This is to indicate that the image is active.

\noindent Cliking in this image also activates a link to another location. 

\noindent This feature is decribed \hyperref{below}{in section }{}{sec:hypimg}

\medskip
\noindent Note: There are more complex behaviours like mapping parts of the image to activate
several links according to the location where the user clicks in the frame,
but this advanced feature is not described here, since it should not be useful
for a documentation.

\end{htmllist}

%--------------------------------------------------------------------------------------------------------------------

\section{Requirements}
 
\bigskip
\bigskip

\noindent To run properly LaTeX2HTML while having no undesirable side effects
for running LaTeX (i.e. HTML commands diagnosed as unrecognized commands), you need
to have a LaTeX version which accept to ignore these HTML commands, i.e. a
"modern" enough version of LaTeX.

\noindent You NEED to have at least "Latex2e" version correctly installed and 
of course, you also need to have an access to LaTeX2HTML.

\noindent These are normally on /free/bin/.../...

\noindent In GMAP, to install these, you should ask to 
\htmladdnormallink{Eric Escaliere}{mailto:eric.escaliere@meteo.fr}.

\bigskip
\bigskip

\noindent For the file, a lot of requirements are needed. You have to have the proper
header to be able to include figures, accents, etc... You have to specify a lot
of packages which are to be used to run sucessfully LaTeX2HTML, etc...
We will not enumerate and explain them here.

\noindent Since the number of  package, commands, setting,... definitions is quite long 
to build if you want to have a nice result, the best to start with is to take a
source file with the proper header from a friend of you.

\noindent As an example (or if you have no friends in GMAP),
the source file of this documentation can be downloaded
\htmladdnormallink{(click here to dowload)}{../DOClatex2html.tex}.
This file allows in-lined figures/images and the various features which can be seen
on the screen version.

%--------------------------------------------------------------------------------------------------------------------

\section{Making a (simple) HTML Document}
 
\bigskip
\bigskip

\begin{rawhtml}
<HR>
<HR>
\end{rawhtml}

\subsection{The command to run LaTeX2HTML}

\noindent Here we assume the simplest possible configuration for building a HTML document from
LaTeXtoHTML: We assume a single (and reasonably short) "file.tex" source file.

\noindent The process to create the HTML document is thus:

\begin{htmllist}
\htmlitemmark{GreenBall}%
\item[Run LaTeX:] LaTeX should be run (successfully!) one or two times (according
the presence of cross references or not). This step is mainly in order to check that
the syntax is correct, and for generating the paper version. This is done by:

\begin{verbatim}
latex file.tex
\end{verbatim}

\item[Run LaTeX2HTML:] LaTeX2HTML is then runned to make the HTML page(s).

\noindent This is done by:

\begin{verbatim}
latex2html file.tex
\end{verbatim}

\label{new-dir}

\noindent Running LaTeX2HTML creates a NEW DIRECTORY (with name \verb+file+ where \verb+file.tex+ is the name of
the source file), located below the directory where the source file is.

\noindent The HTML files are created in this new directory.

\noindent If the source file does not content any LaTeX2HTML specific command, the appearance of
the obtained HTML document will be very "basic": The only HTML-like feature will be
the fact that sections, subsections etc... will be accessible by clicking in the
Table of Contents. After that, refinements as the creation of hyperlinks inside 
the test itself must be introduced as specific LaTeX2HTML commands.
\end{htmllist}

\begin{rawhtml}
<HR>
<HR>
\end{rawhtml}

\subsection{Customization of LaTeX2HTML's behaviour}

\noindent The behaviour of LaTeX2HTML for a given document can be customized by copying the
".latex2html-init" file into the same directory as the "file.tex" file and
by modifying its content. This file is originally located in the 
\verb+$LATEX2HTMLDIR+ directory.
The preferences for running LaTeX2HTML will then be taken 
from this version then from "\verb+$HOME+" and from "\verb+$LATEX2HTMLDIR+" 
versions by decreasing order of priority.

\begin{rawhtml}
<HR>
<HR>
\end{rawhtml}


\subsection{Control of the navigation hierarchy (*IMPORTANT*)}

\noindent Here we only discuss about the control of the navigation for the hyperlinks 
automatically generated by LaTeX2HTML (i.e. among the hyperlinks discussed above,
only those which concern the sectionning of the document).

\label{lab:nodes}
\noindent Usually, the document is divided into entities (e.g. chapters, sections, ...)
organised as a hierarchy (or a tree). When running LaTeX2HTML, the HTML version
of the document will be also divided into several files or nodes.
 However, the default behaviour of LaTeX2HTML
is to generate one "HTML page" for each smallest entity of the document.
Physically, each page is put in a node file "\verb+node##.HTML+" where "\verb+##+" is an integer.
This can be VERY UNCOMFORTABLE for the reader if these entities are too short 
or too long. Fortunately, the default behaviour of LaTeX2HTML can be 
modified (customized) to achieve a easily readble documentation.

\noindent The way the Electronic document appears at screen is QUITE IMPORTANT for its
"readability" and this is why this section should be red carefully.


\subsubsection{The two levels of splitting}

\noindent There are in fact two levels of splitting, which can be controlled separately:

\begin{htmllist}
\htmlitemmark{GreenBall}%
\item["Node (or file) Splitting":] The way the total document will be divided in 
single HTML-pages.
\item["link Splitting":] The way information is indexated inside each HTML-page
\end{htmllist}

\noindent Let us explain these two level in more detail now.

\noindent As mentionned above, the default behaviour of 
LaTeX2HTML is to generate a separate file \verb+node.html+ (or "node" or  "HTML-page") 
for each smallest entity of the document. 
The practice shows that an optimal length for a HTML documentation page
is approximately a few paper-pages. Hence if a smallest entity is only 
a few paper-lines long or a hundred paper-pages long, the result 
at screen will be very uncomfortable. In the first case the feeling is of a boring 
documentation for which you have to click twenty time to have an interesting
(but tiny) piece of information. In the second case, you don't need to click too much
but you may become lost inside a non-hierarchised huge page. 

\noindent The ideal situation should then be that each entity of the same level shoud
have approximately the same size, and that the smallest entity should be 
some paper-pages long. But for pre-existing documentation, this is not necessarily
true, and often there are too small entities in the text. 
In this case, the best solution is to customize the behaviour of LaTeX2HTML
in order that it stops the splitting of the document into entities
from a given level of sub-entities.

\noindent This is achieved by the setting the variable \verb+$MAX_SPLIT_DEPTH+ to the 
right value in the "\htmladdnormallink{.latex2html-init}{node2.html#SECTION00022000000000000000}" file.

\normalsize

If this variable is set to 0 or 1 , a single page will be made for the whole "Document".

If set to 2 , a single page per "Part".

If set to 3 , a single page per "Chapter".

If set to 4 , a single page per "Section".

If set to 5 , a single page per "Subsection".

If set to 6 , a single page per "Subsubsection".

If set to 7 , a single page per "Paragraph".

If set to 8 , a single page per "Subparagraph".

\large

\noindent The default value is 8, which most often results in a too much splitted
document. For a documentation which only has no Parts and Chapter, 
but only sections, subsections, etc..., 
the best value should be 4 (for a short documentation of 10-20 paper-pages) 
or 5 (long documentation of 50-100 paper-pages).

\bigskip
\bigskip

\noindent Now, the document is assumed to be splitted in reasonably sized HTML pages.
Each page can now contain sub-entities (e.g., if each page contains a section,
it may also contain several subsection, and many subsubsections...).
LaTeX2HTML then put at the top of each page a list of the sub-entities
of this page, in highlighted text clickable for direct access
inside the page itself.
This list can be viewed as a mini "Table of Content" or "mini ToC" for the current HTML page.

\noindent The deepness to which this "mini ToC" should be displayed
can be specified through the "link-splitting" variable \verb+$MAX_LINK_DEPTH+.

\noindent If this variable is set to 1, the "mini ToC" will show only direct sub-entities, if it
is set to 2 the depth will be 2 and so on.

\noindent The default value is 4, but a smaller value like 1 or 2 is much better for the reader.

%-------------------------------------------------------------------------------------------

 
\section{Conditionality}
\label{sec:cond}
\label{page:cond}

\noindent It can be convenient to have the possibility to distinguish the behaviour
of the source file when processed by LATEX or by HTML.
This can be done by defining specific environments, as:

\medskip

${\tt \backslash begin \la latexonly \ra...\backslash end \la latexonly \ra }$ and 

${\tt \backslash begin \la htmlonly \ra...\backslash end \la htmlonly \ra }$.

\noindent or by commands, as:

\medskip

${\tt \backslash latex \la...\ra}$ and ${\tt \backslash html \la...\ra}$.

\medskip

\noindent {\bf Warning:} This latter commands are only intended for very short arguments (e.g. some words)
inside the brace pairs.


\noindent Here is an example of the syntax for conditional environments:

\rawhtml 
<TABLE border=4 cellpading=10 width=50\%><TR><TD>
\endrawhtml

${\tt \backslash begin \la latexonly \ra }$

\hspace*{1cm} {\tt This will be printed only by LaTeX}

${\tt \backslash end \la latexonly \ra }$ 
\medskip

${\tt \backslash begin \la htmlonly \ra }$

\hspace*{1cm} {\tt This will be printed only by LaTeX2HTML}

${\tt \backslash end \la htmlonly \ra }$ 

\rawhtml 
</TR></TABLE>
\endrawhtml

\noindent Here is an example of the syntax for conditional in-line commands:

\rawhtml 
<TABLE border=4 cellpading=10 width=50\%><TR><TD>
\endrawhtml


${\tt \backslash latex \la \right. }$ {\tt this will be printed only by LaTeX} ${\tt \left. \ra}$ 

${\tt \backslash html \la \right. }$ {\tt this will be printed only by LaTeX2HTML} ${\tt \left. \ra}$ 


\rawhtml 
</TR></TABLE>
\endrawhtml


\bigskip 

\noindent \underline{Warning (BUG):} Even if these two types of conditional environment
seem to be well-behaved for simple commands (like text input), they fail
fro more complex command. For instance if you want to define a different
text-size for screen and paper version, the following sequence does not work:


${\tt \backslash begin \la latexonly \ra }$

\hspace*{1cm} ${\tt \backslash small \;\;\; \backslash sf}$

${\tt \backslash end \la latexonly \ra }$ 
\medskip

${\tt \backslash begin \la htmlonly \ra }$

\hspace*{1cm} ${\tt \backslash large \;\;\; \backslash rm}$

${\tt \backslash end \la htmlonly \ra }$ 


\noindent The "latexonly" part is not taken into account. In the same way, the 
following sequence does not work properly:



${\tt \backslash latex \la \backslash small  \;\;\; \backslash sf\ra}$ 

${\tt \backslash html \la \backslash large \;\;\; \backslash rm \ra}$ 

\noindent The "html" sequence is not taken into account. 
However, the following sequence has been found to work:

${\tt \backslash latex \la \backslash small \;\;\; \backslash sf\ra}$ 

${\tt \backslash begin \la htmlonly \ra }$

\hspace*{1cm} ${\tt \backslash large \;\;\; \backslash rm}$

${\tt \backslash end \la htmlonly \ra }$ 





%--------------------------------------------------------------------------------------------------------------------

\section{Hypertext}
\label{sec:hyptxt}
 
\bigskip
\bigskip

\noindent Here we discuss only the way to include hyperlinks which have an effect
only in the HTML version. The way to include hyperlinks which have two 
different effect when processed by LaTeX and by LaTeX2HTML is described
\hyperref{below}{in section (}{)}{sec-cross}

\noindent Two kind of Hypertext links can be distinguished:

\begin{htmllist}
\htmlitemmark{GreenBall}%
\item["URL links":] These links simply send the reader to another \htmlref{node}{lab:nodes}
       of the current HTML document (internal link), or to another URL address,
        maybe outside of the document (external link).
\item["cross-reference links":] These links send the reader to another place in the text
     of the current document.
\end{htmllist}

\bigskip
\bigskip

\rawhtml 
<HR>
\endrawhtml


\subsection{"URL" links}

\noindent The "URL" hypertext links can be specified in the source document by :

\begin{verbatim}
\htmladdnormallink{text}{URL}
\end{verbatim}


\noindent For an internal link, you just specify the node where to go (e.g. \verb+node2.html+),
and for an external link, you specify its complete URL address.

\begin{htmllist}
\htmlitemmark{GreenBall}%
\item[LATEX:] When processed by LATEX the {\sl text} argument is simply printed normally and the {\sl URL }
argument is ignored.
\item[HTML:] When processed by HTML the {\sl text} argument is simply underlined and the {\sl URL}
argument provides the active link to the corresponding file
\end{htmllist}

\bigskip
\bigskip

\rawhtml 
<HR>
\endrawhtml

\subsection{"cross-reference" links}

\noindent This kind of link is better for referring to inside the current document
since the name of a node can change for a future revised version of the document.
The advantage of a cross-reference link  is to be valid dynamically (even
when then numebring of node changes).
For these links, you must first put a "label" in the text at the place you
want the link to point to:

\normalsize
\verb+ ... some text \label{my_label} and the following ... +
\large

\medskip

\noindent Then a portion of the text must be highlighted and point towards the label \verb+my_label+:

\normalsize
\verb+ ... some other text \htmlref{highlighted_text}{my_label}  more text ... +
\large

%--------------------------------------------------------------------------------------------------------------------

\section{Introducing Images in documents}
\label{sec:hypimg}

\rawhtml 
<HR>
\endrawhtml

\subsection{Basic problem}

\noindent The basic problem with images in document is the following:

(i) LaTeX handles only PostScript files to make figures

(i) HTML is not able to handle PostScript images


\noindent For the moment the only solution to have a figure correctly handled in
paper and electronic documents is to have both version of the figure's file:
\verb+file.ps+ and \verb+file.gif+ . The \verb+.ps+ version will be used by LaTeX to produce
in-lined figures, while the \verb+.gif+ version will be used by
LaTeX2HTML to produce in-lined images
(the way to convert a PostScript image into a gif file will be explained \htmlref{below}{convert}).

\noindent Then we need to have separate commands for LaTeX and for LaTeX2HTML to display the
two different files. This is basically done using the conditional environments,
with the following syntax:

\bigskip

\noindent ${\tt \backslash begin \la latexonly \ra }$\\
${\tt \backslash begin \la figure \lc... \rc \ra }$\\
\hspace*{1cm} ${\tt \backslash includegraphics \la... \ra }$\\
${\tt \backslash end \la figure \lc... \rc \ra }$\\
${\tt \backslash end \la latexonly \ra }$ 
\medskip

\noindent ${\tt \backslash begin \la htmlonly \ra }$\\
\hspace*{1cm} ${\tt e.g.: \backslash htmladdimg \la file.gif \ra }$\\
${\tt \backslash end \la htmlonly \ra }$ \\


\bigskip

\rawhtml 
<HR>
\endrawhtml

\subsection{Various types of HTML images}

\noindent To simplify, three types of images in HTML pages can be distinguished:

\begin{htmllist}
\htmlitemmark{GreenBall}%
\item[inactive image:] images which are inactive
\item[active images:] images which are active
\item[active mapped images:] images which are active by part (each part of the image 
leading to a different link).
\end{htmllist}

\bigskip

\rawhtml 
<HR>
\endrawhtml


\subsection{Including inactive images}

\noindent The strict electronic-equivalent for figures in the paper document are inactive
images.

\noindent Here is the syntax to insert a inactive image in the HTML version:

\verb+\htmladdimg{file.gif}+

\noindent where \verb+gif.gif+ is a \verb+.gif+ image located in the HTML directory
 created under the \verb+.tex+  source file. 
  
\medskip

\noindent {\bf Note:} The path for the LaTeX figure must start from the directory
where the LaTeX source file \verb+file.tex+ is. On the other hand, 
the path for the HTML image must start from the directory created by LaTeX2HTML
under the directory where the LaTeX source file is.

\bigskip

\noindent Here is the behaviour of the above example block when processed by the current
software that have been used to produce the document you are reading:

\begin{latexonly}
\begin{figure}[hbtp]
        \centerline
                {
                \includegraphics
                        [angle=0,
                        width=6.0cm,
                        keepaspectratio=true,
                        clip=true ]
                        {DOClatex2html/fig_GR.eps}
                }
        \caption{A given figure}
        \label{mafig1}
\end{figure}

\end{latexonly}

\begin{htmlonly}
\htmladdimg{fig_GR.gif}
\end{htmlonly}

\bigskip

\rawhtml 
<HR>
\endrawhtml

\subsection{Including active images}

\noindent Active images are NOT PROVIDED specifically by LaTeX2HTML package.

\noindent However, it is possible to include them in the electronic version of the
document since it is always possible to include any HTML specific command
in the source file by the \verb+\rawhtml+ environment:

\begin{verbatim}
\begin{rawhtml}
...
\end{rawhtml}
\end{verbatim}


\noindent This is the command to obtain a clickable (.GIF) Image in the HTML version of the document:

\begin{verbatim}
<a href="target_URL"><img SRC="source_image.gif" LOWSRC="idem.gif" ALT="text" 
BORDER=0 height=297 width=488 align=TEXTTOP></a>
\end{verbatim}

\noindent Note: There is no need to be a HTML syntax expert to find this syntax: The syntax can be retrieved through the page Composer
associated to the Navigator, and then copy-pasted in the source file.

\bigskip

\noindent Here follows (only in HTML version) an image for which the \verb+target_URL+ is a PostScript file (activates GhostView or a download of the file, according
to the action specified in the "preferences" menu of the navigator):

\begin{rawhtml}
<a href="fig_GR.eps"><img SRC="fig_GR.gif" LOWSRC="fig_GR.gif" ALT="image ex" BORDER=0  width=200 align=TEXTTOP></a>
\end{rawhtml}

\bigskip

\noindent Here follows (only in HTML version) an image for which the \verb+target_URL+ is a internal link to another part of the text (namely the top level).

\begin{rawhtml}
<a href="DOClatex2html.html"><img SRC="fig_GR.gif" LOWSRC="fig_GR.gif" ALT="image ex" BORDER=0  width=240 align=TEXTTOP></a>
\end{rawhtml}

\bigskip

\rawhtml 
<HR>
\endrawhtml

\subsection{Including active mapped images}

\noindent This is an advanced feature which is not in the scope of this documentation.
Moreover, this kind of feature has no obvious link with the spirit of a technical
or scientifical documentation, hence it will not be described here;
the reader is referred to Nikos Drakos documentation.

\bigskip

\rawhtml 
<HR>
\endrawhtml

\subsection{File conversion from PostScript to "GIF"}
\label{convert}

\noindent An easy way to achieve the PostScript to GIF conversion is to use \verb+xv+:
Having the figure on the screen at the desired magnification (e.g. by \verb+GhostView+),
run \verb+xv+, then use the "Grab" button to import the image into \verb+GhostView+.
Then you can clip the interesting part with the "Crop" button, and save to a GIF file
with the "Save" button (don't forget to move the GIF file at the right place after).


%--------------------------------------------------------------------------------------------------------------------
 
\section{Cross References}
\label{sec-cross}
 

LaTeX allows for two types of cross-references:

\begin{htmllist}
\htmlitemmark{GreenBall}%
\item["normal" references:] These references are relative to equations, figures, sections,
 figures, tables. These features are indexated by a number (possibly of the form X.X).
\item["page" references:] These references are relative to the page numbers of the document.
\end{htmllist}

\begin{rawhtml}
<HR>
\end{rawhtml}

\subsection{"normal" References}

\noindent A single command:

\verb+\hyperref{HTML-text}{LaTeX-text}{post-LaTex-text}{label}+ 

\noindent allows to handle the treatment of "normal" references 
(equation, figures, sections, figures, tables...) by both
LATEX and HTML:

\bigskip

\noindent LaTeX will handle the label in a normal way as \verb+\ref{label}+, which is used
for labelling and numbering equations, figures etc... , and this reference will be surrounded
by \verb+\ref{LaTeX-text}+ and \verb+\ref{post-LaTeX-text}+ character strings.

\noindent HTML will handle the label by highlighting the character string  \verb+\ref{HTML-text}+
the hyperlink will lead the reader to the place where \verb+label+ is defined.


\bigskip
\bigskip

\noindent {\bf WARNING}: Apparently, this command does not support the presence of "underscore" in the
label name. This is a bug of LaTeX2HTML, the "underscore" character should then be replaced by "minus" or "column"
for labelling.

\bigskip
\bigskip
  
\normalsize

\rawhtml 
<TABLE border=4 cellpading=10 width=50\%><TR><TD>
\endrawhtml

\noindent {\bf Example with an equation} :

\noindent  Here is the continuity equation (which label is assumed to be \verb+eq-cont+):

\begin{equation}
\frac{dX}{dt} = 3 X + 2
\label{eq-cont}
\end{equation}

\noindent In the source file, the following command:

 \verb+\hyperref{continuity equation}{continuity equation (}{)}{eq-cont}+
 
\noindent will result in the following appearance:


with LaTeX: continuity equation (1), ...

with HTML : \underline{continuity equation}, ...

\bigskip
\noindent Here is the effective result of the command with the software that you are using:

\hyperref{continuity equation}{continuity equation (}{)}{eq-cont}

\rawhtml 
</TR></TABLE>
\endrawhtml
  
\rawhtml 
<TABLE border=4 cellpading=10 width=50\%><TR><TD>
\endrawhtml

\noindent {\bf Example with a section }:


\noindent The following link goes to section "Conditionality"  in HTML version, and refers to the same section
in the paper version: 

\hyperref{Conditionality}{conditionality (cf. section}{)}{sec:cond}
\bigskip
\bigskip

\rawhtml 
</TR></TABLE>
\endrawhtml

\large

\rawhtml 
<HR>
\endrawhtml

\subsection{"page" References}

The case of page references is quite particular since HTML page are not supposed to be numbered.
A reference like "see p. 42" in the paper documentation should then be avoided in general.
When such a page reference is necessary it would rather appear as "see above p.42".
In the electronic version, the word "above" would be highlighted and "p.42" would not appear
in the HTML page. The user just have to click on "above" to be linked to the right place.


\noindent {\bf WARNING}: Apparently, the command \verb+\hyperref+ does not support the following syntax:

\verb+\hyperref[page]{HTML-text}{LaTeX-text}{post-LaTex-text}{label}+,

\noindent unlike described in the reference documentation. However, the same result can 
easily be achieved with a double (conditional) command as follow:

\verb+\htmlref{see above}{page:cond} \latex{see above, p.~\pageref{sec:cond}} +
 
\noindent This command writes "see above" and put a link to the concerned place in the text
when processed with LaTeX2HTML. When processed with LaTeX
skip to the specific LaTeX command to print "see above, p. xx".

\bigskip
\bigskip

  
\normalsize


\rawhtml 
<TABLE border=4 cellpading=10 width=50\%><TR><TD>
\endrawhtml

\noindent {\bf Example with a page }:


\noindent The following command creates a link which goes to page where
"Conditionality" section is,  when processed by HTML; 
and refers to the true paper-number of this same page when processed by LaTeX :

\htmlref{Conditionality}{sec:cond} \latex{(cf. page~\pageref{sec:cond})} 

\rawhtml 
</TR></TABLE>
\endrawhtml

\large

%--------------------------------------------------------------------------------------------------------------------
 
\section{Transportability of the document}
\label{sec-trans}
  
\noindent Usually, the documentation source file will be prepared and 
maintained in a directory under the author's \verb+$HOME+ directory, while 
the HTML version of the documentation (i.e. all the \verb+files.html"+ etc...)
will be hosted at any other place, possibly on another machine.

\noindent The transport of the HTML document will be made by copying the files
 from the origin place to the new place on the new machine.

\noindent In this respect, it is important to make sure that the paths indicated to define the links
remain valid at the new location.

\noindent This will be the case if RELATIVE paths are exclusively used to define these
links. We saw above that HTML starting from a source file \verb+file.tex"+,
creates a directory \verb+file"+ at the level immediately under. 
This directory will be referred to as "HTML document directory".

\noindent The simplest way to insure transportability is to put all the information 
concerning the HTML document in this "HTML document directory", and to
use for the links only the name of the files without any path (since 
they are physically in the same directory).

\begin{rawhtml}
<HR>
\end{rawhtml}
  

\noindent If a more subtle architecture is planned (e.g. creation of a sub-directory \verb+figs+
for the figures, or so), then the links relative to the figures should have the form
\verb+figs/figureXX.html+ (symmetrically, directories at an higher level can be accessed by the 
relative path syntax "..").

\noindent If a directory architecture is used instead of the simpler
architecture with only one level, the transport of the document would
obviously have to respect the directory architecture.


%--------------------------------------------------------------------------------------------------------------------
 
\section{Printing quality - Postcript Downloading}
\label{sec-print}

\noindent LaTeX2HTML produces a ".gif" image for each mathematical formula and even
for the smallest expression printed in math-mode. This gives an acceptable result at screen, but
have a very poor appearance when the HTML page is directly printed from the navigator
(i.e. using the "Print" button of the navigator).
The math-text is fuzzy in the obtained PostScript version. This can be more or less optimized
but the results on the paper are always far to be perfect.

\noindent Hence it is HIGHLY ADVISED, as a deontology rule,
to propose (e.g. in the introduction or at the top of the document) a way to download the true 
PostScript (paper) version of the document (at least for technical and scientific documentations).
The interested user can then download and obtain a high quality print.


\subsection{How to make the document down-loadable?}

\noindent First you should copy the PostScript file of the document (obtained by LaTeX),
to the HTML document directory \htmlref{(see above)}{new-dir} which is created when running 
LaTeX2HTML.

\noindent Then you should create an hypertext link to this file. 
This can be done by the following syntax:

\begin{verbatim}
\rawhtml
Click <A HREF="document.ps">here</A> to download the 
PostScript version of the document
\endrawhtml
\end{verbatim}

\noindent where \verb+document.ps+ is the PostScript version of the document.

\noindent NOTE: The problem is that some users have configurated their Navigator in such
a way that this command do not invoke the file transfer, but a visualisation tool such as
GhostView. The hypertext link thus do not have the expected behaviour for the user.
Of course, the visualized file can always be saved from the vizualisation tool, but
this is an indirect method which is not very satisfactory.

An easy way to escape this problem is to transform the dowloadable document  into
a ".tar" file (by \verb+tar -cf file.ps.tar file.ps+). For \verb+.tar+ files, the normal
behaviour of any normal Navigator should be do really activate a download dialog box
as expected from the hypertext link. The syntax for the hypertext link with this ".tar" 
file should then be: 

\begin{verbatim}
\rawhtml
Click <A HREF="document.ps.tar">here</A> to download the  
.tar PostScript version of the document
\endrawhtml
\end{verbatim}

\noindent If somebody has a better solution to this problem, please let me know.

\noindent The effect of the two above commands can be seen in the \htmlref{introduction}{sec:intro} 
of this document (for the HTML version only, of course).


%--------------------------------------------------------------------------------------------------------------------
\section{Fancy things for screen version:}

\noindent The aspect of the document can be modified to
be "more beautiful" when processed by LaTeX2HTML and displayed at screen.
Here follows a short list of the simplest things which can be done
to improve the appearance at screen.

\bigskip

\noindent {\bf Lists} 

\noindent The item marks for a itemized list can be specified in a more graphic 
way than in the paper version. Some basic marks can be accessed directly by their
mnemonic name, but more generally, any GIF image can  constitute an item mark.
To use this facility, you must specify \verb+\usepackage{htmllist}+ in the header
of your source file.
The mnemonics for default item marks are like {\sl Color}{\tt Ball}, where {\sl Color}
is in {\tt Blue, Red, Green, Orange, Pink, Purple, White, Yellow}

\noindent The syntax for these lists is:

\begin{verbatim}
\begin{htmllist}
\htmlitemmark{GreenBall}
\item[Item 1:] Text of Item 1 
\item[Item 2:] Text of Item 2
\end{htmllist}
\end{verbatim}

\bigskip

\noindent Here is the result with the software you use:

\begin{htmllist}
\htmlitemmark{GreenBall}
\item[Item 1:] Text of Item 1 
\item[Item 2:] Text of Item 2
\end{htmllist}

\noindent In the paper version, this is a normal list, while in the
electronic version, this is a list with green balls.

\bigskip
\bigskip


\noindent {\bf rules} 

\noindent It is possible to insert horizontal rules in the HTML document by:

\begin{verbatim}
\rawhtml 
<HR>
\endrawhtml
\end{verbatim}

\noindent In the paper version, there is nothing.

\bigskip
\bigskip

\noindent {\bf frames} 

\noindent It is possible to include some text in a frame in the HTML document by:

\begin{verbatim}
\rawhtml 
<TABLE border=4 cellpadding=10 width=50\%><TR><TD>
\endrawhtml

The text to enclose in the frame ...

\rawhtml 
</TR></TABLE>
\endrawhtml
\end{verbatim}

\noindent This generates a Table with only one row and only one cell.
The parameters \verb+border+ and \verb+width+ are tunable to modify the visual aspect.

\noindent When processed by LaTeX the text enclosed will appear normally since
the raw HTML directives are ignored by LaTeX.

\begin{htmlonly}
\noindent Here is an example (on screen only) of framed text:

\rawhtml 
<TABLE border=1 cellpadding=0 width=50\%><TR><TD>
\endrawhtml

Some framed text, with: border=1 cellpadding=0

\rawhtml 
</TR></TABLE>
\endrawhtml

\rawhtml 
<TABLE border=4 cellpadding=10 width=50\%><TR><TD>
\endrawhtml

Some framed text with: border=4 cellpadding=10

\rawhtml 
</TR></TABLE>
\endrawhtml

\rawhtml 
</TR></TABLE>
\endrawhtml
\rawhtml 
<TABLE border=4 cellpadding=30 width=50\%><TR><TD>
\endrawhtml

Some framed text with: border=4 cellpadding=30

\rawhtml 
</TR></TABLE>
\endrawhtml
\end{htmlonly}
%--------------------------------------------------------------------------------------------------------------------
\section{Efficiency aspects:}


\noindent The user could be frightened by the snail slowness of LaTeX2HTML to
produce a reasonably sized documentation (let's say 50-100 pages).
If the document is quite complex with many mathematical expressions
and formulae, a running time of about ONE HOUR can be expected...

\LARGE
\noindent ** HOWEVER **
\large

\noindent This is only for the FIRST run of LaTeX2HTML.

\noindent In effect, the main part of the above mentionned hour is spent to produce the
GIF version of the mathematical expressions and formulae (2 or 3 seconds for each).
But once created, the software put them into files that are re-used for next 
executions. The translation is then MUCH more fast from the second execution
(typically passing from one hour to five minutes).

\noindent The way this is done is quite mysterious, but this seems to be quite
cleanly done: the existing GIF images are re-used without confusion when modifying
not only the text, but also the sectionning, and even the number and content
of the mathematical expressions. If a single mathematical formula or expression is added,
a single GIF image generation will have to be done.

%--------------------------------------------------------------------------------------------------------------------
\section{Conclusions and Documentations:}

\noindent The LaTeX2HTML translator appears to be a quite efficient tool and allows
to obtain a satisfactory HTML version of scientific/technical documents without
large efforts. The main points to obtain a satisfactory HTML documents from an existing LaTeX 
document are the following:

\begin{list}{}{}

\item - Properly install LaTeX.2e and LaTeX2HTML
\item - Add the .latex2html-init file in the document directory and customize the splitting
   of the document.
\item - Take an existing document source as this one to have a proper header.
\item - Maybe replace some \verb+\ref+ by \verb+\hyperref+ from places to places.
\item - Try to make a effort to avoid page-references. If there are some, use the
 conditional \verb+\pageref+ and \verb+\htmlref+ command combinations.
\item - Make a GIF version of each figure by \verb+xv+, and add a conditional
 command to implement the GIF image in the HTML document
\end{list}

\noindent and this is enough! A clean HTML document can then be obtained very rapidly.

\bigskip
\bigskip

\noindent The Reference documentation by Nikos Drakos can be found at:


\htmladdnormallink{http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual}
                  {http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual}
                  
\medskip
                 
\noindent Here is another reference (which does not work very good):


\htmladdnormallink{http://www-math.mpce.mq.edu.au/texdev/LaTeX2HTML/docs/manual}
                  {http://www-math.mpce.mq.edu.au/texdev/LaTeX2HTML/docs/manual}

\medskip


\end{document} 
 
  
