\documentclass[12pt]{article}
\usepackage{lmac}
\usepackage{alltt}
\usepackage{html}
\usepackage{tcode}

\mytwoheads
\dateheadtrue
\tolerance=500
\textwidth=6.5in
\textheight=9.5in
\parskip = 3pt

\newif\ifnotes\notestrue
% \notesfalse             %%  Uncomment this line to hide footnotes.  <----
%
\def\boxnote#1#2{\ifnotes\fbox{\footnote{\ }}\ \footnotetext{ From #1: #2}\fi}
\def\pierre#1{\boxnote{Pierre}{#1}}
\def\hpierre#1{}
\def\richard#1{\boxnote{Richard}{#1}}
\def\hrichard#1{}
\def\eric#1{\boxnote{\'Eric}{#1}}
\def\heric#1{}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}

\begin{titlepage}

\null\vfill
\begin {center}
{\Large\bf TCode} \\[20pt] 
{\Large\bf User Guide } \\[20pt] 
{\Large\bf Tools for documenting Java programs in \LaTeX }\\[15pt] 
 Version: \today \\
\vfill\vfill
\end {center}

\vfill
This document describes facilities that help writing Java classes,
together with detailed documentation of their application programming 
interface (API), in a single \LaTeX{} file.  
The \LaTeX{} package {\tt tcode} offers special commands and
environments for typesetting API documentation and user guides.
It permits one to display certain parts of the code (e.g., method headers),
hide others (e.g., method bodies and private variables), 
and explain the methods, variables, etc., in a uniform format.
Although it is targeted to that language,
it works not only for Java, but also for other programming languages
such as C, C++, etc.
\LaTeX\ will produce the documentation as a {\tt .dvi}, {\tt .ps}, 
or {\tt .pdf} file.

A Perl script called \emph{texjava} produces a 
{\tt .java} file by extracting the code form the {\tt .tex} file.
With the help of \latextohtml{}, \emph{texjava} also transforms some 
of the documentation into Javadoc
format, so that the \emph{javadoc} program can later produce HTML
documentation from the {\tt .java} file.
Another Perl script called \emph{javatex} does the reverse transformation,
recovering the {\tt .tex} file from the {\tt .java} file.
\vfill
\end{titlepage}

%\pagenumbering{roman}
%\tableofcontents
%\pagenumbering{arabic}

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

\emph{Javadoc} is the standard Java tool for generating API documentation
\cite{iFLA99a}.
Its output is in HTML format.
However, HTML is very limited on certain aspects such as 
displaying mathematical expressions, complex tables, etc.
Good modern typesetting systems such as \TeX{} and \LaTeX{} offer
much better quality, flexibility, and precision than HTML
for producing detailed and nice-looking documentation \cite{iGOO99a}.
\LaTeX{} is certainly a tool of choice for API documentation of 
mathematically-oriented software.  On the other hand, for Java libraries,
standard online HTML documentation based on Javadoc is almost a necessity.

With the tools described here, one can program a Java class and 
document its API in great detail, in a single \LaTeX{} file.
The \LaTeX{} program produces a nicely-typeset version of the 
documentation, while a Perl script called \emph{texjava}, helped by
\latextohtml{} \cite{iGOO99a}, produces a {\tt .java} file, which can
be compiled into a {\tt .class} file and can also be used by javadoc 
to produce HTML documentation.
The {\tt .java} file produced by \emph{texjava} can be retransformed 
(to a certain extent) into a \LaTeX{} file by the Perl script \emph{javatex}.

The \LaTeX{} package {\tt tcode} defines special commands and
environments for typesetting API documentation in a uniform format, 
and selectively displaying or hiding (from the API documentation or 
user's guide) pieces of Java code.
This \LaTeX{} class file can also be used for 
other programming languages such as C, C++, etc.
In this document, we assume that the target language is Java.

These tools are rudimentary and much simpler, for example, than the 
CWEB system of documentation \cite{iKNU94a}, also based on \TeX{}.

Section~\ref{sec:layout} explains how \LaTeX{} files should be organized
for using these tools, describes the main commands, and give an example.
Section~\ref{sec:texjava} shows how to run \emph{texjava}.
Sections~\ref{sec:javatex} and \ref{sec:javatex2} 
tell about \emph{javatex} and how to run it.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Layout of the \LaTeX{} files}
\label{sec:layout}

A \LaTeX{} document using the {\tt tcode} \LaTeX{} package to describe
a Java package (or set of packages) normally has a single master file,
with several secondary {\tt .tex} files, which are loaded via 
\verb!\include{ }! commands in the master file.
There should be one secondary {\tt .tex} file for each {\tt .java} 
file that we want to have (typically, this is one file for each Java 
class or interface in the package).  The master file may contain 
other material and include additional files as well.
\LaTeX{} or pdf\LaTeX{} will process the master file to produce the 
detailed documentation, which will usually end up as a {\tt .pdf} file.
The {\tt .tex} files that implement Java classes are transformed one by one 
into the corresponding {\tt .java} files (or {\tt .c}, {\tt .cpp}, etc., 
in the case of other languages) by the Perl script {\tt texjava.pl}
helped by the \latextohtml{} program, which basically extracts the code 
and formats additional information for \emph{javadoc}.  Since the
script can process only one {\tt .tex} file at a time, one may
create a Makefile
% or an Ant project using the {\tt Texjava} task
to automate the generation process
when dealing with many files.

