## File: tcode.tex

package info (click to toggle)
tcode 0.1.20080918-3
 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023 \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## 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!! \include{Texjava} \include{PdfLatex} \bibliographystyle{plain} \bibliography{ift} % Dans texmac. \end{document}