%%%%%%%%%%%%  tcode package
\paragraph*{The {\tt tcode} package.}
To use the commands of the {\tt tcode} \LaTeX{} package, this one 
must be imported via the command

\verb!\usepackage{tcode}!

\noindent
This command will locate and load {\tt tcode.sty}, so this file must be 
accessible in a directory pointed to by the {\tt TEXINPUTS} environment 
variable.  The {\tt tcode} package requires the {\tt html} and {\tt alltt}
packages which should also be locatable through the {\tt TEXINPUTS} 
environment variable.

%%%%%%%%%%%%%%  code
\paragraph*{The code environment.}
The basic construct for identifying programming code in the \LaTeX{} 
files is the {\tt code} environment.
Everything between \verb!\begin{code}! and \verb!\end{code}!,
with the exception of \LaTeX{} commands, 
is displayed in special verbatim mode, with a typewriter font, by \LaTeX{}
and is treated as Java code (copied into the {\tt .java} file) 
by \emph{texjava}.  The Perl script disallows nesting of 
{\tt code} environments.  The
\verb!\end{code}! command should always be placed alone at the beginning of a line.
A document is therefore composed of an alternance of 
text blocks and code blocks, starting and ending with a text block.

%% longcode
The contents of a {\tt code} environment is actually treated as a ``box''
by \LaTeX{}, which means that 
% it cannot be split on two pages (just like a figure or table). 
all the code it contains will appear on the same document page.  This
is what we expect when documenting methods, because we wish
a multi-line signature not to span on two pages.
However, if the code is too long to fit 
in the page, \LaTeX{} will issue an ``overfull vbox'' warning and
the code will not appear entirely on the resulting document.  
The {\tt longcode} environment is convenient for displaying long blocks
of code; it behaves just as the {\tt code} environment, 
except that it allows the code to span over two or more pages.

%% smallcode

%% vcode
There are situations where one would like to have some code displayed
in the documentation, but not have it in the {\tt .java} file
(e.g., when giving programming examples in the documentation).
The {\tt vcode} and {\tt longvcode} environments do that: 
\LaTeX{} treats them just like the {\tt code} and {\tt longcode}
environments, but \emph{texjava} does not copy the code into the {\tt .java} file.
However, it will appear as typed text in the HTML documentation.

The following character strings should never appear inside programming
code (e.g., in a litteral string or in a comment), because they will be
interpreted as active \LaTeX{} commands:
\verb!\hide!, \verb!\endhide!, \verb!\code!, \verb!\endcode!, 
\verb!\begin{hide}!, \verb!\end{hide}!, \verb!\begin{code}!, 
\verb!\end{code}!.  If one needs to use such a string, one must
separate it in two parts, as in the following example:
{\tt String s = "\bs\bs" + "begin{code}";}.


%%%%%%%%%%%%% hide
\paragraph*{The hide environment.}
Normally, we do not want all the code to be displayed in the API 
documentation.  For example, the private fields, methods, and classes,
as well as the method implementations, should be hidden.
The {\tt hide} environment permits one to easily hide 
parts of the code and text from the \LaTeX{} documentation:
Everything between \verb!\begin{hide}! and \verb!\end{hide}!  
is simply not shown in the document produced by \LaTeX{}.
This environment can be applied to a block of text as well as to a block
of code (i.e., inside the code environment).
Nesting is allowed, but not inside the code environment.
For example, one may place a whole set of methods together with their
descriptions in a {\tt hide} environment, to remove them from the 
documentation, while part of the code of each method may already be
in a {\tt hide} environment (inside the {\tt code} environment).
In this case, the outer {\tt hide} environment must begin and end 
\emph{outside} any {\tt code} environment.

The {\tt hide} environment has no effect on the code extracted
by \emph{texjava} in the sense that all hidden code goes to the 
{\tt .java} file anyway.  
However, the hidden documentation will not appear in the HTML conversion 
produced by Javadoc.

%%%%%%%%%%%% \hidefalse
\paragraph*{No hiding.}
In case one wishes a documentation that contains all the code,
including the method implementations and other private material,
one can simply turn OFF the hiding mechanism of the {\tt hide} 
environment with the command \verb!\hidefalse!.
It can be turned ON again with the command \verb!\hidetrue!.
However, turning the hide mechanism OFF will get \LaTeX\ to
parse hidden contents to display it.  It will then react to backslashes
in the hidden code and try to interpret control sequences.
For example, if some hidden code contains

{\tt System.out.println ("This is a string,\bs nAnd another one.");}

\noindent
it must remain hidden
otherwise \LaTeX\ will complain about the invalid control sequence {\tt\bs n}.

%%%%%%%%%%%% \detailedtrue
\paragraph*{Detailed contents.}
The {\tt detailed} environment is convenient for producing two versions
of the documentation, one more detailed than the other.
It comes with a switch that can be turned ON by the command
{\tt\bs detailedtrue} and turned OFF by the command {\tt\bs detailedfalse}.
Everything inside the {\tt detailed} environment is ignored by \LaTeX{}
when the switch is turned OFF, otherwise it is included normally.
By default, the switch is turned ON.  When creating the HTML
version, the {\tt detailed} environment is ignored, meaning
that the HTML document will never be detailed.


%%%%%%%%%%%%%
\paragraph*{Restrictions due to \latextohtml.}

The \emph{texjava} script calls the \latextohtml{} utility to convert
the documentation in the {\tt .tex} file to HTML format in the {\tt .java}
file.  It generates HTML 4.0 code using Unicode for mathematical symbols.
This utility processes standard \LaTeX{} commands,
but not user-defined commands/macros and commands/macros 
found in external packages.  
Adding support for new packages implies writing Perl code intended
for processing the different commands provided by these packages
\cite{iGOO99a}.
This operation is complex and requires a good understanding of the
\latextohtml{} conversion process (which is yet undocumented at the time
of this writing).

The contents intended for HTML conversion should therefore be as simple as
possible and should contain only standard \LaTeX{} commands and environments.
Unknown environments and mathematics are translated to images using \LaTeX{}
(called by \latextohtml{}).
However, image creation is time consuming and should be avoided by
restricting usage of the math mode and complex environments to 
\emph{\LaTeX-only} subblocks (see below).  
Sometimes, images may mysteriously appear with a gray background.  
If \LaTeX{} generates an error when making an image, 
it will skip it, \latextohtml{} will not notice that, and 
subsequent images may have the wrong number.
The {\tt equation} and {\tt eqnarray} environments are converted 
to their star forms because problems arise with equation numbers.
The {\tt ref} and {\tt cite} commands are also ignored because reference
collecting accross several independent runs of \latextohtml{} causes problems.

Except for the {\tt hide} environment, no other environment should 
span more than one documentation block, i.e., 
should not contain a {\tt code} environment.
% each environment must begin and end in the same text block.  
Departure from that rule could prevent \latextohtml{} from writing 
the markers separating the blocks (i.e., the fields and methods), 
and empty documentation blocks 
could then appear for subsequent fields and methods.
% In the interest of speed, 
The script calls \latextohtml{} only once for the \LaTeX\ file given to it,
%%  only for the master file and not for each {\tt .tex} file?  No. 
so any modification of the \LaTeX\ parameters in one text block
could have an impact on the subsequent blocks.

%%%%%%%%%%%%%
\paragraph*{{\LaTeX-only} and {HTML-only} parts.}

Certain parts of the {\tt .tex} files can be intended only for \LaTeX{},
others only for the HTML file.
This can be specified by the usual commands and environments 
available in the {\tt html} package (e.g., the {\tt latexonly},
{\tt htmlonly}, and {\tt rawhtml} environments).

Everything inside a {\tt latexonly} environment is ignored by \latextohtml{}.
This is a good place for complex mathematical expressions and tables,
for example.
On the other hand, everything inside a {\tt htmlonly} or {\tt rawhtml}
environment is ignored by \LaTeX{}.
Material inside a {\tt rawhtml} environment is assumed to be HTML code,
which is copied directly to the {\tt .java} file and eventually the 
{\tt .html} file, whereas material inside the {\tt htmlonly} environment
is translated into HTML by \latextohtml{}.


%%%%%%%%%%%%%  \defclass
\paragraph*{Header of a class or module.}
The command \verb!\defclass{!\emph{classname}\verb!}! 
can be used to start the documentation of a Java class or interface.
The command places its argument on a line by itself, centered, 
in a large font.  It also adds a corresponding entry to the table of
contents and modifies the page headings to contain the class name.
The command \verb!\defmodule{!\emph{name}\verb!}! 
has exactly the same effect.

The first block of text is considered as a class or file documentation 
block.  In the {\tt .java} file, it will be inserted as a 
doc comment for \emph{javadoc}, at the beginning of the class definition.
For this reason, the first block of code processed by \emph{texjava} 
must contain the Java class definition.

%%%%%%%%%%%%%
\paragraph*{Subsequent blocks of code and text.}
After the first block of code (i.e., {\tt code} or {\tt longcode}
environment), there is an alternance of a block of text, a block of code,
a block of text, etc.  For each such block of code, the text that follows
it immediately is assumed to be its corresponding \LaTeX{} documentation.
Therefore, \emph{texjava} will insert this text as a (javadoc) 
\emph{doc comment} for the last field or method appearing in this block 
of code (and not in a {\tt hide} environment).

When a class has many documented methods, it may be convenient to
partition them into different groups in the \LaTeX{} documentation,
with a descriptive header above each group.
The command \verb!\guisec{!\emph{header}\verb!}! outputs such a header,
centered horizontally, with horizontal lines on each side.
It should not be placed inside a {\tt code} environment and should 
always be alone in its own paragraph.
A text block that contains this command will be splitted in two parts.
The contents preceeding the section will be inserted as usual whereas
the sectioning command and all the following contents will be
inserted \emph{after} the previous code block.
With the \verb!\unmoved! command, one can achieve the
same effect of a sectioning command without displaying anything.
Note that \emph{javadoc} will always ignore this
\verb!\guisec! and any other sectioning commands,
so it cannot be used to regroup class 
members in the HTML documentation.


%%%%%%%%%%%%% tab, tabb, tabbb
\paragraph*{Indenting documentation.}
The environments {\tt tab}, {\tt tabb}, and {\tt tabbb}
have been defined to indent the documentation and put it in a smaller font.
These environments are normally used to describe fields and methods,
they are ignored by \latextohtml{},
and produce the following results:

\begin{tab}
This is a text indented with {\tt tab}.
\end{tab}

\begin{tabb}
This text is more indented because it is in a {\tt tabb} environment.
\end{tabb}

\begin{tabbb}
This text is still more indented because it is in a {\tt tabbb}
environment.
\end{tabbb}


%%%%%%%%%%%%% Doc-comment tags
\paragraph*{Doc-comment tags for javadoc.}
%
The following \LaTeX{} commands are mapped  by \emph{texjava} 
to the corresponding \emph{javadoc} doc-comment tags 
% (obtained by replacing the character ``\verb!\!'' by ``\verb!@!''), 
which are used to encode specific information about classes, 
fields, methods, etc. (see \cite[chapter 7]{iFLA99a}).
These doc comments will also appear in the \LaTeX{} documentation.
For doc comments that are to appear only in the java and HTML files,
one can use the \emph{javadoc} tags directly
(provided that \emph{texjava} is called with the {\tt -nosavelatex} option).

The \LaTeX{} commands \verb!\param!, \verb!\return!, etc.,
are mapped to the doc-comment tags \verb!@param!, \verb!@return!, etc.
These commands should be placed at the end of the method documentation,
in the same order as they are described below.
% \LaTeX{} will not reorder them and \emph{javadoc} will place them at
% the end of the documentation for each method.
The available commands and their descriptions are:

\noindent
\verb!\param{!\emph{param-name}\verb!}{!\emph{description}\verb!}!

\begin{tab}
Gives a description for the parameter \emph{param-name} of the current
method.  This parameter name must be a single word whereas the description
is usually a short sentence.  Such a description should appear for every 
method parameter.
\end{tab}

\noindent
\verb!\return{!\emph{description}\verb!}!

\begin{tab}
Describes, in one or more sentences, what is returned by the current method.
This should appear for every method returning values.
\end{tab}

\noindent
\verb!\exception{!\emph{class-name}\verb!}{!\emph{description}\verb!}!

\begin{tab}
Gives the class name of an exception raised by Java when the situation
described by the sentence in the second argument occurs.
\end{tab}

\noindent
\verb!\class{!\emph{class-name}\verb!}!

\begin{tab}
Indicates the name of a class.  This is formatted in typed text
in the \LaTeX\ document and converted to
an hyperlink in the HTML document.

Example: \verb!See class \class{GofStat} for more information!\\
 \verb!Use \class{java.util.List} to store the data.!
\end{tab}

\noindent
\verb!\externalclass{!\emph{package}\verb!}{!\emph{class-name}\verb!}!

\begin{tab}
Indicates the fully qualified name of a class.  This is formatted in typed text
in the \LaTeX\ document, and converted to
an hyperlink in the HTML document.
This macro can be useful if one does not want the fully
qualified package name to appear in the \LaTeX\ and HTML document
whereas it is sometimes necessary for Javadoc to hyperlink to the class.
If one wants to have the full package name, he can write
the full qualified name as the argument of the {\tt class} command.

Example: \verb!The \externalclass{umontreal.iro.lecuyer.util}{Num}! will
  show {\tt Num} as a label whereas
  \verb!\externalclass{umontreal.iro.lecuyer}{util.Num}! will show {\tt util.Num}.
\end{tab}

\noindent
\verb!\method{!\emph{method-name}\verb!}{!\emph{signature}\verb!}!

\begin{tab}
Indicates the name of a method in the current class.
This is formatted in typed text
in the \LaTeX\ document, and
converted to an hyperlink in HTML.
If the signature is empty, Javadoc will link to the first method with
that name.  The signature will never be shown in the link labels.
If one wants to show the signatures, he must write it in parentheses
after the method name.
One can also use \verb!\method! and the following \verb!\externalmethod!
to link to fields.  In this case, the signature argument will be empty.

Examples: \verb!\method{density}{}! and \verb!\method{density}{double}!
  will generate the {\tt density} label
  whereas \verb!\method{density(double)}{}! will generate {\tt density(double)}.
\end{tab}

\noindent
\verb!\externalmethod{!\emph{package}\verb!}{!\emph{class-name}\verb!}{!\emph{method-name}\verb!}{!\emph{signature}\verb!}!

\begin{tab}
Indicates the name of a method in another class.
This is formatted in typed text
in the \LaTeX\ document, and
converted to an hyperlink in HTML.
The package name, class name and the signature will not appear in the label name.

Example: \verb!\externalmethod{umontreal.iro.lecuyer.gof}{GofStat}{andersonDarling}{}!
  will typeset {\tt andersonDarling}
\end{tab}

\noindent
\verb!\clsexternalmethod{!\emph{package}\verb!}{!\emph{class-name}\verb!}{!\emph{method-name}\verb!}{!\emph{signature}\verb!}!

\begin{tab}
This is the same as \verb!\externalmethod! except that the class name
is prepended.  Since this macro can generate long strings in typed text
which can easily result in overful boxes, a discretionary hyphen
is added between class name and method name.

Example:\\
 \verb!\clsexternalmethod{umontreal.iro.lecuyer.gof}{GofStat}{andersonDarling}{}!
  will be formated {\tt GofStat.andersonDarling}\\
\verb!\clsexternalmethod{umontreal.iro.lecuyer}{gof.GofStat}{andersonDarling}{}!
  will format {\tt gof.GofStat.andersonDarling}
\end{tab}

%%%%%%%%%%%%%
\paragraph*{An example.}

\begin{verbatim}
\defclass{Complex}

This class allows one to work with complex numbers of
the form $a + bi$, where $a$ is the \emph{real} part of
the number, \emph{b} is the imaginary part and
$i=\sqrt{-1}$.

\bigskip\hrule\bigskip

\begin{code}

public class Complex\begin{hide} {
   private double realPart;
   private double imagPart;\end{hide}

   public Complex (double realPart, double imagPart)\begin{hide} {
      this.realPart = realPart;
      this.imagPart = imagPart;
   }\end{hide}
\end{code}
\begin{tabb}  Constructs a new {\tt Complex} number.
\param{realPart}{The real part corresponding to $a$}
\param{imagPart}{The imaginary part corresponding to $b$}
\end{tabb}
\begin{code}

   public Complex add (Complex c)\begin{hide} {
      realPart += c.realPart;
      imagPart += c.realPart;
      return this;
   }\end{hide}
\end{code}
\begin{tabb}  Adds two complex numbers.
  \param{c}{The complex number to add to this one.}
  \return{This object, allowing to perform more than one operation
    on a single line of code.}
\end{tabb}
\begin{code}

   // other methods...

   public String toString()\begin{hide} {
      return "(" + realPart + " + " + imagPart + "i)";
   }
}\end{hide}
\end{code}
\begin{tabb}   Converts the number to a {\tt String} of
  the form {\tt a + bi}.
\end{tabb}
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Running Texjava}
\label{sec:texjava}

The Perl script {\tt texjava.pl} converts \LaTeX{} documents into
Java code with javadoc-style comments.
Everything inside a {\tt code} or {\tt longcode} environment is
considered as Java code.
% The script also works for other languages such as C, C++, etc.
Since \LaTeX{} has a better error-detection scheme than \emph{texjava} 
and \latextohtml, it is a good idea to compile the documents 
first with \LaTeX{}, before using \emph{texjava}.  

The \LaTeX{} commands defined in the {\tt tcode} package are implemented
for \latextohtml{} in the {\tt tcode.perl} file.  This file should 
therefore be accessible to \latextohtml{}, i.e., it should be in a 
directory known by the {\tt\$LATEX2HTMLSTYLES} environment variable.
See \cite[page 99]{iGOO99a} for details about this.
The script has been tested on Perl~5.8.0 but it should 
work with any version~5 Perl interpreter.  Under non-Unix operating
systems, such as Microsoft Windows, it is necessary to install
a Perl distribution, such as ActivePerl \cite{iACT03a}, before using {\tt texjava.pl}.
For Linux environments using C-Shell, {\tt Tcoderc} shell script
can be used to set the environment.  It needs the environment
variable {\tt TCODEHOME} to be set.  It sets the {\tt TEXINPUTS}
variable, creates {\tt .latex2html-init} if it does not already exist, and
defines a {\tt texjava} alias to allow running {\tt texjava.pl} more
easily.

The following command runs the script:

\noindent
{\tt perl texjava.pl $[$-(no)images$]$ $[$-(no)html$]$ $[$-(no)savelatex$]$
  $[$-htmloutdir {\rm\em dir\/}$]$\\
  $[$-master {\rm\em masterfile\/}$]$ $[$-htmlonly$]$
  $[$-htmltitle {\rm\em title\/}$]$} 
     \emph{infile}  $[$\emph{outfile}$]$

Here, {\tt texjava.pl} has to be replaced by a path to
the script if it is not executed in the {\tt tcode} directory.
Its arguments and options are as follows:

\noindent
\emph{infile}

\begin{tab}
The name of the input file, which should have the {\tt .tex} extension.  
If the extension is not given and no file with
such a name exists, {\tt .tex} is appended to the file name.
The input file is parsed but not modified.  
\end{tab}

\noindent
\emph{outfile}

\begin{tab}
The name of the output file.
Normally, it should be a program file, e.g., with the {\tt .java} extension.  
If no extension is specified, {\tt .java} is assumed.  When using the HTML
option, {\tt .html} is used.
If no output file is given, the name of the input file is taken, 
with a {\tt .java} or {\tt .html} extension.  The file will be created
or replaced in the same directory as the input file.
If \emph{outfile} already exists, it will be replaced without notice,
otherwise the file will be created.
If \emph{infile} and \emph{outfile} are the same, an error will occur.
\end{tab}

\noindent
{\tt -(no)images}

\begin{tab}
A switch to enable or disable image generation by \latextohtml{}.
With the {\tt -images} option, 
images are generated and stored in the HTML output directory.
They are copied into a subdirectory corresponding to the package
of the Java file.
With the {\tt -noimages} option, the conversion can be much faster,
but no images (e.g., complicated mathematical formulas) 
will appear in the HTML file and if it does not already exist,
the HTML output directory will not be created.  Images will
be replaced by placeholders in the generated files.
Default value: {\tt -noimages}.
\end{tab}

\noindent
{\tt -(no)html} 

\begin{tab}
With the {\tt -html} option, \latextohtml{} is invoked to convert
from \LaTeX{} to HTML.
With the {\tt -nohtml} option, \latextohtml{} is not called, so the 
script can run faster, but no HTML conversion of the \LaTeX{} 
documentation is produced.  This can be useful for environments which
do not have \latextohtml{} installed.
The \LaTeX{} contents is nevertheless saved as HTML doc comments in the
Java code if {\tt -savelatex} is passed.
Default value: {\tt -nohtml}.
\end{tab}

\noindent
{\tt -(no)savelatex} 

\begin{tab}
With the {\tt -savelatex} option, the script will save \LaTeX{} contents
into Java doc comments, using special encoding.  
This results in rather ugly Java files,
but permits one to recover the original \LaTeX{} file (at least to 
some extent) from the {\tt .java} file.
The {\tt -nosavelatex} option unclutters the
output file, but prevents reverting to \LaTeX.  
The combination {\tt -nohtml -nosavelatex} disables insertion in the output 
file of all doc comments generated from the \LaTeX{} source.
Default value: {\tt -nosavelatex}.
\end{tab}

\noindent
{\tt -htmloutdir }\emph{dir}

\begin{tab}
Specifies where the HTML output will be placed when \emph{Javadoc} processes
the Java files.  This will indicate to {\tt texjava.pl} where to put
the image files generated by \latextohtml.  If not specified, the
images will be copied into an {\tt html} subdirectory of the output
directory where the Java file is created.  This option has no effet if
the {\tt -html} option is not given.  The HTML output directory is
automatically created unless it already exists or the {\tt -noimages}
option is specified.  It is never emptied or removed by {\tt texjava.pl}.
\end{tab}

\noindent
{\tt -master }\emph{masterfile} 

\begin{tab}
The name of a master \LaTeX\ file for the \emph{infile} file.  
This file should compile successfully with the command {\tt latex master}.
Usually, it will contain the \verb!\begin{document}! command and include
the \emph{infile} file.  Its preamble may contain macros used in \emph{infile}.
The script will read only the preamble, i.e., everything before 
\verb!\begin{document}!.  This preamble is used when constructing
the document intended for \latextohtml{} processing.  
If no master file is specified, it is assumed that \emph{infile} itself is
the master file.
Forgetting to specify the master file when it is needed could prevent
some required packages from being loaded into \latextohtml{} and generate
unwanted additional images in the HTML file.
\end{tab}

\noindent
{\tt -htmlonly}

\begin{tab}
Indicates that the script only has to convert a \LaTeX\ document
to HTML, not processing Java code blocks.  This option is useful
to convert overviews into {\tt package.html} files.
It is simpler and better than calling \latextohtml\ directly because
{\tt texjava.pl} passes a bunch of options to \latextohtml\
and transforms the {\tt .tex} and {\tt .html} contents
to avoid some images from math formulas.
\end{tab}

\noindent
{\tt -htmltitle }\emph{title}

\begin{tab}
When using HTML-only mode, allows to give a title to the generated
HTML file.  This title will be placed in the {\tt TITLE} element of {\tt HEAD}.
If one wants to have a title containing spaces, it must be surrounded
by quotation marks for the shell to pass it as one argument
to the script.  If no title is given, an empty string will be used
as the title for the HTML document.
\end{tab}

%%%%%%%%%%%%
\paragraph*{Examples.}

To extract {\it Java} code  from the \LaTeX\  file {\tt Event.tex},
assuming that the master file is {\tt guide.tex},
and place the result in the file {\tt Event.java}, one can use:

%\noindent
{\tt  perl texjava.pl \ -master guide.tex \ Event.tex}

\noindent
which will create the {\tt Event.java} file and, if needed, 
a {\tt html} subdirectory that will contain images.  
To generate the \emph{javadoc} documentation (in HTML), one can use 
a command of the form:

%\noindent
{\tt javadoc -d html} \ \emph{javafilesorpackages} \ {\tt Event.java} \ \emph{javafilesorpackages}

As another example, to extract the {\it C} code from the \LaTeX{} 
file {\tt chrono.tex} and place it in the header file {\tt chrono.h}, 
assuming that the preamble is in {\tt guide.tex}, one can use:

%\noindent
{\tt perl texjava.pl \ -master guide.tex \ chrono.tex \ chrono.h}

Here, one must not forget to specify the target name otherwise
{\tt chrono.java} would be created instead of {\tt chrono.h}.

%%%%%%%%%%%%
\paragraph*{Restrictions, limitations, and special cases.}

\begin{itemize}
\item
Due to the structure of the {\tt code} environment, every
\LaTeX\ command taking no argument will be interpreted.
Braces delimiting arguments
will however display as contents in the code.  This cannot be avoided
because \LaTeX\ must interpret {\tt\bs begin} and {\tt\bs end}
to support contents hiding and {\tt code} environment termination.
\item
If a package declaration is found before the class declaration in a
given Java file, the script will place generated image files in an
appropriate subdirectory of the HTML output directory.  For exemple,
if one writes the line {\tt package a.b.c;} in its Java program, {\tt
  texjava.pl} will copy the images into a subdirectory named {\tt
  a/b/c}.  This reflects the Javadoc generated structure and allows
proper image retrieval by the browser.

\item
Althought the script allows white spaces within commands
(e.g., \verb!\begin {code}!), it can cause problems to \LaTeX.
Such spaces must be avoided in commands controling the {\tt hide}
environment inside a {\tt code} environment, and in the \verb!\end{code}!
command.

\item
When hiding method bodies, one must add at least one space
between \verb!\begin{hide}! and the open brace.  If one
writes

\verb!\begin{hide}{!

\noindent\LaTeX{} will treat the rest of the
file as an argument to the {\tt hide} environment and an error will occur.

\item
The method bodies should always be hidden, otherwise, the
insertion point of the documentation may be incorrectly computed.

\item
The first sentence of a doc comment is used by \emph{javadoc} as a 
\emph{brief} (a one-sentence summary) 
of the corresponding class, interface, field, or method.
The first sentence of a \LaTeX{} documentation block which is to be 
converted to a doc comment should therefore be short and simple.
It should not contain special commands, mathematical formulas, etc.,
and should not be in a {\tt latexonly} environment.
If a formatting problem arises with a too complicated first sentence, 
the script will simply insert a period on a single line (to represent
an empty brief).  This artefact will appear in the \emph{javadoc}
documentation, but it will prevent badly formated HTML on
the rest of the concerned page.

\item
With the {\tt -savelatex} option, the strings {\tt /*HIDE*/},
{\tt /*ENDHIDE*/}, and {\tt /**} will be converted to 
{\tt /* HIDE */}, {\tt /* ENDHIDE */}, and {\tt /* *} everywhere.
This implies in particular that \emph{javadoc} comments already in
the code will be ignored!

\item
If a {\tt package}, {\tt class} or {\tt interface} keyword is found in a long comment
before the Java class or interface declaration, 
and if there is no star preceeding the keyword on the line,
the script will get confused about where to insert the class
documentation or will put images at the wrong place. 

\item
Problems may arise for Java because of the saved \LaTeX{} contents.  
If a text block contains a \LaTeX{} command starting with {\tt u}, e.g., 
{\tt\bs unitlength}, it will be replaced, in the comments, 
by {\tt\bs @unitlength}.  When reverting to \LaTeX, this substitution 
will be undone by \emph{javatex}, so one has to worry about it only
when modifying the (hidden) saved \LaTeX\ contents directly in the 
{\tt .java} file before reverting to \LaTeX{}.

\item
If no {\tt code} or {\tt longcode} environment is found in the input file,
the output file will contain only a single doc comment.

\item
The script uses HTML 4.0 with Unicode for mathematical symbols.
For the symbols to be displayed correctly, one should use a recent
version of major browsers.

\item
To perform the conversion, a recent
version of \latextohtml{} is required.  Version 2002 (1.62) does
not convert greek letters to Unicode properly unless we use
MathML which is not compatible with major browsers, whereas version
2002-2-1 (1.70) works properly.
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{The Javatex Script}
\label{sec:javatex}

{\bf Warning}: This script is experimental and not very reliable,
so one should use it with care.  It is strongly recommended to make 
a backup copy of the original \LaTeX{} file before using it.
The script assumes that the code intended for conversion is
syntactically correct and can be compiled without errors.

The Perl script {\tt javatex.pl} can convert Java source files to
\LaTeX{} documents.  The {\tt .java} source files may have been
produced by \emph{texjava}, but not necessarily.
% (It also works for C or C++ source files.)
For example, one may want to use a special editor for Java programs
to edit the Java file and encode the \LaTeX{} documentation in it by hand,
in the same format as it would have been saved by \emph{texjava}.

The Java source file intended for conversion should normally contain 
Java doc comments, of the form {\tt /**} \emph{comments} {\tt */},
where \emph{comments} can be any (multi-line) text.
The contents of these comments is converted into \LaTeX{} documentation
blocks for classes, interfaces, fields, and methods.
Other types of comments in the code are simply ignored and preserved 
intact into code blocks.

The contents of HTML commented blocks of the form \verb#<!--LATEX ... -->#
will be inserted directly into the \LaTeX{} document.
This construct allows hiding \LaTeX{} code inside Java doc comments.  
Note that a doc comment should never begin with such an
HTML comment, otherwise \emph{javadoc} could get mixed up and
produce badly-formatted documentation.  If a block contains only
\LaTeX\ code, it can be entered as a comment of the form 
{\tt /*LATEX ... */} rather than as a doc comment, in order to avoid
confusion of \emph{javadoc}.

The {\tt /*HIDE*/} \dots {\tt /*ENDHIDE*/} constructs found in the 
code are converted respectively to \verb!\begin{hide}! \dots 
\verb!\end{hide}! constructs.

The {\tt /*CODE*/}, {\tt /*SMALLCODE*/}, and {\tt /*LONGCODE*/} 
constructs are converted to the {\tt code}, {\tt smallcode}, and 
{\tt longcode} environments.

All java doc-comment markers {\tt /**} and {\tt */} will be removed,
since these doc comments are converted to \LaTeX{} documentation.
Any star at the beginning of a line in a doc comment will also be 
removed to follow Java doc-comment formatting conventions.
Doc comment are considered converted from \emph{texjava} and
should contain some special indications.  
Since HTML to \LaTeX{} conversion is not supported, 
unmarked text in comments is simply discarded.

The first doc comment is considered as the class or interface documentation
and will appear at the top of the resulting document.  
In the code, it should be placed on the top of the class or interface
declaration.  
A block of code containing the code before the class documentation and 
until a new doc-comment block appears will be converted to a \LaTeX{} 
code block.  Any subsequent block of comments will be inserted as \LaTeX{} 
contents after the declaration or body following the documentation.
A declaration is detected by the presence of a semicolon (;) on a line.
An end of body is detected when a balanced set of opening and closing
brackets is found.

The tab characters will be replaced by individual spaces, 
in order to be correctly displayed by \LaTeX.  


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Running Javatex}
\label{sec:javatex2}

As for {\tt texjava.pl}, the script requires a Perl 5 interpreter to
be installed but \latextohtml{} is not necessary for {\tt javatex.pl}.
The following command runs the script:

%\noindent
{\tt perl javatex.pl $[$-tabsize {\rm\em i\/}$]$}
    \emph{infile} \ \emph{outfile}\\

Here, {\tt javatex.pl} has to be replaced by a path to
the script if it is not executed in the {\tt tcode} directory.
Its arguments and option are as follows:

\noindent
\emph{infile}

\begin{tab}
The name of the input file, which should have the {\tt .java} extension.  
The input file is parsed but not modified.  
\end{tab}

\noindent
\emph{outfile}

\begin{tab}
The name of the output file, which should have the {\tt .tex} extension.
If \emph{outfile} already exists, it will be replaced without notice,
otherwise the file will be created in the working directory.
If \emph{infile} and \emph{outfile} are the same, an error will occur.
\end{tab}


\noindent
{\tt -tabsize }\emph{i}

\begin{tab}
By using the {\tt -tabsize }\emph{i} option, where \emph{i} is a non-negative 
integer, one can specify the number of spaces that corresponds to a tab 
character.  The default value is 8.
\end{tab}

%%%%%%%%%%%%%%
\paragraph*{Example:}

To extract the \LaTeX{} code from the Java file {\tt Chrono.java}
and place it in file {\tt Chrono.tex}, one can use:

% \noindent
{\tt  perl javatex.pl \ Chrono.java \ Chrono.tex}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Ant tasks}

Apache Ant is becoming the de facto build system for Java applications.
An XML build file instructs Ant how to build the Java package in a portable
way.  Unfortunately, Ant is not a scripting language and can only deal
with plain {\tt .java} file.  It could be possible to call {\tt texjava.pl}
manually using the Ant built-in {\tt exec} task, but this would fastly
because tedious and no dependency checking would be performed at all.
On each build cycle, every {\tt .tex} file would be turned into a {\tt .java}
and recompiled, since it would be freshly created, into a new {\tt .class} file.
However, it is possible to extend Ant using user-defined
tasks.  TCode provides some Ant tasks to work with the \LaTeX{} files.
The {\tt texjava} task allows one to process a batch of {\tt .tex} files
into {\tt texjava.pl}, producing output {\tt .java} files.  The {\tt pdflate}
task allows one to construct, using pdf\LaTeX, the PDF documentation
for a package.  To use these tasks, one must include {\tt tcode.jar} in
the CLASSPATH environment variable and declare the use tasks in
the {\tt build.xml} file, using the {\tt taskdef} task.  For example, to use
{\tt texjava} task, one must write, in the {\tt project} section of {\tt build.xml},

\noindent\verb!<taskdef name="texjava" classname=''umontreal.iro.lecuyer.tcode.Texjava"/>!

\include{Texjava}
\include{PdfLatex}

\bibliographystyle{plain}
\bibliography{ift}  % Dans texmac.

\end{document}
