Adding overview docs and a couple tweaks to the demo.

[wxWidgets.git] / utils / tex2rtf / docs / tex2rtf.tex

\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
%\input{psbox.tex}
\newcommand{\commandref}[2]{\helpref{{\tt $\backslash$#1}}{#2}}%
\newcommand{\commandrefn}[2]{\helprefn{{\tt $\backslash$#1}}{#2}\index{#1}}%
\newcommand{\commandpageref}[2]{\latexignore{\helprefn{{\tt $\backslash$#1}}{#2}}\latexonly{{\tt $\backslash$#1} {\it page \pageref{#2}}}\index{#1}}%
\newcommand{\indexit}[1]{#1\index{#1}}%
\newcommand{\inioption}[1]{{\bf {\tt #1}}\index{#1}}%
\parskip=10pt%
\parindent=0pt%
%\backgroundcolour{255;255;255}\textcolour{0;0;0}% Has an effect in HTML only
\winhelpignore{\title{Manual for Tex2RTF 2.0: A \LaTeX\ to RTF and HTML converter}%
\author{Julian Smart}%
\date{November 1999}%
}%
\winhelponly{\title{Manual for Tex2RTF 2.0}%
\author{by Julian Smart\\$$\image{1cm;0cm}{tex2rtf.wmf}$$}%
}%
\makeindex%
\begin{document}%
\maketitle%
\pagestyle{fancyplain}%
\bibliographystyle{plain}%
\pagenumbering{roman}%
\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%
\tableofcontents%

\chapter*{Copyright notice}%
\setheader{{\it COPYRIGHT}}{}{}{}{}{{\it COPYRIGHT}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

Copyright (c) 1997 Julian Smart.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose is hereby granted without fee, provided that the
above copyright notice, author statement and this permission notice appear in
all copies of this software and related documentation.

THE SOFTWARE IS PROVIDED ``AS-IS'' AND WITHOUT WARRANTY OF ANY KIND, EXPRESS,
IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL JULIAN SMART OR THE ARTIFICIAL INTELLIGENCE
APPLICATIONS INSTITUTE OR UNIVERSITY OF EDINBURGH BE LIABLE FOR ANY
SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR
ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY
OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

\chapter{Introduction}%
\pagenumbering{arabic}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

This document describes a utility for converting \popref{\LaTeX}{latexgloss}\ files into
several other formats.

Only a subset of \LaTeX\ can be processed by this utility, especially
since the target document language will never perfectly match \LaTeX.
Whether the quality of the results is good enough will depend upon the
application and your own expectations. {\it This caveat is worth emphasizing}, because
many people assume that any old \LaTeX\ document will go through without modification: it might,
but the chances are you'll need to modify it a bit for Tex2RTF. Tex2RTF was written with
portable document maintenance and generation in mind, with less emphasis on accepting all \LaTeX\ syntax.
You have been warned!

Tex2RTF is heavily biased towards making on-line, hypertext versions of
\rtfsp\LaTeX\ documents, but the \popref{RTF}{rtf} converter can be used to generate linear,
paper-based documents too.

The latest version of Tex2RTF, plus source code, can be accessedfrom:

\begin{verbatim}
http://web.ukonline.co.uk/julian.smart/tex2rtf
ftp://www.remstar.com/pub/wxwin/tex2rtf
\end{verbatim}

It is available in Sun Open Look, Motif, Windows 3.1, Windows 95/NT, and
non-GUI UNIX versions.

Tex2RTF was developed using the free Open Look, Motif and Windows 3.1
C++ class library \popref{wxWidgets}{wxwidgets}.

\section{Status of Tex2RTF}\index{status of Tex2RTF}%

Windows HTML help, and wxWidgets 2 wxHTML help, are now catered for using
the htmlWorkshopFiles setting.

Tex2RTF is very rarely updated these days: it would be nice to
rewrite the parser (and indeed the rest of it) at some point,
to improve error reporting, space handling and ability to
handle more advanced Tex/Latex commands.

\section{Acknowledgements}\index{acknowledgements}%

Thanks are due to the many people in AIAI and on the Internet at large
who have pointed out bugs or shortcomings in Tex2RTF. Michel Lavaud has been
a great help in giving advice for improvements to the manual.

\section{Change log}\index{change log}%

Version 2.0, August 24th 1999

\begin{itemize}\itemsep=0pt
\item Added htmlWorkshopFiles setting, to output .hpp, .hhc
and .hhk (HTML Workshop) files, for generating MS HTML Help or wxHTML Help.
\end{itemize}

Version 1.64, October 20th 1998

\begin{itemize}\itemsep=0pt
\item Added \verb$\insertatlevel$ command.
\end{itemize}

Version 1.63, October 21st 1997

\begin{itemize}\itemsep=0pt
\item Debugged problem with Word bookmarks not being inserted for unnumbered
sections.
\end{itemize}

Version 1.62, August 18th 1997

\begin{itemize}\itemsep=0pt
\item Added contributed changes by Andreas Münzenmaier to support German
accents by allowing the characters to be placed in input files, and also
converting them back to character codes in the WinHelp {\tt .cnt} file.
\item Now \verb$\helpref$ causes page references to be inserted in linear RTF,
or section references if not on Word mode.
\item WinHelp table caption bug fixed.
\end{itemize}

Version 1.61, June 11th 1997

\begin{itemize}\itemsep=0pt
\item \verb$\fcol$ now works in HTML using the FONT tag.
\item \verb$\twocollist$ works in indented paragraphs, and is now
implemented properly using tables in HTML.
\item New boolean option {\bf combineSubSections} added, which switches off
the generation of separate HTML files below section level. This can reduce the
number of HTML files substantially.
\end{itemize}

Version 1.60, February 18th 1997

\begin{itemize}\itemsep=0pt
\item The index command now allows complex LaTeX instead of inserting the
first argument verbatim.
\end{itemize}

Version 1.59, February 14th 1997

\begin{itemize}\itemsep=0pt
\item Added special processing for a chapter called Popups.
\end{itemize}

Version 1.58, August 1st 1996

\begin{itemize}\itemsep=0pt
\item Added HTML settings: backgroundImage, backgroundColour, textColour,
linkColour, followedLinkColour. 
\item Added \verb$\backgroundimage$, \verb$\backgroundcolour$, \verb$\linkcolour$,
\verb$followedLinkColour$. \verb$\background$ now obsolete (but behaviour is
backward compatible).
\item The default background colour is now white.
\item Debugged HTML \verb$\ss$ (put in wrong place in code).
\end{itemize}

Version 1.57, July 27th 1996

\begin{itemize}\itemsep=0pt
\item Added upperCaseNames setting; now all links in HTML files are in lower
case unless specified otherwise.
\end{itemize}

Version 1.56, May 25th 1996

\begin{itemize}\itemsep=0pt
\item Debugged \verb$\special$ processing for HTML (escaped characters such ampersand).
\item Added contentsDepth for Word RTF contents page.
\item Removed overlapping href in HTML pages.
\end{itemize}

Version 1.55, May 6th 1996

\begin{itemize}\itemsep=0pt
\item \verb$\verb$ support corrected for HTML.
\item Added {\it abstractName} setting.
\item Debugged incorrect centring for HTML buttons.
\end{itemize}

Version 1.54, Feburary 28th 1996

\begin{itemize}\itemsep=0pt
\item Bug fix for 24-bit bitmap inclusion when generating RTF:
caused a floating point error.
\item Added htmlIndex setting, to generate an {\tt .htx} index file of an HTML document for
use in wxHelp version 2 or other programs.
\item Fixed header/footer bug.
\item Change colons to spaces for WinHelp RTF keywords, since the colon has a specific meaning in WinHelp.
\end{itemize}

Version 1.53, January 1995

\begin{itemize}\itemsep=0pt
\item Now stores paths from file inclusions, so that if you include
a file A from a separate directory, which then includes a file B
relative to that directory, Tex2RTF will search in the path
of A to find file B.
\end{itemize}

Version 1.52, December 1995

\begin{itemize}\itemsep=0pt
\item \verb$\helpref$ and related commands now generate italicized instead
of bold `anchor' text for linear formats.
\item Cured bug where Tex2RTF could hang on start up, while reading
the {\tt tex2rtf.ini} file. This occurred when a comment finished with
the end of file.
\item Split the commands reference in two (\LaTeX\ and Tex2RTF commands),
and added a {\it Commands by category} section.
\item Removed a bug that caused HTML output to be garbled on the
second pass.
\end{itemize}

Version 1.51: Windows 95 enhancements.

\begin{itemize}\itemsep=0pt
\item Added settings winHelpContents (for generating {\tt .cnt} file), winHelpVersion (for specifying
target version of WinHelp).
\item Added space to non-scrolling region of topic.
\item If winHelpVersion is 4, makes non-scrolling region grey and the rest yellow.
\item Added \verb$\settransparency$ command for WinHelp 4 transparent bitmaps.
\end{itemize}

Version 1.50:

\begin{itemize}\itemsep=0pt
\item Tidied up HTML generation (headers and bodies in the right places).
\item Eliminated extra space after verbatim in HTML.
\item Added support for simple tables in HTML.
\item Added \verb$\textcolour$, \verb$\background$ for colouring text and background in HTML.
\item Added \verb$\copyright$, \verb$\registered$ symbols in HTML.
\item Added \verb$\imagel$, \verb$\imager$ for left and right aligned images
in HTML.
\item Added \verb$\brclear$ for clearing image alignment in HTML.
\item Added \LaTeX\ font size support in HTML (\verb$\small$, \verb$\large$ etc.) using Netscape font extensions.
\item HTML button-bar change: always shows the same buttons, but may make one or more insensitive. Changing button positions
could be very annoying.
\item Tidied up RTF generation for non-Word viewers ({\it useWord} set to {\it false}). Will now look reasonable using
Windows 95 Quick View and WordPad: WordPad doesn't do tables but does bitmaps, and QuickView does tables but not
bitmaps. Such is life.
\end{itemize}

Version 1.49:

\begin{itemize}\itemsep=0pt
\item Cured some bugs (char used for fgetc instead of int) so now compiles for
WIN32s.
\end{itemize}

Version 1.48:

\begin{itemize}\itemsep=0pt
\item Added some LaTeX2e fonts commands such as \verb$\rmfamily$, \verb$\textrm$, \verb$\emph$.
Most of these are aliases for other commands.
\end{itemize}

Up to version 1.47:

\begin{itemize}\itemsep=0pt
\item Added \verb$\backslashraw$, \verb$\rbraceraw$ and \verb$\lbraceraw$ commands
to help output arbitrary RTF.
\item Added \verb$\sethotspotcolour$, \verb$\sethotspotunderline$ commands for controlling
WinHelp hotspot appearance.
\item Added truncateFilenames option.
\item Improved HTML inline image handling.
\end{itemize}

Up to version 1.46:

\begin{itemize}
\itemsep=0pt
\item Added \verb$\urlref$ command for specifying HTML URLs.
\item Started support for translating .SHG files to HTML .map files
(this works if compiled under Borland, not MS VC++ for some reason!)
\item Fixed nasty memory bug in HTML code (thanks Petr).
\end{itemize}

Version 1.40:

\begin{itemize}
\itemsep=0pt
\item Added {\it generateHPJ} option for generating the .HPJ WinHelp project file
\item Added support for DDE via a small command set
\end{itemize}

Version 1.39:

\begin{itemize}
\itemsep=0pt
\item Option for using Word's INCLUDEPICTURE or IMPORT field, since the method that
works for Works, doesn't work for Word! See {\it bitmapMethod} in the
settings section.
\end{itemize}

Version 1.37-1.38:

\begin{itemize}
\itemsep=0pt
\item Improved bibliography reading and cured some minor bugs
\item Added \verb$\ss$ German sharp s
\item Added rudimentary \verb$\special$ command (simply copies the argument
to the output)
\item Added missing '.' in subsubsection reference
\item Added primitive internationalisation support with contentsName, tablesName etc.
\end{itemize}

Version 1.36:

\begin{itemize}
\itemsep=0pt
\item All HTML special characters now correctly delimited by a semicolon.
\item Cured HTML section-duplicating bug I introduced in 1.35.
\item Cured too much spacing after sections in RTF, introduced in 1.35.
\end{itemize}

Version 1.35:

\begin{itemize}
\itemsep=0pt
\item Added TCHECK tool, to help track down common Tex2RTF syntax problems.
\item Included Kresten Thorup's LACHECK \LaTeX\ checking tool with DOS executable.
\item Now ignores \verb|\@| command.
\item Table of contents now includes numbered subsubsections.
\end{itemize}

Version 1.34:

\begin{itemize}
\itemsep=0pt
\item Added \verb$\multicolumn$ `support' to stop RTF readers crashing.
\item Added {\it useWord, defaultColumnWidth, compatibility} options to {\tt .ini} file.
\item \verb$\comment$ environment now doesn't complain about unknown syntax.
\item Added \verb$\toocomplex$ environment that treats its contents as
verbatim in output, treated as normal output in true \LaTeX.
\item End-of-line comments allowed in in {\tt .ini} files, using semicolon,
percent or hash characters to denote a comment.
\item For linear RTF, Word for Windows support for \verb$\printindex$,\rtfsp
\verb$\index$, \verb$\pageref$, \verb$\listoftables$, \verb$\listoffigures$, contents page.
\item Added RTF support for various symbols.
\item Added colour support, with \verb$\definecolour$, \verb$\fcol$ and \verb$\bcol$ commands.
\item Fixed some bugs: page numbering problems, macros deleted after first pass.
\end{itemize}

Version 1.33:

\begin{itemize}
\itemsep=0pt
\item Added -charset command-line switch.
\item Added \verb$\itemsep$, \verb$\twocolumn$, \verb$\onecolumn$, \verb$\setfooter$, \verb$\setheader$, \verb$\pagestyle$,
\verb$\pagenumbering$, \verb$\thechapter$, \verb$\thesection$, \verb$\thepage$, \verb$\thebibliography$, \verb$\bibitem$ commands.
\item New environment called \verb$\twocollist$ for making two-column lists,
with formatting optimized for target file format.
\item New \verb$\indented$ environment for controlling indentation.
\item List indentation and bulleting improved.
\item Added commands \verb$\normalbox$, \verb$\normalboxd$ for putting borders around text.
\item Many options can now be specified in the {\tt .ini} file along with custom macros.
\item Cured bug that put too much vertical space after some commands.
\item Improved table formatting.
\item Optional `Up' button in WinHelp files for easier navigation.
\item Verbatim lines followed by \verb$\par$ in RTF, to improve WinHelp wrapping.
\item Conversion may now be aborted under Windows by attempting to close the application.
\item Added conditional output for all formats: \verb$\latexignore$, \verb$\latexonly$, \verb$\rtfignore$, \verb$\rtfonly$,
\verb$\winhelpignore$, \verb$\winhelponly$, \verb$\htmlignore$, \verb$\htmlonly$, \verb$\xlpignore$, \verb$\xlponly$.
\item HTML generator can now add Contents, Up, $<<$ and $>>$ buttons (text or bitmap) to
each page except titlepage.
\end{itemize}

Version 1.32:

\begin{itemize}
\itemsep=0pt
\item \verb$\footnote$ command now supported in WinHelp RTF, and \verb$\footnotepopup$\rtfsp
added.
\end{itemize}

Version 1.31:

\begin{itemize}
\itemsep=0pt
\item \verb$\footnote$ command now supported, in linear RTF only.
\item Added {\tt -bufsize} option, for converting large documents.
\end{itemize}

Version 1.30:

\begin{itemize}
\itemsep=0pt
\item \verb$\image$ command now scales metafiles (but not bitmaps).
\item Fixed macro loading bug, now informs the user of the found macro filename.
\item Now supports paragraph and subparagraph commands.
\item Support for some accents added.
\item \verb$\verb$ command now supported.
\item Bug in subsubsection handling fixed.
\item Can save conversion log in a text file.
\end{itemize}

Version 1.22:

\begin{itemize}
\itemsep=0pt
\item More informative, warns against use of some commands.
\item Added compile-time support for non-GUI environments (such as plain UNIX).
\item Improved HTML support.
\end{itemize}

\chapter{Running Tex2RTF}\index{running Tex2RTF}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

Tex2RTF may be run in a number of ways: with or without command line arguments,
interactively or in batch mode, and with an optional initialisation file
for specifying \LaTeX\ macros and detailed options.

Tex2RTF accepts two arguments (input and output filenames) and trailing
(optional) switches.  If both filenames are given, the utility will work
in batch mode.  Otherwise, if Tex2RTF has been compiled for GUI
operation, a main window will be shown, with appropriate menu items for
selecting input and output filenames, starting off the conversion
process, and so on.

Note that if the file {\tt bullet.bmp}\index{bullets} is found by Tex2RTF, this bitmap
will be used as the bullet for items in \verb$\itemize$ lists, for WinHelp
output. Otherwise, a symbol will be inserted (linear RTF) or bold `o'
will be used instead (all other formats).

Syntax error reporting is fairly minimal. Unrecognised macro errors may
actually be produced by an unbalanced brace or passing the wrong number of
arguments to a command, so look in the vicinity of the error for the
real cause.

\normalbox{Some of the syntax that is OK for true \LaTeX\ but which trips up
Tex2RTF, may be detected by the TCHECK\index{TCHECK} program included in the tools
directory of the Tex2RTF distribution. Some \LaTeX\ errors may be picked up
by the LACHECK\index{LACHECK} program, also found in the tools directory.}

It is recommended that you run Tex2RTF twice in order to be sure of
resolving all references and including an up-to-date contents page.

If importing RTF files into Word for Windows\index{Microsoft Word}, you may need to reformat
the document. The easiest way to do this is to select all text with
CTRL-A, then reformat with F9. Reformat again to ensure all references
are resolved. For the second format, respond with {\it Update Entire
Table} to prompts.

\winhelponly{
\section{Tex2RTF Interface}

This is the Tex2RTF interface under Windows. Click on an area of the
picture for more information.

$$\imagemap{1cm;0cm}{screen}{mapref}$$

\subsection{Menu bar}\label{menubar}

Use the menubar for interactive operations.

\subsection{Message area}\label{messagearea}

Tex2RTF writes warning and error messages on this window.

\subsection{Status line}\label{statusline}

Displays help on menu items as the user drags the cursor over the menus.

\subsection{Mode indicator}\label{modeindicator}

Displays the output mode Tex2RTF is currently in.
}

\section{Command line arguments}\index{command line arguments}%

These are the optional arguments you may give Tex2RTF on the command line.

\twocolwidtha{5cm}
\begin{twocollist}
\twocolitem{{\bf -bufsize}}{Specifies buffer size in K (default 60 under Windows,
500 under UNIX). Large files (particularly large verbatim environments)
may require a large buffer size, equal to the largest argument of a \LaTeX\ command.
Note that this value may not be larger than 64 under Windows.}
\twocolitem{{\bf -html}}{Specifies HTML (World Wide Web) output.}
\twocolitem{{\bf -interactive}}{Forces interactive mode even if both
filenames are given.}
\twocolitem{{\bf -charset charset}}{Specifies a character set for
RTF production. This can be one of ansi, mac, pc, and pca.
The default is ansi.}
\twocolitem{{\bf -macros filename}}{Specifies a file for the custom macro
file -- see \helpref{Macro not found error}{macronotfound}.}
\twocolitem{{\bf -rtf}}{Specifies linear RTF output.}
\twocolitem{{\bf -sync}}{Forces synchronous mode (no yielding to other
processes) -- usually use this in non-interactive mode.}
\twocolitem{{\bf -twice}}{Tells Tex2RTF to run the conversion twice to ensure all
references and citations are resolved and the contents page included.}
\twocolitem{{\bf -winhelp}}{Specifies Windows Help RTF output.}
\end{twocollist}

\section{Initialisation file syntax}\label{inifile}\index{initialisation file}%

The initialisation file contains further detailed options for
customising Tex2RTF's behaviour. A file may be specified
with the {\tt -macros} command line switch, otherwise Tex2RTF
looks for the file {\tt tex2rtf.ini} in the working directory
or input file directory.

The file may comprise macro\index{macros} (command) definitions or option settings.

The syntax for a macro definition is:

\begin{verbatim}
    \name [number of args] {...LaTeX code...}
\end{verbatim}

For example:

\begin{verbatim}
    \crazy      [2]{{\bf #2} is crazy but #1 is not}
    \something  [0]{}
    \julian     [0]{Julian Smart}
\end{verbatim}

The syntax for an option setting is:

\begin{verbatim}
    name = value
\end{verbatim}

or 

\begin{verbatim}
    name = "value"
\end{verbatim}

For example:

\begin{verbatim}
    conversionMode = RTF
    runTwice = true
    titleFontSize = 12
    authorFontSize = 10
    headerRule = yes
    footerRule = yes
\end{verbatim}

Options expecting boolean values accept {\it 1, 0, true, false, yes, no} in any combination of upper or
lower case.

End-of-line comments are allowed in an initialisation file, using the
hash, semicolon or percent signs to denote the start of a comment, which runs
until the end of the line.

\subsection{Tex2RTF options}\index{options in initialisation file}\index{tex2rtf.ini}\index{initialisation file}\index{macros}%

These are the allowable options in an initialisation file.

\subsubsection{General options}\label{generaloptions}

\twocolwidtha{5cm}
\begin{twocollist}
\htmlignore{\twocolitemruled{Option}{Description}}
\twocolitem{\inioption{compatibility}}{Set to true for maximum \LaTeX\ compatibility, e.g. if
tables crash RTF readers. Should be false (default) if the Tex2RTF guidelines
are followed, e.g. use of $\backslash${\tt row} command in tabular environment.}
\twocolitem{\inioption{conversionMode}}{One of RTF, WinHelp, XLP (or wxHelp), and HTML.}
\twocolitem{\inioption{ignoreInput}}{Adds the filename to the list of files ignored by the $\backslash${\tt input} command.
The only default filename in the list is {\tt psbox.tex}.}
\twocolitem{\inioption{isInteractive}}{If true, runs in interactive mode (the default).}
\twocolitem{\inioption{runTwice}}{If true, runs the converter twice.}
\twocolitem{\inioption{ignoreBadRefs}}{If true (or yes), ignores bad helpref references
and simply writes the text in the first argument. Useful when a program such as HelpGen
generates references to classes documented in another manual.}
\end{twocollist}

\subsubsection{Presentation options}\index{options, presentation}%

\begin{twocollist}
\htmlignore{\twocolitemruled{Option}{Description}}
\twocolitem{\inioption{authorFontSize}}{Specifies the point size for the author and date (RTF only).}
\twocolitem{\inioption{chapterFontSize}}{Specifies the point size for chapter headings (RTF only).}
\twocolitem{\inioption{documentFontSize}}{One of 10, 11 and 12, to specify the main font size
independently of the \LaTeX\ document style command.}
\twocolitem{\inioption{sectionFontSize}}{Specifies the point size for section headings (RTF only).}
\twocolitem{\inioption{subsectionFontSize}}{Specifies the point size for subsection headings (RTF only).}
\twocolitem{\inioption{titleFontSize}}{Specifies the point size for the title (RTF only).}
\twocolitem{\inioption{chapterName}}{The string used when referencing chapters. The default is ``chapter".}
\twocolitem{\inioption{sectionName}}{The string used when referencing sections. The default is ``section".}
\twocolitem{\inioption{subsectionName}}{The string used when referencing subsections. The default is ``subsection".}
\twocolitem{\inioption{subsubsectionName}}{The string used when referencing subsubsections. The default is ``subsubsection".}
\twocolitem{\inioption{indexName}}{The string used for printing the index heading. The default is ``Index".}
\twocolitem{\inioption{contentsName}}{The string used for printing the contents heading. The default is ``Contents".}
\twocolitem{\inioption{abstractName}}{The string used for printing the abstract heading. The default is ``Abstract".}
\twocolitem{\inioption{tablesName}}{The string used for printing the list of tables heading. The default is ``List of Tables".}
\twocolitem{\inioption{tableName}}{The string used when referencing a table. The default is ``table".}
\twocolitem{\inioption{figuresName}}{The string used for printing the list of figures heading. The default is ``List of Figures".}
\twocolitem{\inioption{figureName}}{The string used when referencing a figure. The default is ``figure".}
\twocolitem{\inioption{glossaryName}}{The string used for printing the glossary heading. The default is ``Glossary".}
\twocolitem{\inioption{referencesName}}{The string used for printing the references heading. The default is ``References".}
\end{twocollist}

\subsubsection{RTF and WinHelp options}\label{rtfwinhelpoptions}\index{options, RTF}\index{RTF}%

\begin{twocollist}
\htmlignore{\twocolitemruled{Option}{Description}}
\twocolitem{\inioption{bitmapMethod}}{Can be ``hex'' (embed the hex data in the file with a $\backslash$dibitmap keyword),
``includepicture'' (use the MS Word 6.0 INCLUDEPICTURE field) or ``import'' (an earlier name
for INCLUDEPICTURE). ``hex'' may be used for importing into MS Works, but this doesn't work
for Word 6.0. The default is ``includepicture''.}
\twocolitem{\inioption{contentsDepth}}{The depth of headings that is displayed in the table of contents. The default
is 4 but you may wish to reduce this, for example for manuals that document C++ and have a large number of
headings for member functions.}
\twocolitem{\inioption{defaultColumnWidth}}{The width in points for columns in tables
where the width of the column is not set by using {\it p} in the tabular
argument. The default is 100.}
\twocolitem{\inioption{footerRule}}{If true, draws a rule above footers (linear RTF only).}
\twocolitem{\inioption{generateHPJ}}{If true, generates a .HPJ project file (WinHelp mode only).}
\twocolitem{\inioption{headerRule}}{If true, draws a rule below headers (linear RTF only).}
\twocolitem{\inioption{listLabelIndent}}{Specifies the size of list item label indentation, in points.
The default is 18.}
\twocolitem{\inioption{listItemIndent}}{Specifies the size of list item indentation, in points. The default
is 40.}
\twocolitem{\inioption{indexSubsections}}{If true (the default), subsection and subsubsection
titles are indexed in RTF mode.}
\twocolitem{\inioption{mirrorMargins}}{If true, margins are mirrored in twosided documents (linear RTF only).}
\twocolitem{\inioption{useWord}}{If true (the default), Word for Windows RTF
formatting is used where possibly, e.g. for the table of contents, list of
tables, and list of figures.}
\twocolitem{\inioption{useHeadingStyles}}{If true (the default), sections are marked with
appropriate heading styles for generating the table of contents in RTF.}
\twocolitem{\inioption{useUpButton}}{If true (the default), WinHelp files will be generated with an {\bf Up}\rtfsp
button to make browsing easier. Note that you need to put an extra line in the CONFIG section
of your .HPJ file:

{\tt CreateButton("Up", "\&Up", "JumpId(`name.hlp', `Contents')")}

where {\tt name.hlp} is the name of your help file.}
%%% NEED TO BREAK THE LIST AT THE PAGE BREAK BECAUSE LATEX IS STUPID
%%% UNFORTUNATELY, Tex2RTF IS STUPIDER SO NEED TO COMMENT OUT THIS
%%% LINE WHEN MAKING HTML, RTF, XLP
%\latexonly{\end{twocollist}\newpage\begin{twocollist}}
\twocolitem{\inioption{winHelpContents}}{If yes, ok or true, a WinHelp {\tt .cnt} file will be generated (used in Windows 95 for either old WinHelp
files or new WinHelp 4 files).}
\twocolitem{\inioption{winHelpVersion}}{The version of WinHelp being targetted. This affects the generated {\tt .hpj} file and features
such as transparent bitmaps which are new to version 4 or later. The default is 3.}
\twocolitem{\inioption{winHelpTitle}}{Windows Help file title, inserted into the project file if {\it generateHPJ} is true.}
\end{twocollist}

\subsubsection{HTML options}\label{htmloptions}\index{options, HTML}\index{HTML}%

\begin{twocollist}
\htmlignore{\twocolitemruled{Option}{Description}}
\twocolitem{\inioption{htmlBrowseButtons}}{Allows generation of Contents, Up, browse back and browse forward
buttons on each HTML page except title page. Specify none, text or bitmap. If you specify
bitmap, make sure that the files {\tt contents.gif}, {\tt up.gif}, {\tt back.gif} and {\tt forward.gif} are in the
directory where the HTML files will reside: samples are given in the docs directory.}
\twocolitem{\inioption{truncateFilenames}}{If true, uses {\tt .htm} suffix instead of {\tt .html},
and truncates filenames within HTML documents.}
\twocolitem{\inioption{htmlIndex}}{If true, specifies generation of an {\tt .htx} index file for an HTML document.
This file can be used in wxHelp version 2 or other programs. The file consists of a number of lines,
each line with three fields separated by bar characters: the indexed phrase, the file, and a label in the file.}

\twocolitem{\inioption{htmlWorkshopFiles}}{If true, specifies generation of {\tt .hpp, .hhc} and {\tt .hhk} files
which can be used to create both MS HTML Help and wxHTML Help files. wxHTML Help
is the HTML help facility that can be used by wxWidgets 2 applications (see the wxWidgets manual
and the wxWidgets HTML sample).}
\twocolitem{\inioption{upperCaseNames}}{If true, filenames in links are in upper case. By default
filenames are in lower case.}
\twocolitem{\inioption{backgroundColour}}{Specifies the RGB background colour for the document, e.g. {\tt 255;255;255} for white.
The default is white.}
\twocolitem{\inioption{backgroundImage}}{Specifies the RGB background image for the document, e.g. {\tt tile.gif}.}
\twocolitem{\inioption{textColour}}{Specifies the RGB text colour for the document, e.g. {\tt 0;0;0} for black.}
\twocolitem{\inioption{linkColour}}{Specifies the RGB link colour for the document, e.g. {\tt 0;0;255} for blue.}
\twocolitem{\inioption{followedLinkColour}}{Specifies the RGB followed link colour for the document, e.g. {\tt 0;0;255} for blue.}
\twocolitem{\inioption{combineSubSections}}{If true (or yes), switches off
the generation of separate HTML files below section level. This can reduce the
number of HTML files substantially. A subsection contents list is inserted before
the first subsection.}
\twocolitem{\inioption{htmlFaceName}}{A string specifying the overall font face, such as ``"Arial, Lucida, Helvetica".}
\end{twocollist}

\section{DDE commands}\index{DDE}%

A Windows program can hold a conversation with Tex2RTF using DDE. The Tex2RTF server name is
``TEX2RTF'', and the topic name to use is also ``TEX2RTF''.

Tex2RTF functionality is accessed using the DDE {\it Execute} message.
The {\it Execute} data should consist of a command name and possibly one
argument, e.g.

\begin{verbatim}
    INPUT c:\docs\mine.tex
\end{verbatim}

If the command is not recognised, a standard TEX2RTF.INI option is assumed.

The {\it Request} DDE message can be used to query the return status of an {\it Execute}
command, and will be one of {\it OK} (no error), {\it CONVERSION ERROR}, or a more
specific error string.

The following DDE commands may be used:

\begin{twocollist}
\htmlignore{\twocolitemruled{Command}{Description}}
\twocolitem{\inioption{EXIT}}{Takes no argument, and exits Tex2RTF.}
\twocolitem{\inioption{GO}}{Takes no argument, and initiates the conversion.}
\twocolitem{\inioption{INPUT}}{Takes a file name as the argument, and sets the input file to be this name.}
\twocolitem{\inioption{MINIMIZE}}{Takes no argument, and minimizes Tex2RTF.}
\twocolitem{\inioption{OUTPUT}}{Takes a file name as the argument, and sets the input file to be this name.}
\twocolitem{\inioption{RESTORE}}{The same as SHOW.}
\twocolitem{\inioption{SHOW}}{Takes no argument, and unminimizes Tex2RTF.}
\end{twocollist}

\section{Performance issues}\index{performance}%

Since Tex2RTF reads the whole file into memory, a lot of memory is needed.
For very large documents, 16MB of RAM is adviseable.

I tested conversion of the wxWidgets 1.63 manual on both VC++ 1.5 and
Watcom WIN32s versions of Tex2RTF, both running under Windows 3.11 on a
Gateway P60 with 16MB of RAM and a 2MB disk cache. Two passes were
made, with 1.5MB of WinHelp RTF being generated. The unoptimized 16-bit
version took 169 seconds. The optimized WIN32s version took 126 seconds,
a significant improvement. Systems with faster disk subsystems should see
an even better relative performance of the 32-bit version.

\chapter{Writing documents with Tex2RTF}\index{LaTeX}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\section{Why use \LaTeX?}

\LaTeX\ happens to be a very convenient format if you need to produce
documents (such as manuals, help facilities, up-to-date information) in
both printed and on-line media. Being a language rather than a WYSIWYG system,
it allows explicit specification of layout and document structure, lending
itself well to hypertext applications and automatic document generation.
Many people also prefer to use \LaTeX\ for ordinary use since it encourages
a logical document structure and the user is not distracted by having to perfect
the appearance; many layout decisions are taken by \LaTeX\ automatically.

Although \LaTeX\ is not as fancy as modern word processors and desk-top
publishing packages, it is for many purposes quite adequate, and sometimes
more flexible than its modern counterparts.

The conversion utility gives \LaTeX\ a new lease of life by allowing
virtually all other wordprocessor formats to be generated from documents
containing a reasonable subset of \LaTeX\ syntax. From the same \LaTeX\ 
sources, we can now generate printed manuals, Windows Help files, \popref{wxHelp}{wxhelp}\rtfsp
files, RTF-compatible word processor formats such as MS Word, and \popref{HTML}{html}\rtfsp
files for use in the World Wide Web. Since the conversion tool is
free, as are \LaTeX, HTML viewers, wxHelp and (effectively) Windows
Help, there are no financial or time penalties for providing
documentation in a wide range of printed and hypertext formats.

\section{Help versus the printed page}\index{on-line help}%

The purist may argue, quite rightly, that on-line help systems and
printed manuals have different characteristics; help windows tend to be
much smaller than pages, help topics should be more stand-alone than
pages in a manual, navigation methods are very different, etc. Therefore,
help systems should be {\it based} on printed documentation but
separately hand-crafted into hypertext help, preferably by an
independent person or team.

This might be the ideal, but many organisations or individuals simply
do not have the time: on-line help wouldn't get done if the
documentation effort had to be doubled. However, Tex2RTF does provide
some commands to allow tailoring the documentation to printed or
on-line form, such as \verb$\helponly$ and \verb$\helpignore$. An awareness
of the design issues should go a long way to making the compromise
a good one, so a book such as {\it Developing On-line Help for Windows} \cite{helpbook} is highly recommended.

\section{Output Formats}\index{output formats}%

At present the following output formats are supported:

\begin{itemize}
\itemsep=0pt
\item RTF (Rich Text Format)\index{RTF}. This is the most well developed
converter. RTF is commonly used as a document exchange format amongst
Windows-based applications, and is the input for the Windows Help
Compiler. Tex2RTF supports both linear documents and Windows Help
hypertext format.
\item HTML (Hypertext Markup Language)\index{HTML}. This an SGML-based format
commonly used by documents in the World Wide Web distributed hypertext
system, and formats text dynamically rather like Windows Help.
\item wxHelp\index{wxHelp}. This is the platform-independent help system for
the class library wxWidgets (see the wxWidgets User Manual \cite{smart93a}).
It can display ASCII files with embedded codes
for changing font styles, but no formatting is done by wxHelp.
\end{itemize}

\section{What compromises must I make?}\index{compromises}\index{LaTeX}%

As a \LaTeX\ user, you need to be aware that some commands or facilities
don't transfer to other formats, either because they are not supported
by the target format or because the converter does not support them. 
Maths formatting is a good example of an unsupported feature.

Sometimes \LaTeX\ facilities must be accessed in a slightly different
way to support the variety of formats, particularly hypertext formats
where \LaTeX\ references are often replaced by hypertext jumps (but must
still look right in printed documentation). Tables don't transfer well
to RTF and HTML (and not at all to wxHelp) but an attempt is made
to approximate tables so long as special row commands are used, instead
of the usual end of row delimiter.

Bibliographies are handled quite well since the utilities can read in\rtfsp
{\tt .bib} files and resolve citations. Numbers are used in citations;
the references are not yet sorted alphabetically.

Pictures\index{pictures} are handled in a limited way: if the PSBOX\index{PSBOX} macro package is
used, an \verb$\image$ command can be used to place Encapsulated PostScript
files in \LaTeX, and Windows RGB-encoded bitmap files or placeable
metafiles when converting to RTF.

Nested file inclusion\index{file inclusion} is handled with \verb$\input$, \verb$\include$ and \verb$\verbatiminput$,
and the comment environment is supported. However, using \verb$\input$\rtfsp
to include macro packages is not advisable. If you do this,
make sure you add a line in the Tex2RTF initialisation file to ignore
this file, unless it's a simple \LaTeX\ file that conforms to Tex2RTF
restrictions. The file {\tt psbox.tex} is the only file ignored
by Tex2RTF by default.

Because of the way \LaTeX\ is parsed, some syntax\index{syntax restrictions} has to conform to a
few simple rules. Commands such as \verb$\bf$ and \verb$\it$ need to occur
immediately after a left brace, and have a block of their own, since
the text within their scope is regarded as its argument. This syntax
means the same thing as using \verb$\begin ... \end$, which is usually
a one argument command (the argument is the text between the \verb$\begin$\rtfsp
and \verb$\end$). See \helpref{Space}{space}.

As a Windows hypertext help writer\index{on-line help}, you don't have access to all RTF
commands but you'll be able to get most of what you want. In particular,
any \LaTeX\ document you write will automatically be a hypertext
document, because the converter takes advantage of the hierarchy of
sections. Further jumps can be placed using the commands
\rtfsp\commandrefn{label}{label}, \commandrefn{helpref}{helpref},
\rtfsp\commandrefn{helprefn}{helprefn}, and \commandrefn{popref}{popref}.
Tex2RTF outputs help files that may be read linearly using the
\rtfsp$<<$ and $>>$ buttons, with an additional Up button for
ease of navigation.

When writing HTML, multiple files are generated from one \LaTeX\ file
since browsing HTML works best with many small files rather than a few
large ones.

wxHelp files are least well supported since there is no formatting
support, only font style, sizes and colours. Still, some hypertext help
support on UNIX/X platforms is better than none. wxHelp is now being rewritten (March 1996)
to use HTML files.

Sometimes you will use a local macro package that is unrecognised by
the converters. In this case, you may define a custom macro file
where macros are defined in terms of supported \LaTeX\ commands
and text. Even if the result is not the same as in \LaTeX, you
can probably end up with something adequate, and at least avoid
undefined macro errors. See \helpref{Initialisation file syntax}{inifile} for
further information.

\section{Changes to LaTeX syntax}

Here are the conventions you need to observe to satisfy the Tex2RTF
parser.

\subsection{Space}\label{space}\index{space}%

Tex2RTF attempts to insert spaces where \LaTeX\ assumes whitespace.
However, for the benefit of RTF conversion, you need to use the \commandrefn{rtfsp}{rtfsp} command
where a command or brace within a paragraph begins or ends with a macro. For example:

\begin{verbatim}
    Within a paragraph, you need to be careful about commands
    \rtfsp{\it that begin at the start of a line.}
\end{verbatim}

As normal with \LaTeX, two newlines represents a paragraph break,
although \commandrefn{par}{par} can also be used at the end of a paragraph.

You need to have a blank line between section and some environment
commands and the first paragraph or your document will look rather
weird, e.g. headings running into paragraphs.

wxHelp is more fussy than \LaTeX\ or RTF: you need to use percent
characters at line ends liberally to eliminate newlines after commands
on single lines.

\subsection{Command arguments}\index{LaTeX commands}%

Commands that have one or more arguments can be used in the following
three ways:

\begin{verbatim}
    \bf{Some text.}

    \begin{bf}
    Some text.
    \end{bf}

    {\bf Some text.}
\end{verbatim}

The first method is a normal \LaTeX\ command.

The second method is called an {\it environment}; \LaTeX\ has specific
environments that do not always correspond to normal commands, but
Tex2RTF recognizes environments and normal commands interchangeably, so
long as the command has no more than two arguments.

With the third method, it is important that the command has its own
pair of braces, and that the command immediately follows the first brace.
Otherwise, the parser cannot parse the argument(s) properly.
With multiple arguments, each should be enclosed in braces.

Optional arguments are specified using square brackets or parentheses.

The braces that start command arguments must not be separated from
the other arguments by whitespace. For example, the following produces
an error:

\begin{verbatim}
    \image{5cm;0cm}
    {picture.eps}
\end{verbatim}

and should be replaced by 

\begin{verbatim}
    \image{5cm;0cm}{picture.eps}
\end{verbatim}

\subsection{Avoid the setlength command}

Using the $\backslash$setlength command doesn't work, since its first
argument looks like a command with the wrong number of arguments. Use an
alternative form instead, e.g.

\begin{verbatim}
    \parindent 0pt
\end{verbatim}

instead of

\begin{verbatim}
    \setlength{\parindent}{0pt}
\end{verbatim}

\subsection{Units}\index{units}%

Only a subset of \LaTeX\ units may be used for specifying dimensions.
Valid units are {\tt pt, mm, cm} and {\tt in}. Units should usually
be specified for dimensions or the results may be unexpected.

\subsection{Labels}\index{labels}%

The \verb$\label$ command may be used for sections and figure captions,
but must come immediately after the section or caption commands with no
intervening whitespace.

\subsection{Tables}\label{tables}\index{tables}%

For best layout, table rows should be enclosed in a \verb$\row$\rtfsp
or \verb$\ruledrow$ command, since Tex2RTF can't cope with parsing
the \LaTeX\ tabular syntax unaided. However, if you really don't want
to go through \LaTeX\ files inserting new syntax, set the {\it compatibility}\rtfsp
flag to TRUE in your {\tt tex2rtf.ini} file. In this mode, Tex2RTF tries to make
the best of a bad job, but the results won't be optimal (e.g., no table
borders). Without this flag set, normal \LaTeX\ tables can crash RTF readers
such as Word for Windows.

\section{Tex2RTF for non-LaTeX users}\index{LaTeX}%

You don't need to have \LaTeX\ installed to use Tex2RTF. You
can still output RTF files to be imported into your favourite
word processor, and hypertext files for on-line help.

This chapter gives a very brief introduction to \LaTeX. For further
information, Kopka and Daly's {\it A Guide to \LaTeX} \cite{kopka} is
recommended.

\subsection{What is \LaTeX?}

\LaTeX\ is a macro package built on top of the typesetting package,
\TeX. \TeX\ was written by Donald Knuth in the 1970s, and Leslie
Lamport wrote \LaTeX\ as a higher-level, easier way to write \TeX.

\TeX\ was quite advanced for its day, and is still used (particularly by
academics) because of its free availability and its flexibility in
typesetting maths and other symbols. It's more like a programming
language than a word processor, with embedded commands prefixed by a
backslash and block structure. Like programs, \TeX\ documents are
processed by a `compiler', outputting a .dvi file, which is a device
independent file which can be read by many converters for output
onto physical devices, such as screens and printers.

A reason for its longevity is the ability to add facilities to
\TeX, using macro packages that define new commands.

\LaTeX\ is the most popular way to write \TeX. Although WYSIWYG
word processors and DTP packages are outstripping \LaTeX, the increasing
interest in hypertext and mark-up languages makes \LaTeX\ relevant as
a similar language to SGML documents (such as World Wide Web HTML files).

Also, languages such as \LaTeX\ (and Rich Text Format, which it resembles
in many ways) are {\it complementary} to WYSIWYG packages. These languages
allow automatic production and translation of documents, where manual
mark-up is impractical or undesirable.

Since the source code of \TeX\ and \LaTeX\ is in the public domain,
there are many free and commercial implementations of \LaTeX\ for almost
every computer in existance. Of PC implementations, EmTeX is arguably
the best and most complete. You can download it from various FTP sites.

If you don't want to use \LaTeX\ itself, you may wish to use a program
called lacheck to check your documents before using Tex2RTF, since it
catches some mistakes that Tex2RTF doesn't.

\subsection{Document structure}

Here is a sample of a typical \LaTeX\ document:

\begin{verbatim}
    \documentstyle[a4,texhelp]{report}
    \title{A title}
    \author{Julian Smart}
    \date{October 1993}
    \begin{document}
    \maketitle

    \chapter{Introduction}

    ...

    \section{A section}

    ...

    \end{document}
\end{verbatim}

The first line is always a \verb$\documentstyle$ command. The square brackets
enclose optional {\it style} files (suffix {\tt .sty}) that alter the appearance
of the document or provide new commands, and the curly brackets enclose
the mandatory style, in this case `report'.

Before the document begins properly with \verb$\begin{document}$,
you can write various commands that have an effect on the appearance of the
document or define title page information. The \verb$\maketitle$ command
writes the title page using information defined previously (title, author,
date).

A report has chapters, which are divided into sections, and can be further
divided into subsections and subsubsections. To start a new section, you
write the appropriate section command with the section heading; there is
no specific end section command, since a new section heading or the end
of the document will indicate the end of the previous section.

An article is divided into sections, subsections and subsubsections, but
has no chapters. This is so an article can be included in a report as a chapter.

Tex2RTF is written to deal with reports best, so stick with the report
style if you can.

\subsection{Command syntax}

There are several kinds of commands in \LaTeX. Most involve a keyword
prefixed with a backslash. Here are some examples:

\begin{verbatim}
    \titlepage

    \centerline{This is a centred line}

    \begin{center}
    This is a centred
    paragraph
    \end{center}

    {\bf This is bold font}
\end{verbatim}

The first example has no arguments. The second has one argument. The third
example is an {\it environment} which uses the begin and end keywords instead
of a pair of braces to enclose an argument (usually one). The fourth is an example
of using a command within a pair of braces: the command applies to the scope within
the braces. Tex2RTF treats this form as if it were a command with one argument,
with the right brace delimiting the argument. In this case, the command must
immediately follow a left brace as shown.

Commands may be nested, but not overlapped.

\subsection{Space}\index{space}%

In \LaTeX, white space is mostly ignored, line breaks make no difference.
However, \LaTeX\ interprets two successive newlines (a blank line) as
denoting a paragraph break. You may also use the \verb$\par$ command to end
a paragraph.

\section{Hypertext features}\index{hypertext}%

\LaTeX\ is inherently suitable for specifying hypertext documents since
it encourages description of the logical structure of a document using
section commands. Therefore, a \LaTeX\ document is automatically
a hypertext document, without any further editing.

For Windows Help, a single RTF file is generated with topics
corresponding to sections. A top level contents page shows each chapter
or top-level section, and each chapter or section ends with a list of
further sections or subsections. Tex2RTF outputs help files that may be
read linearly using the \rtfsp$<<$ and $>>$ buttons.

Similarly, a single wxHelp XLP file is generated.

For HTML, a different file is generated for each section, since the
XMOSAIC browser works best with a large number of small files. The files
are named automatically based on the name of the output file, with the
contents page filename being formed from the output filename with {\tt
\_contents} appended to the name. If the truncateFilenames option is
begin used, then the contents page is just the root name, with a .htm
suffix. The conversion may result in the generation of several hundred
files for a large \LaTeX\  input file. 

To specify explicit jumps around a hypertext file, the \commandrefn{helpref}{helpref} command is
used. The first argument is the text to be displayed at the point of reference,
which will be highlighted in a hypertext file to allow jumping to a reference.
The second argument is the reference label (there should be a corresponding
\rtfsp\commandrefn{label}{label} command in the file, following a section or figure).

To use extra Tex2RTF features in proper \LaTeX, such as \verb$\helpref$\rtfsp
and the C++ and CLIPS class reference documentation features, include
the style file {\tt texhelp.sty}.

\section{Special sections}\index{special sections}%

The treatment of bibliography, glossary and index are worth special mention.

\subsection{Bibliography}\label{bibsection}\index{bibliography}%

Tex2RTF recognises standard \LaTeX\ bibliography files (usually with {\tt .bib} extension)
and resolves citations. The \commandrefn{bibliography}{bibliographycmd}\rtfsp
command reads the given {\tt .bib} file and includes a list of
references at that point in the input. Only numbered, unsorted
references are catered for at the moment, with no variation in
bibliography style. A {\bf References} heading is placed in the contents
section. Note that Tex2RTF must be run twice to ensure the citations are
resolved properly.

Tex2RTF can also cope with the \verb$\thebibliography$ environment, with \rtfsp 
\verb$\bibitem$ commands, so long as the text following the first \verb$\bibitem$\rtfsp 
argument is enclosed in braces as if it were a second argument.

\subsection{Glossary}\label{glossarysection}\index{glossary}%

Glossaries are formatted according to the following scheme.
The \commandrefn{helpglossary}{helpglossary} environment is used together with
the \commandrefn{gloss}{gloss} command for glossary entries. In \LaTeX\ this
is interpreted as a description list, and each glossary entry is an item.
In on-line help, each glossary entry is a section.

A labelled glossary entry command may be referenced by \commandrefn{popref}{popref}\rtfsp 
to provide a quick popup explanation of a term.

\subsection{Index}\index{index}%

The explicit index is assumed to be redundant in on-line help, since
search facilities are provided. Therefore the \verb$\printindex$ command
does nothing in on-line versions. In linear RTF an index field is
added, and \commandrefn{index}{index} marks words for inserting in the index.

In Windows Help, all section headings and C++ function names are treated
as keywords. A keyword may be ambiguous, that is, refer to more than one
section in the help file.  This automatic indexing may not always be
adequate, so the \LaTeX\ \commandrefn{index}{index} command may be used
to add keywords.

In wxHelp, all section headings are indexed.

\section{Authoring HTML documents}

When an HTML document is generated, the suffix `\_contents' is appended
to the input file root. This will be the contents page for the document.
A number of further HTML files will be generated, possibly a large number
for a document with a large number of sections. If you are running
a 16-bit Windows version of Tex2RTF, you may wish to use
the {\it truncateFilenames} option to generate DOS filenames with
appropriately truncated references inside the HTML files.

\normalbox{Tip: to reduce the number of sections generated and make
the document more linear, you could define new chapter and section
commands. Alias them to the normal commands in real LaTeX (edit {\tt texhelp.sty}), and
to appropriate bold/large headings (but not section commands) in
the Tex2RTF initialisation file.}

Each HTML section file (except for the contents page) is given browse
buttons, similar to a Windows Help file: Contents, Up, Down, Back, Forward.
You can set {\it htmlBrowseButtons} to specify whether bitmaps or text should
be used for these buttons. On a text-only browser, the buttons will show
as text even if images have been specified.

As well as the usual jumps within a document, you can use the \commandref{urlref}{urlref} command to jump
to other documents. `Advanced features' which are implemented for HTML include:

\begin{itemize}\itemsep=0pt
\item Simple tables: \commandref{tabular}{tabular} command
\item Background colour/bitmap: \commandref{backgroundcolour}{backgroundcolour} and
\rtfsp\commandref{backgroundimage}{backgroundimage}
\item Text colour: \commandref{textcolour}{textcolour} command
\end{itemize}

See \helpref{HTML options}{htmloptions} for relevant initialisation file
switches.

\section{Authoring Windows Help documents}\index{WinHelp files}%

To produce a Windows Help file, you need to generate a WinHelp RTF file
with Tex2RTF and then invoke a Windows Help compiler (such as hc505.exe)
to translate this to a .hlp file.

WinHelp support has split into two streams, Windows 3.1 help format
and Windows 95 (WinHelp 4) format. You control this with the {\it winHelpVersion} option,
setting it to 3 for Windows 3.1, and 4 for Windows 95. In the latter case,
you also need the Help Compiler for Windows (hcw.exe and associated components)
which are available in the WIN32 SDK and with Windows 95 compilers.

Tex2RTF can produce a Windows 95 {\tt .cnt} file if {\it winHelpContents}\index{CNT file} is switched
on. This file is used to generate the new-style contents page, allowing
hierarchical browsing of the topic contents. In fact this file can be used
with ordinary Windows 3.1 files on Windows 95: so to hedge your bets,
generate a Windows 3.1 help file along with {\tt .cnt} file.

Tex2RTF also generates (optionally) a {\tt .hpj} (Help Project) file\index{HPJ file} which is
fed to the help compiler and specifies the RTF file being used amongst
other things. In WinHelp 4 mode, Tex2RTF adds entries to the project
to enhance the appearance of the help file. In particular, the
non-scrolling (topic title) region is coloured grey, and the rest
is coloured a light yellow in keeping with other Windows 95 help
files.

\normalbox{Tip: you can maintain two versions of a help file
by specifying an alternative {\tt .ini} file on the command
line when invoking Tex2RTF, and compiling to a different directory.
Tex2RTF instructs the help compiler to use the input file directory
to find bitmaps and metafiles, so using a different output directory
is not a problem.}

There is a slight wrinkle with generation of the {\tt .cnt} file:
to work around a `feature' in the Windows 95 help compiler, Tex2RTF may insert
extra book icons in the contents page. So your contents page
may not exactly match the structure in your LaTeX file.

`Advanced features' which are implemented for WinHelp include:

\begin{itemize}\itemsep=0pt
\item Transparency: \commandref{settransparency}{settransparency} command
\item Colour: \commandref{definecolour}{definecolour}, \commandref{fcol}{fcol}, \commandref{bcol}{bcol} commands
\item Hot spot appearance: \commandref{sethotspotcolour}{sethotspotcolour}, \commandref{sethotspotunderline}{sethotspotunderline} commands
\end{itemize}

Tex2RTF automatically generates browse buttons for jumping to the
above, previous and next topics. 

See \helpref{RTF/WinHelp options}{rtfwinhelpoptions} for
relevant initialisation file switches.

\section{Authoring linear RTF documents}\index{RTF}%

Linear RTF documents come in two main flavours. It can produce simple
RTF that can be read by a wide variety of readers, such as
Windows 95 WordPad, the Windows 95 viewer, and most word processors.
Tex2RTF can also output MS Word compatible RTF which has special
fields for contents page and index formatting, headings, and
other enhancements.

Use the {\it useWord} initialisation file flag to switch Word mode
on or off.
Hypertext links (using \verb$\helpref$ and other commands) will be formatted as
bold `anchor' text plus a section or figure number in parentheses.

In Word mode, using an index section generates a proper Word index.
Similarly, a Word table of contents, list of figures, list of tables
and page reference may be generated.

See \helpref{RTF/WinHelp options}{rtfwinhelpoptions} for
relevant initialisation file switches.

\section{Authoring wxHelp documents}\index{wxHelp}%

The wxHelp (.xlp) file is the most basic kind of file that Tex2RTF
can handle. Since spacing is passed through to the output, you need to
format your input document appropriately, with lines of reasonable length.

The generated xlp file is an ASCII file that can be read directly by
wxHelp, the generic wxWidgets help viewer.

\chapter{Command reference}\index{command reference}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

The following lists commands which are recognised by the converters. The reader
can assume that commands not mentioned here are unrecognised or ignored.

Each command is listed with its name, the number of arguments it takes
(excluding optional arguments), and a description. Note that if the
command is used as an environment (using \verb$\begin$ and \verb$\end$) then
the number of arguments must be either one or two. For example, the\rtfsp
\verb$\tabular$ environment takes two arguments: a first argument for
specifying the formatting, and the second argument for the body of the
environment.

\begin{verbatim}
    \begin{tabular}{|l|l|}
    \row{One&Two}
    \row{Three&Four}
    \end{tabular}
\end{verbatim}

\section{\LaTeX\ Commands}

\subsection*{abstract:1}\label{abstract}

This standard \LaTeX\ environment prepares an abstract page, and is
treated as an ordinary chapter or section in on-line help.

\subsection*{addcontentsline:3}\label{addcontentsline}

Adds a chapter title to the contents page. Linear RTF. Rarely required.

%\subsection*{appendix}
%\subsection*{arabic}
%\subsection*{array}
\subsection*{author:1}\label{author}

Defines the author, for output when \verb$\maketitle$ is used.

\subsection*{backslash:0}\label{backslash}

Outputs a backslash in math mode (should be enclosed by two dollar symbols).

\subsection*{bf:1}\label{bf}

Specifies bold font.

\subsection*{bffamily:1}\label{bffamily}

Specifies bold font.

\subsection*{bibitem:2}\label{bibitem}

For parsing convenience, \verb$\bibitem$ requires two arguments: a cite key and item.
\rtfsp\LaTeX\ syntax permits writing this as if it were two arguments,
even though it is in fact only one. This command is used within
a \commandrefn{thebibliography}{thebibliography} environment. The preferred
method is to store references in {\tt .bib} files and use the \commandrefn{bibliography}{bibliographycmd}\rtfsp
command to generate a bibliography section automatically.

\subsection*{bibliographystyle:1}\label{bibliographystyle}

Currently doesn't affect the style of bibliography, but probably will
in the future.

\subsection*{bibliography:0}\label{bibliographycmd}

Includes the bibliography at this point in the document. See the section
on \helpref{bibliographies}{bibsection}.

%\subsection*{caption*}
\subsection*{caption:1}\label{caption}

Specifies a caption (within a \commandrefn{figure}{figure} or \commandrefn{table}{table} environment). This may
be followed immediately by a \commandrefn{label}{label} command.

\subsection*{cdots:0}\label{cdots}

Outputs three dots.

\subsection*{centerline:1}\label{centerline}

Centres (or centers!) a line of text.

%\subsection*{centering}
\subsection*{center:1}\label{center}

Centres a block of text.

\subsection*{chapter:1}\label{chapter}

Outputs a chapter heading. If the chapter's name is Popups\index{popups}, the chapter title will not be
put in the contents, to allow popups to be placed in a document without the popup
sections being directly accessible.

\subsection*{chapter*:1}\label{chaptersX}

Outputs a chapter heading with no contents entry.

\subsection*{cite:1}\label{cite}

Cite a reference. The argument is a reference key as defined in a \LaTeX\ {\tt .bib}\rtfsp
file.

\subsection*{comment:1}\label{comment}

An environment that allows large comments in \LaTeX\ files: the argument
is ignored in all formats. Useful for commenting out parts of files that
cannot be handled by \LaTeX, such as the picture environment. See also\rtfsp
\commandrefn{toocomplex}{toocomplex}.

\subsection*{date:1}\label{date}

Specifies the date of a document; only output by \commandrefn{maketitle}{maketitle}.

\subsection*{description:1}\label{description}

A list environment, where each \commandrefn{item}{item} command must be
followed by optional square-bracketed text which will be highlighted.

%\subsection*{destruct:1}\label{destruct}

\subsection*{document:1}\label{document}

This environment should enclose the body of a document.

\subsection*{documentstyle:1}\label{documentstyle}

Specifies the main style (report, article etc.) and, optionally, style files
such as {\tt texhelp.sty}. A report has \commandrefn{chapters}{chapter}, while an article's top-level
sections are specified using \commandrefn{section}{section}.

%\subsection*{doublespace}\label{doublespace}
\subsection*{em:1}\label{em}

Emphasizes text (italic in RTF).

\subsection*{emph:1}\label{emph}

Same as \commandrefn{em}{em}.

\subsection*{enumerate:1}\label{enumerate}

Enumerate list environment: numbers the \commandrefn{items}{item}.

%\subsection*{equation}\label{equation}
%\subsection*{evensidemargin}
%\subsection*{fbox:1}\label{fbox}

\subsection*{figure:1}\label{figure}

A figure environment: does nothing special, except allows interpretation of
embedded \helpref{caption}{caption} commands as figures rather than (say) tables.

\subsection*{flushleft:1}\label{flushleft}

Flushes the given text to the left margin.

\subsection*{flushright:1}\label{flushright}

Flushes the given text to the right margin.

%\subsection*{footheight}\label{footheight}
\subsection*{footnote:1}\label{footnote}

In linear RTF, a footnote is created. Whether this appears at the end of
the section or the bottom of the page appears to depend on the current
document style, at least for MS Word 6.0 for Windows. The default seems
to be to put the footnotes at the end of the section, which is probably
not the best assumption.

In WinHelp RTF, a bracketed number is generated for the footnote
and the footnote becomes a popup topic. It is probably preferable
to change footnote commands to \commandref{footnotepopup}{footnotepopup},
or \commandref{popref}{popref} references to glossary entries.

This command is not supported for formats other than \LaTeX,
linear RTF and WinHelp RTF.

\subsection*{hline:0}\label{hline}

Within a \commandrefn{tabular}{tabular} environment, draws a horizontal
rule below the current row. Note that this does not work in RTF for the
last row of a table, in which case the command \commandrefn{ruledrow}{ruledrow}\rtfsp
should be used instead.

\subsection*{hrule:0}\label{hrule}

Draws a horizontal line below the current paragraph. For example:

\begin{verbatim}
    This paragraph should have a horizontal rule following it.\hrule
\end{verbatim}

gives:

This paragraph should have a horizontal rule following it.\hrule

%\subsection*{hspace*}\label{hspaceX}
%\subsection*{hspace}\label{hspace}
%\subsection*{hskip*}\label{hskipX}
%\subsection*{hskip}\label{hskip}

\subsection*{huge:1}\label{huge1}

Outputs the argument in huge text.

\subsection*{Huge:1}\label{Huge2}

Outputs the argument in huger text than \commandrefn{huge}{huge1}.

\subsection*{HUGE:1}\label{HUGE3}

Outputs the argument in huger text than \commandrefn{Huge}{Huge2}.

\subsection*{include:1}\label{include}

Include the given file. The command must not be preceded by any whitespace,
and spurious whitespace between elements of the command will also
trip up Tex2RTF.

\subsection*{index:1}\label{index}

In WinHelp mode, adds a keyword to the keyword list for the current
topic. This keyword must currently be straight text, with no embedded
commands. The conversion process must be run twice (without quitting
Tex2RTF inbetween) to resolve the keyword references.

\subsection*{input:1}\label{input}

Include the given file. The command must not be preceded by any whitespace,
and spurious whitespace between elements of the command will also
trip up Tex2RTF.

\subsection*{insertatlevel:2}\label{insertatlevel}

Insert some text at a particular level of the document. For example,

\begin{verbatim}
  \insertatlevel{2}{Some text}
\end{verbatim}

inserts "Some text" at level 2 (for a report, the current section). This
allows you to insert headings into an automatically-generated section contents,
for example.

\subsection*{it:1}\label{it}

Marks the argument in italic.

\subsection*{itemize:1}\label{itemize}

Indents each \commandrefn{item}{item} of a list and precedes with a bullet.
If the file {\tt bullet.bmp} is found by Tex2RTF, this bitmap will be
used as the bullet (WinHelp RTF); otherwise, a symbol or bold `o' will be used instead,
depending on output format.

Use \commandrefn{itemsep}{itemsep} to specify the separation between
list items. Currently this only works for linear or WinHelp RTF output.
If the value is more than zero, an extra paragraph is inserted.

\subsection*{item:0}\label{item}

Marks an item of a \commandrefn{itemize}{itemize}, \commandrefn{description}{description} or \commandrefn{enumerate}{enumerate}
list. Items within a description environment should have an `optional' argument
in square brackets which will be highlighted.

\subsection*{itemsep:0}\label{itemsep}

Use this command to specify the separation between
list items. Currently this only works for linear or WinHelp RTF output.
If the value is zero, no extra paragraph is inserted; if the value
is more than zero, an extra paragraph is inserted.

\subsection*{itshape:1}\label{itshape}

Marks the argument in italic.

%\subsection*{kill}\label{kill}
\subsection*{label:1}\label{label}

Labels the chapter, section, subsection, subsubsection or figure caption
with the given label. This must be an ASCII string, and duplicate items
with different case letters are not allowed.

The command must follow immediately after the section or caption command,
with no intervening whitespace.

\subsection*{large:1}\label{large1}

Marks the argument in large text.

\subsection*{Large:1}\label{Large2}

Makes the argument display in larger text than \commandrefn{large}{large1}.

\subsection*{LARGE:1}\label{LARGE3}

Makes the argument display in larger text than \commandrefn{Large}{Large2}.

\subsection*{LaTeX:0}\label{LaTeX}

Outputs the annoying \LaTeX\ upper and lower case name.

\subsection*{ldots:0}\label{ldots}

Outputs three dots.

%\subsection*{linebreak}\label{linebreak}
%\subsection*{listoffigures}\label{listoffigures}
%\subsection*{listoftables}\label{listoftables}
%\subsection*{makeglossary}\label{makeglossary}
%\subsection*{makeindex}\label{makeindex}
\subsection*{maketitle:0}\label{maketitle}

Makes the article or report title by outputting the \commandrefn{title}{title},
\rtfsp\commandrefn{author}{author} and optionally \commandrefn{date}{date}.

%\subsection*{markright}\label{markright}
%\subsection*{markboth}\label{markboth}

\subsection*{marginparwidth:1}\label{marginparwidth}

Specifies the width of a margin paragraph.

\subsection*{marginpar:1}\label{marginpar}

Inserts a marginal note. It is best to use the Tex2RTF extensions \rtfsp
\commandrefn{marginparodd}{marginparodd} and \commandrefn{marginpareven}{marginpareven} \rtfsp
for best results.

\subsection*{marginpareven:1}\label{marginpareven}

Inserts a marginal note on even pages. This is required for RTF generation since
it is impossible for Tex2RTF to know in advance which side of paper the marginal note
will fall upon, and the text has to be positioned using absolute dimensions.
If only one sided output is required, use \commandrefn{marginparodd}{marginparodd} \rtfsp
instead.

\subsection*{marginparodd:1}\label{marginparodd}

Inserts a marginal note on odd pages. This is required for RTF generation since
it is impossible for Tex2RTF to know in advance which side of paper the marginal note
will fall upon, and the text has to be positioned using absolute dimensions.

Also, even if one-sided output is required, this command should be used instead
of \verb$\marginpar$ because the \LaTeX\ command allows it to be used
just before a paragraph. Normally, if this were done, the marginal note would
not be aligned with the paragraph succeeding it. For example:

\begin{verbatim}
    \marginparodd{{\it Note:} if nothing happens, perhaps you
    have not plugged your computer in at the mains.}%
    To start using your computer, push the Power button
    and wait for text to appear on the screen.
\end{verbatim}

Note the percent sign after the \verb$\marginparodd$ command: without it,
\LaTeX\ refuses to believe that the following text is part of the
same paragraph, and will print the note at the wrong place.

You should use \commandrefn{textwidth}{textwidth} to allow space for marginal
notes, and also \commandrefn{marginparwidth}{marginparwidth} to specify the size of
the marginal note.

In WinHelp, HTML and wxHelp, marginal notes are treated as normal text delineated
with horizontal rules above and below.

%\subsection*{mbox:1}\label{mbox}

\subsection*{mdseries:1}\label{mdseries}

Changes to a medium-weight font. Un-emboldens in RTF mode, no effect in other modes.

\subsection*{multicolumn:3}\label{multicolumn}

Used in \commandrefn{tabular}{tabular} environment to denote a cell that
spans more than one column. Only supplied for compatibility with
existing \LaTeX\ files, since all it does in RTF is output the correct
number of cell commands, with the multicolumn text squashed into one cell.

\subsection*{newcommand:3}\label{newcommand}

Define a new command; arguments are the command, the number of
arguments, and the command body. For example:

\begin{verbatim}
    \newcommand{\crazy}[2]{{\bf #1} is crazy but {\bf #2} is not.}
\end{verbatim}

The command must have no whitespace at the start of the line or between
the three arguments.

New commands may also be defined in the {\tt tex2rtf.ini} file using
slightly different syntax (see \helpref{Macro not found error}{macronotfound}).

%\subsection*{newcounter}\label{newcounter}
%\subsection*{newline}\label{newline}
\subsection*{newpage:0}\label{newpage}

Inserts a page break.

\subsection*{nocite:1}\label{nocite}

Specifies that this reference should appear in the bibliography,
but the citation should not appear in the text.

See also \commandrefn{cite}{cite}.

\subsection*{noindent:0}\label{noindent}

Sets paragraph indentation to zero. See also \commandrefn{parindent}{parindent}.

%\subsection*{nolinebreak}\label{nolinebreak}
%\subsection*{nopagebreak}\label{nopagebreak}

\subsection*{normalsize:1}\label{normalsize}

Sets the font size back to normal.

\subsection*{onecolumn:0}\label{onecolumn}

Sets the number of columns to one. \LaTeX\ and linear RTF only.

%\subsection*{oddsidemargin}\label{oddsidemargin}
%\subsection*{pagebreak}\label{pagebreak}
\subsection*{pageref:1}\label{pageref}

In linear RTF, generates a page reference to the given label.

\subsection*{pagestyle:1}\label{pagestyle}

If argument is {\tt fancyplain} or {\tt fancy}, Tex2RTF
separates the header from the rest of the page with a rule.
This command must be defined for headers and footers to
work properly. See also \commandrefn{setheader}{setheader},
\commandrefn{setfooter}{setfooter}.

\LaTeX\ and linear RTF only.

\subsection*{pagenumbering:1}\label{pagenumbering}

The argument may be one of:

\begin{description}
\itemsep=0pt
\item[alph] a, b, ...
\item[Alph] A, B, ...
\item[arabic] 1, 2, ...
\item[roman] i, ii, ...
\item[Roman] I, II, ...
\end{description}

\LaTeX\ and linear RTF only.

\subsection*{paragraph:0}\label{paragraph}

Behaves as for a subsubsection.

\subsection*{paragraph*:0}\label{paragraphX}

Behaves as for a subsubsection.

\subsection*{parindent:1}\label{parindent}

Indents the first line of succeeding paragraphs by the given amount.

\subsection*{parskip:1}\label{parskip}

Changes the spacing between paragraphs. In fact, in RTF this will cause
two \commandrefn{par}{par} commands to be output if parskip is greater
than zero.

%\subsection*{part*}\label{partX}
%\subsection*{part}\label{part}
\subsection*{par:0}\label{par}

Causes the paragraph to end at this point. \LaTeX\ and Tex2RTF also
treat two consecutive newlines as a paragraph break.

%\subsection*{pfunc}\label{pfunc}
%\subsection*{picture}\label{picture}
\subsection*{printindex:0}\label{printindex}

In linear RTF, inserts an index.

\subsection*{quote:1}\label{quote}

Indents a short quotation.

\subsection*{quotation:1}\label{quotation}

Indents a long quotation.

%\subsection*{raggedbottom}\label{raggedbottom}
%\subsection*{raggedleft}\label{raggedleft}
%\subsection*{raggedright}\label{raggedright}

\subsection*{ref:1}\label{ref}

In \LaTeX\ and linear RTF, refers to a \commandrefn{label}{label} and
causes the number of that section or figure to be printed.

\subsection*{rm:1}\label{rm}

Causes the argument to be formatted in a plain, roman font.
In fact, does nothing in RTF, HTML and XLP modes.

\subsection*{rmfamily:1}\label{rmfamily}

Causes the argument to be formatted in a plain, roman font.
In fact, does nothing in RTF, HTML and XLP modes.

%\subsection*{roman}\label{roman1}
%\subsection*{Roman}\label{Roman2}

\subsection*{sc:1}\label{sc}

Prints the output in small capitals.

\subsection*{scshape:1}\label{scshape}

Prints the output in small capitals.

\subsection*{section:1}\label{section}

Section header, with an entry in the contents page.

\subsection*{section*:1}\label{sectionX}

Section header, with no entry in the contents page.

%\subsection*{setcounter}\label{setcounter}
\subsection*{sf:1}\label{sf}

Should format in a sans-serif font. Does nothing in Tex2RTF.

\subsection*{sffamily:1}\label{sffamily}

Should format in a sans-serif font. Does nothing in Tex2RTF.

\subsection*{shortcite:1}\label{shortcite}

The same as \commandrefn{cite}{cite}.

%\subsection*{singlespace}\label{singlespace}
%\subsection*{sloppypar}\label{sloppypar}
%\subsection*{sloppy}\label{sloppy}

\subsection*{sl:1}\label{sl}

In Tex2RTF, the same as \commandrefn{it}{it}. The LaTeX interpretation is `slanted text'.

\subsection*{slshape:1}\label{slshape}

In Tex2RTF, the same as \commandrefn{itshape}{itshape}. The LaTeX interpretation is `slanted text'.

\subsection*{small:1}\label{small}

Prints the argument in a small font.

\subsection*{special:1}\label{special}

Simply copies the argument to the output file without processing
(except \verb$\}$ is translated to \verb$}$, and \verb$\{$ is
translated to \verb${$, to allow for insertion of braces).

\subsection*{ss:0}\label{ss}

Outputs the German sharp S character \ss.

%\subsection*{subitem}\label{subitem}
\subsection*{subparagraph:1}\label{subparagraph}

Behaves as for a subsubsection.

\subsection*{subparagraph*:1}\label{subparagraphX}

Behaves as for a subsubsection.

\subsection*{subsection:1}\label{subsection}

Subsection header, with an entry in the contents page. 

\subsection*{subsection*:1}\label{subsectionX}

Subsection header, with no entry in the contents page. 

\subsection*{subsubsection:1}\label{subsubsection}

Subsubsection header, with an entry in the contents page. 

\subsection*{subsubsection*:1}\label{subsubsectionX}

Subsubsection header, with no entry in the contents page. 

\subsection*{tabbing:1}\label{tabbing}

Tabbing environment: doesn't work properly in RTF.

\subsection*{table:1}\label{table}

An environment for tables. The only thing that Tex2RTF does with this
is to interpret an embedded \helpref{caption}{caption} command differently
from figures.

\subsection*{tableofcontents:0}\label{tableofcontents}

Inserts the table of contents at this point. In linear RTF mode, a
proper Word for Windows table of contents will be inserted unless either
of the variables {\it insertTOC} or {\it useWord} is set to {\it false}.

\subsection*{tabular:2}\label{tabular}

Tabular environment: an attempt is made to output something
reasonable in RTF and HTML formats, although currently only simple
tables will work. The first argument specifies the column formatting.
a pipe symbol (\verb$|$) denotes a vertical border, one of {\tt l, r, c}\rtfsp
signifies a normal column of default width, and {\tt p} followed by
a dimension specifies a column of given width. It is recommended that
the {\tt p} is used since Tex2RTF cannot deduce a column width in the
same way that \LaTeX\ can.

Horizontal rules are achieved with \commandrefn{hline}{hline}; two together
signify a double rule. Note that in HTML, all rows and the table itself are bordered
automatically.

Use the Tex2RTF \commandrefn{row}{row} and \commandrefn{ruledrow}{ruledrow} commands
for best effect.

For two-column tables that work in WinHelp files, use \commandrefn{twocollist}{twocollist} instead.

Example:

\begin{verbatim}
    \begin{tabular}{|l|p{8.5cm}|}\hline
    \row{{\bf A.I.}&{\bf Simulation}}\hline\hline
    \row{rules&constraints/methods}
    \row{planning&design of experiments}
    \row{diagnosis&analysis of results}
    \ruledrow{learning&detection of connections}
    \end{tabular}
\end{verbatim}

This produces:

\begin{tabular}{|l|p{8.5cm}|}\hline
\row{{\bf A.I.}&{\bf Simulation}}\hline\hline
\row{rules&constraints/methods}
\row{planning&design of experiments}
\row{diagnosis&analysis of results}
\ruledrow{learning&detection of connections}
\end{tabular}

%\subsection*{tab:1}\label{tab}
\subsection*{TeX:0}\label{TeX}

Outputs the annoying \TeX\ upper and lower case name.

\subsection*{textbf:1}\label{textbf}

Same as \commandrefn{bf}{bf}.

\subsection*{textit:1}\label{textit}

Same as \commandrefn{it}{it}.

\subsection*{textrm:1}\label{textrm}

Same as \commandrefn{rm}{rm}.

\subsection*{textsf:1}\label{textsf}

Same as \commandrefn{sf}{sf}.

\subsection*{textsc:1}\label{textsc}

Same as \commandrefn{sc}{sc}.

\subsection*{textsl:1}\label{textsl}

Same as \commandrefn{sl}{sl}.

\subsection*{texttt:1}\label{texttt}

Same as \commandrefn{tt}{tt}.


\subsection*{textwidth:1}\label{textwidth}

Sets the text width (valid for RTF only). This might be used
in conjunction with \commandrefn{marginpar}{marginpar}, for example,
to leave space for marginal notes.

%\subsection*{textheight}\label{textheight}
\subsection*{thebibliography:1}\label{thebibliography}

An environment for specifying the bibliography as a series of\rtfsp
\commandrefn{bibitem}{bibitem} commands; the preferred method is to use
\rtfsp{\tt .bib} files and \commandrefn{bibliography}{bibliographycmd} instead.

%\subsection*{titlepage:0}\label{titlepage}

\subsection*{title:1}\label{title}

Sets the title, to be output when the command \commandrefn{maketitle}{maketitle}\rtfsp
is used.

\subsection*{tiny:1}\label{tiny}

Prints the argument in a very small font.

\subsection*{today:0}\label{today}

Outputs today's date.

%\subsection*{topmargin}\label{topmargin}
%\subsection*{topskip}\label{topskip}
\subsection*{tt:1}\label{tt}

Outputs the argument in teletype font.

\subsection*{ttfamily:1}\label{ttfamily}

Outputs the argument in teletype font.

%\subsection*{typein}\label{typein}
\subsection*{typeout:1}\label{typeout}

Outputs the text on the Tex2RTF text window.

\subsection*{twocolumn:0}\label{twocolumn}

Sets the number of columns to two. \LaTeX\ and linear RTF only.

\subsection*{underline:1}\label{underline}

Underlines the argument.
  
\subsection*{upshape:1}\label{upshape}

Changes to an upright font. Un-italicizes in RTF mode, no effect in other modes.

\subsection*{verbatiminput:1}\label{verbatiminput}

Include the given file as if it were within a \commandrefn{verbatim}{verbatim}\rtfsp
environment. The command must not be preceded by any whitespace,
and spurious whitespace between elements of the command will also
trip up Tex2RTF.

\subsection*{verbatim:1}\label{verbatim}

Uses a fixed-width font to format the argument without interpreting
any \LaTeX\ commands.

\subsection*{verb}\label{verb}

The \verb$\verb$ command is like the \commandref{verbatim}{verbatim} environment,
but for small amounts of text. The syntax is:

\begin{verbatim}
    \verb<char><text><char>
\end{verbatim}

The character {\it char} is used as a delimiter; it may be any character
not ocurring in the following text, except asterisk.

For example, \verb@\verb$\thing%^&$@ produces \verb$\thing%^&$.

%\subsection*{verse}\label{verse}
%\subsection*{vfill}\label{vfill}
%\subsection*{vline}\label{vline}
%\subsection*{void}\label{void}
%\subsection*{vrule}\label{vrule}
%\subsection*{vspace*}\label{vspaceX}
%\subsection*{vskip*}\label{vskipX}
%\subsection*{vspace}\label{vspace}
%\subsection*{vskip}\label{vskip}


\section{Tex2RTF Commands}

\subsection*{backgroundcolour:1}\label{backgroundcolour}

Specifies the page background colour, in HTML only. The argument consists
of three numbers from 0 to 255 separated by semicolons, for red, green and blue values respectively.

\begin{verbatim}
    \backgroundcolour{255;255;255}
    \backgroundcolour{0;0;255}
\end{verbatim}

The first example sets the background to white, the second sets the background to blue.

Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
setting, {\it backgroundColour}.

\subsection*{backgroundimage:1}\label{backgroundimage}

Specifies the page background image, in HTML only. The argument
is a URL for the GIF file to be used as the background.

For example:

\begin{verbatim}
    \backgroundimage{tile.gif}
\end{verbatim}

This sets the background to a tile file.

Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
setting, {\it backgroundImage}.

\subsection*{backslashraw:0}\label{backslashraw}

Outputs a raw backslash into the output (not LaTeX). Useful when
inserting RTF (for example) that cannot be dealt with by Tex2RTF.
E.g.

\begin{verbatim}
    \backslashraw{'e3}
\end{verbatim}

inserts the text \verb$\'e3$ into the RTF file.

\subsection*{bcol:2}\label{bcol}

Sets the background colour for a block of text (RTF only). Has no known effect
in the RTF readers currently tried (Word for Window and Windows Help).

See also \commandrefn{definecolour}{definecolour}, \commandrefn{fcol}{fcol}.

%\subsection*{baselineskip}
%\subsection*{boxit:1}\label{boxit}

\subsection*{brclear:0}\label{brclear}

Stops aligning content following a left or right-aligned image in HTML only.

See also \commandrefn{imagel}{imagel}, \commandrefn{imager}{imager}.

\subsection*{cextract:0}\label{cextract}

Prints a C++ extraction operator (\cextract).

\subsection*{chapterheading:1}\label{chapterheading}

Like \commandrefn{chapter}{chapter}, but does not increment the chapter
number and does not print a chapter number in the printed documentation
contents page, or in the chapter heading. Used to implement \helpref{glossaries}{glossarysection} and
other sections that are not real chapters.

\subsection*{cinsert:0}\label{cinsert}

Prints a C++ insertion operator (\cinsert).

\subsection*{class:1}\label{class}

Outputs the argument, an index entry (\LaTeX\ only) and a keyword entry (WinHelp only).
Used in class reference documentation.

%\subsection*{cleardoublepage}
%\subsection*{clearpage}
%\subsection*{cline}
\subsection*{clipsfunc:3}\label{clipsfunc}

Formats a CLIPS function, given the return value, function name, and
arguments.

%\subsection*{columnsep}
\subsection*{copyright:0}\label{copyright}

Outputs the copyright symbol.

\subsection*{cparam:2}\label{cparam}

Formats a CLIPS type and argument. Used within the third argument of
a \commandrefn{clipsfunc}{clipsfunc} command.

\subsection*{definecolour:4}\label{definecolour}

Defines a new colour that can be used in the document (RTF only). This
command can also be spelt \verb$\definecolor$.

The first argument is the lower-case name of the colour, and the following
three arguments specify the red, green and blue intensities, in the range 0 to 255.

The default colours are equivalent to the following definitions:

\begin{verbatim}
    \definecolour{black}{0}{0}{0}
    \definecolour{cyan}{0}{255}{255}
    \definecolour{green}{0}{255}{0}
    \definecolour{magenta}{255}{0}{255}
    \definecolour{red}{255}{0}{0}
    \definecolour{yellow}{255}{255}{0}
    \definecolour{white}{255}{255}{255}
\end{verbatim}

To use colours in a document, use the \commandrefn{fcol}{fcol} and \commandrefn{bcol}{bcol} commands.

Note that a document that defines its own colours should be converted twice within
the same Tex2RTF session.

\subsection*{fcol:2}\label{fcol}

Sets the foreground colour for a block of text (RTF and HTML).

For example:

\begin{verbatim}
    This sentence is brightened up by some \fcol{red}{red text}.
\end{verbatim}

gives:

This sentence is brightened up by some \fcol{red}{red text}.

See also \commandrefn{definecolour}{definecolour}, \commandrefn{bcol}{bcol}.

\subsection*{followedlinkcolour:1}\label{followedlinkcolour}

Specifies the followed link colour for the whole page, HTML only. The argument consists
of three numbers from 0 to 255 separated by semicolons, for red, green and blue values respectively.

For example:

\begin{verbatim}
    \followedlinkcolour{255;255;255}
    \followedlinkcolour{0;0;255}
\end{verbatim}

The first example sets the followed link text to white, and the second sets the followed link text to blue.

See also \commandrefn{backgroundcolour}{backgroundcolour}, \commandrefn{textcolour}{textcolour},
\rtfsp\commandrefn{linkcolour}{linkcolour}.

Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
setting, {\it followedLinkColour}.

\subsection*{footnotepopup:2}\label{footnotepopup}

In linear RTF, a footnote is created following the first argument, as with
\commandref{footnote}{footnote}.

In WinHelp RTF, a the first argument is highlighted and becomes
a popup reference to the second argument. See also \commandref{footnote}{footnote}\rtfsp
and \commandref{popref}{popref}.

This command is not supported for formats other than \LaTeX,
linear RTF and WinHelp RTF.

%\subsection*{footskip}\label{footskip}
%\subsection*{framebox:1}\label{framebox}

\subsection*{functionsection:1}\label{functionsection}

Defines a subsection, adding the C++ function name to the \LaTeX\ index or the
WinHelp keyword list.

Should be followed by a \commandrefn{func}{func} command to specify function
details.

\subsection*{func:3}\label{func}

Defines a C++ function, given the return type, function name, and parameter list.

Should occur after a \commandrefn{functionsection}{functionsection} command.

%\subsection*{glossary:}\label{glossary}
\subsection*{gloss:1}\label{gloss}

Marks a glossary entry. In \LaTeX, this is a synonym for an \commandrefn{item}{item}
with an optional argument, within a \commandrefn{description}{description} environment,
and the argument is added to the index.

In Windows Help, this is identical to a \commandrefn{section*}{sectionX} in a report.

If labels are associated with the glossary entries, they can be referenced by
\commandref{helpref}{helpref} or \commandref{popref}{popref} jumps. A glossary entry is
currently the only type of destination that popref may refer to.

This is an example of making a glossary in a report:

\begin{verbatim}
    \begin{helpglossary}

    \gloss{API}\label{api}

    Application Programmer's Interface - a set of calls and
    classes defining how a library (in this case, wxWidgets)
    can be used.

    \gloss{Canvas}\label{canvas}

    A canvas in XView and wxWidgets is a subwindow...

    \gloss{DDE}\label{dde}

    Dynamic Data Exchange - Microsoft's interprocess
    communication protocol. wxWidgets provides an abstraction
    of DDE under both Windows and UNIX.

    \end{helpglossary}
\end{verbatim}

%\subsection*{headheight}\label{headheight}
\subsection*{helpglossary:1}\label{helpglossary}

An environment for making a glossary (not standard \LaTeX). See \commandrefn{gloss}{gloss} for
usage.

\subsection*{helpignore:1}\label{helpignore}

Ignores the argument in Tex2RTF generated files, but not \LaTeX.

\subsection*{helponly:1}\label{helponly}

Only outputs the argument in Tex2RTF generated files.

\subsection*{helpinput:1}\label{helpinput}

Only includes the given file in Tex2RTF generated files.

\subsection*{helpfontfamily:1}\label{helpfontfamily}

Specifies the font family for Tex2RTF generated files. The argument
may be Swiss or Times.

\subsection*{helpfontsize:1}\label{helpfontsize}

Specifies the font size for Tex2RTF generated files.

\subsection*{helpref:2}\label{helpref}

Specifies a jump to a labelled chapter, section, subsection subsubsection
or figure.

The first argument is text to be highlighted (mouseable in help systems)
and the second is the reference label. In linear documents, the section number
is given following the text, unless the \commandrefn{helprefn}{helprefn} command
is used instead, where the section number is suppressed.

Note that when generating HTML, the label {\it contents} is automatically defined,
and may be referenced using \verb$\helpref$.

\subsection*{helprefn:2}\label{helprefn}

Specifies a jump to a labelled chapter, section, subsection subsubsection
or figure.

The first argument is text to be highlighted (mouseable in help systems)
and the second is the reference label.  See \commandrefn{helpref}{helpref} for
the form where the section number is printed in linear documents.

%\subsection*{hfill}\label{hfill}
\subsection*{htmlignore:1}\label{htmlignore}

Ignores the argument in HTML.

\subsection*{htmlonly:1}\label{htmlonly}

Only outputs the argument in HTML.

\subsection*{image:2}\label{image}

This is translated to a PSBOX macro package \verb$\psboxto$ command in \LaTeX,
the first argument being a sizing command and the second a filename.

In HTML mode, the second argument is used to generate a PostScript file reference.

In RTF mode, the second argument is tried with first a BMP extension and
then a WMF extension to find a suitable Windows bitmap file, placeable
metafile, or segmented hypergraphics file (.SHG). If a suitable file is
found, in Windows Help mode a {\tt bmc}\rtfsp command is inserted into
the RTF file with a reference to the file. In linear RTF mode, the
bitmap or metafile is converted into hex and inserted into the RTF
document.

Note that only RGB-encoded Windows bitmaps, or placeable metafiles, are
valid for input to Tex2RTF. You can convert a RLE (run length encoded)
bitmap file into a (bigger) RGB file using a program such as Paintshop
Pro. A placeable metafile has a special header with dimension
information. One may be constructed by a wxWidgets program by calling
the function wxMakeMetafilePlaceable. The Microsoft Windows SDK has a
sample program that loads and steps through placeable and ordinary
metafiles.

Another wrinkle is that programs differ in the methods they
use to recognise pictures in RTF files. You may need to use the {\it bitmapMethod} setting,
which can be ``hex'' (embed the hex data in the file with a \verb$\dibitmap$ keyword),
``includepicture'' (use the MS Word 6.0 INCLUDEPICTURE field) or ``import''
(an earlier name for INCLUDEPICTURE).

Here is an example of using the \verb$\image$ command.

\begin{verbatim}
    \begin{figure}
    $$\image{5cm;0cm}{heart.ps}$$

    \caption{My picture}\label{piccy}
    \end{figure}
\end{verbatim}

The dollars centre the image in the horizontal plane. The syntax
of the first argument to \verb$\image$ is taken from syntax used by the \verb$\psbox$\rtfsp
package: it allows specification of the horizontal and vertical
dimensions of the image. Scaling will take place for PostScript
and metafile images. A value of zero indicates that the image should
be scaled in proportion to the non-zero dimension. Zeros for both
dimensions will leave the image unscaled in the case of metafiles,
or scaled to fit the page in the case of PostScript.

See also \commandrefn{imagel}{imagel}, \commandrefn{imager}{imager} for aligned images in
HTML.

\subsection*{imagel:2}\label{imagel}

Similar to \commandrefn{image}{image}, but left-aligns the image with respect to the following
content. Use \commandrefn{brclear}{brclear} to stop aligning the content to the right of the image.

See also \commandrefn{imager}{imager}.

\subsection*{imagemap:3}\label{imagemap}

This is translated to an HTML image map reference, or (in LaTeX) a PostScript psbox
command. This allows images in HTML to have hotspots, where the user clicks on a
part of the image and the browser jumps to a particular file.

The first argument is the same as the first argument to the \commandref{image}{image}\rtfsp
command (ignored in HTML). The second argument must be the name of the
image map entry, and the second is the filename to be displayed inline.

\begin{verbatim}
    \imagemap{}{tree.gif}{myname}
\end{verbatim}

translates to:

\begin{verbatim}
    <a href="/cgi-bin/imagemap/mymap">
      <img src="tree.gif" ismap></a><p>
\end{verbatim}

The snag with this is that, apart from the inconvenience of having to
register a map file with the server, the map file will also have
references to particular HTML files. If they exist in the current
document, these names are not known until the file is generated. In which case, the
map entries should probably refer to symbolic links that can be easily
changed later.

\subsection*{imager:2}\label{imager}

Similar to \commandrefn{image}{image}, but right-aligns the image with respect to the following
content. Use \commandrefn{brclear}{brclear} to stop aligning the content to the left of the image.

See also \commandrefn{imagel}{imagel}.

%\subsection*{includeonly}\label{includeonly}
\subsection*{indented:2}\label{indented}

Environment supplied by Tex2RTF to allow (possibly nested) indentation of
\LaTeX\ and RTF text. The first argument is the amount to be indented.

For example:

\begin{verbatim}
    \begin{indented}{2cm}
    This text should be indented by a couple of centimetres.
    This can be useful to highlight paragraphs.
    \end{indented}
\end{verbatim}

produces:

\begin{indented}{2cm}
This text should be indented by a couple of centimetres. This can be
useful to highlight paragraphs.
\end{indented}

\subsection*{latexignore:1}\label{latexignore}

Ignores the argument in \LaTeX.

\subsection*{latexonly:1}\label{latexonly}

Only prints the argument in \LaTeX.

%\subsection*{lbox}\label{lbox}

\subsection*{lbraceraw:0}\label{lbraceraw}

Outputs a raw left brace into the output (not LaTeX). Useful when
inserting RTF (for example) that cannot be dealt with by Tex2RTF.

\subsection*{linkcolour:1}\label{linkcolour}

Specifies the link colour for the whole page, HTML only. The argument consists
of three numbers from 0 to 255 separated by semicolons, for red, green and blue values respectively.

For example:

\begin{verbatim}
    \linkcolour{255;255;255}
    \linkcolour{0;0;255}
\end{verbatim}

The first example sets the link text to white, and the second sets the link text to blue.

See also \commandrefn{backgroundcolour}{backgroundcolour}, \commandrefn{textcolour}{textcolour},
\rtfsp\commandrefn{followedlinkcolour}{followedlinkcolour}.

Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
setting, {\it linkColour}.

\subsection*{membersection:1}\label{membersection}

Used when formatting C++ classes to print a subsection for the member name.

\subsection*{member:1}\label{member}

Used to format a C++ member variable name.

\subsection*{normalbox:1}\label{normalbox}

Draws a box around the given paragraph in \LaTeX\ and RTF. In HTML
and XLP formats, horizontal rules are drawn before and after the text.

For example:

\begin{verbatim}
    \normalbox{This should be a boxed paragraph for highlighting
    important information, such as information for registering
    a shareware program.}
\end{verbatim}

gives:

\normalbox{This should be a boxed paragraph for highlighting important
information, such as information for registering a shareware program.}

See also \commandrefn{normalboxd}{normalboxd} for double-bordered text.

\subsection*{normalboxd:1}\label{normalboxd}

Draws a double border around the given paragraph in \LaTeX\ and RTF. In
HTML and XLP formats, horizontal rules are drawn before and after the
text.

For example:

\begin{verbatim}
    \normalboxd{This should be a boxed paragraph for
    highlighting important information, such as information
    for registering a shareware program.}
\end{verbatim}

gives:

\normalboxd{This should be a boxed paragraph for highlighting important
information,such as information for registering a shareware program.}

See also \commandrefn{normalbox}{normalbox} for single-bordered text.

\subsection*{param:1}\label{param}

Formats a C++ type and argument pair. Should be used within the third argument
of a a \commandrefn{func}{func} command.

\subsection*{popref:2}\label{popref}

Similar to \commandrefn{helprefn}{helprefn}, except that in Windows Help,
the destination text is popped up in a small window to be dismissed with
a mouse click, instead of going to a separate section.

Currently this command can only refer to a labelled glossary entry; see
\commandrefn{gloss}{gloss}.

\subsection*{psboxto:2}\label{psboxto}

Identical to \commandrefn{image}{image}.

%\subsection*{psbox}\label{psbox}
\subsection*{rbraceraw:0}\label{rbraceraw}

Outputs a raw right brace into the output (not LaTeX). Useful when
inserting RTF (for example) that cannot be dealt with by Tex2RTF.

\subsection*{registered:0}\label{registered}

Outputs the `registered' symbol in HTML, and (r) in other formats.

\subsection*{row:1}\label{row}

A Tex2RTF command signifying the row of a table within the \commandrefn{tabular}{tabular}\rtfsp
environment. See also \commandrefn{ruledrow}{ruledrow}.

\subsection*{ruledrow:1}\label{ruledrow}

A Tex2RTF command signifying a ruled row of a table within the \commandrefn{tabular}{tabular}\rtfsp
environment. See also \commandrefn{row}{row}.

\subsection*{rtfignore:1}\label{rtfignore}

Ignores the argument in linear RTF.

\subsection*{rtfonly:1}\label{rtfonly}

Only outputs the argument in linear RTF.

\subsection*{rtfsp:0}\label{rtfsp}

Outputs a space in RTF. Tex2RTF tries to insert a space where one is implied
by a newline, but cannot cope where a line starts or ends with a command,
in the middle of a paragraph. Use this command to insert a space explicitly.

\subsection*{sectionheading:1}\label{sectionheading}

Like \commandrefn{section}{section}, but does not increment the section
number and does not print a section number in the printed documentation
contents page, or in the section heading.

\subsection*{setfooter:6}\label{setfooter}

Tex2RTF has a non-standard way of setting headers and footers,
but the default macro definitions in {\tt texhelp.sty} may be altered
to your current method.

The arguments are as follows:

\begin{enumerate}
\itemsep=0pt
\item Left footer, even pages
\item Centre footer, even pages
\item Right footer, even pages
\item Left footer, odd pages
\item Centre footer, odd pages
\item Right footer, odd pages
\end{enumerate}

For many documents, the first three arguments will be left empty.

The behaviour for first pages of a chapter, section or document
is to have a blank header, but print the footer.

For best results, define headers and footers for {\it each chapter or
section}.

Note that this command works only for \LaTeX\ and linear RTF. See also\rtfsp
\commandrefn{setheader}{setheader}.

\subsection*{setheader:6}\label{setheader}

Tex2RTF has a non-standard way of setting headers and footers,
but the default macro definitions in {\tt texhelp.sty} may be altered
to your current method.

The arguments are as follows:

\begin{enumerate}
\itemsep=0pt
\item Left header, even pages
\item Centre header, even pages
\item Right header, even pages
\item Left header, odd pages
\item Centre header, odd pages
\item Right header, odd pages
\end{enumerate}

For many documents, the first three arguments will be left empty.
If \commandrefn{pagestyle}{pagestyle} is not plain or empty, the
header will separated from the rest of the page by a rule.

The behaviour for first pages of a chapter, section or document
is to have a blank header, but print the footer.

For best results, define headers and footers for {\it each chapter or
section}.

Note that this command works only for \LaTeX\ and linear RTF. See also\rtfsp
\commandrefn{setfooter}{setfooter}.

\subsection*{sethotspotcolour:1}\label{sethotspotcolour}

If the argument is yes, on or ok, subsequent WinHelp hotspots will be green.
If any other value, the hotspots will be the normal text colour. Note that this
doesn't apply to section hotspots, only to helpref hotspots.

\subsection*{sethotspotunderline:1}\label{sethotspotunderline}

If the argument is yes, on or ok, subsequent WinHelp hotspots will be
underlined (the default). If any other value, the hotspots will not be
underlined. Note that this doesn't apply to section hotspots, only to
helpref hotspots.

\subsection*{settransparency:1}\label{settransparency}

WinHelp mode only (version 4 of WinHelp). If the argument is yes, on or ok, subsequent bitmaps
will be inserted in transparent mode: areas of white will be made transparent.
If the argument is any other value (such as no, ok or false), the bitmaps will not be transparent.

\subsection*{textcolour:1}\label{textcolour}

Specifies the text foreground colour for the whole page, HTML only. The argument consists
of three numbers from 0 to 255 separated by semicolons, for red, green and blue values respectively.

For example:

\begin{verbatim}
    \textcolour{255;255;255}
    \textcolour{0;0;255}
\end{verbatim}

The first example sets the text to white, and the second sets the text to blue.

See also \commandrefn{backgroundcolour}{backgroundcolour}, \commandrefn{linkcolour}{linkcolour},
\rtfsp\commandrefn{followedlinkcolour}{followedlinkcolour}.

Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
setting, {\it textColour}.

\subsection*{toocomplex:1}\label{toocomplex}

An environment for dealing with complex \LaTeX\ commands that
Tex2RTF cannot handle. In normal \LaTeX, the argument will be output
as normal. In Tex2RTF output, the argument will be output as verbatim text,
for the user to hand-translate into the desired output format.

See also \commandrefn{comment}{comment}.

\subsection*{twocolitem:2}\label{twocolitem}

Used to specify a row for a two column list, a Tex2RTF
extension to optimize two-column lists for different
file formats.  See \commandrefn{twocollist}{twocollist},
\rtfsp\commandrefn{twocolitemruled}{twocolitemruled}.

\subsection*{twocolitemruled:2}\label{twocolitemruled}

Used to specify a ruled row for a two column list, a Tex2RTF
extension to optimize two-column lists for different
file formats.  See \commandrefn{twocollist}{twocollist},
\rtfsp\commandrefn{twocolitem}{twocolitem}.

\subsection*{twocollist:1}\label{twocollist}

A Tex2RTF environment for specifying a table of two columns, often
used in manuals and help files (for example, for listing commands and
their meanings). The first column should be one line only, and
the second can be an arbitrary number of paragraphs.

The reason that a normal tabular environment cannot be used is that
WinHelp does not allow borders in table cells, so a different method
must be employed if any of the rows are to be ruled. In \LaTeX, a table
is used to implement this environment. In RTF, indentation is used instead.

Use this environment in conjunction with \commandrefn{twocolitem}{twocolitem} and\rtfsp
\commandrefn{twocolitemruled}{twocolitemruled}. To set the widths of the first
and second column, use \commandrefn{twocolwidtha}{twocolwidtha} and\rtfsp
\commandrefn{twocolwidthb}{twocolwidthb}.

Example:

\begin{verbatim}
    \htmlignore{\begin{twocollist}}
    \twocolitemruled{{\bf Command}}{{\bf Description}}
    \twocolitem{File}{The file menu is used to select various
    file-related operations, such as saving and loading.}
    \twocolitem{Edit}{The Edit menu is used for
    selection, copying, pasting, etc.}
    \end{twocollist}
\end{verbatim}

This produces:

\begin{twocollist}
\twocolitemruled{{\bf Command}}{{\bf Description}}
\twocolitem{File}{The file menu is used to select various file-related
operations, such as saving and loading.}
\twocolitem{Edit}{The Edit menu is used for selection, copying, pasting, etc.}
\end{twocollist}

\subsection*{twocolwidtha:1}\label{twocolwidtha}

Sets the width of the first column in a two column list to the given
dimension. See also \commandrefn{twocollist}{twocollist} and \commandrefn{twocolwidthb}{twocolwidthb}.

\subsection*{twocolwidthb:1}\label{twocolwidthb}

Sets the width of the second column in a two column list to the given
dimension. See also \commandrefn{twocollist}{twocollist} and \commandrefn{twocolwidtha}{twocolwidtha}.

\subsection*{urlref:2}\label{urlref}

Specifies a jump to a URL (univeral resource location).

The first argument is text to be highlighted (mouseable in HTML browsers)
and the second is the URL. In linear documents, the URL
is given following the text.

Example:

\begin{verbatim}
    See also the \urlref{wxWidgets manual}
      {http://www.aiai.ed.ac.uk/~jacs.html}.
\end{verbatim}

(the line is broken only to keep to this manual's page width).

\subsection*{winhelpignore:1}\label{winhelpignore}

Ignores the argument in WinHelp RTF.

\subsection*{winhelponly:1}\label{winhelponly}

Only outputs the argument in WinHelp RTF.

\subsection*{xlpignore:1}\label{xlpignore}

Ignores the argument in XLP mode (wxHelp files).

\subsection*{xlponly:1}\label{xlponly}

Only outputs the argument in XLP mode (wxHelp files).

\section{Accents}\label{accents}

The following \LaTeX\ accents work for RTF and HTML production:

\begin{itemize}%
\itemsep=0pt
\item \verb$\'{a}$ produces \'{a}. Valid for a, e, i, o, u, A, E, I, O, U
\item \verb$\`{a}$ produces \`{a}. Valid for a, e, i, o, u, y, A, E, I, O, U, Y
\item \verb$\^{a}$ produces \^{a}. Valid for a, e, i, o, u, A, E, I, O, U
\item \verb$\~{a}$ produces \~{a}. Valid for a, n, o, A, N, O
\item \verb$\"{a}$ produces \"{a}. Valid for a, e, i, o, u, y, A, E, I, O, U, Y
\item \verb$\.{a}$ produces \.{a}. Valid for a, A
\end{itemize}

\section{Commands by category}\index{commands}%

Below are categories of \LaTeX\ commands, to help you find the right
command for a particular purpose.

\subsection{Font commands}

\begin{itemize}\itemsep=0pt
\item \commandpageref{bf}{bf}
\item \commandpageref{bffamily}{bffamily}
\item \commandpageref{em}{em}
\item \commandpageref{emph}{emph}
\item \commandpageref{huge}{huge1}
\item \commandpageref{Huge}{Huge2}
\item \commandpageref{HUGE}{HUGE3}
\item \commandpageref{it}{it}
\item \commandpageref{itshape}{itshape}
\item \commandpageref{large}{large1}
\item \commandpageref{Large}{Large2}
\item \commandpageref{LARGE}{LARGE3}
\item \commandpageref{mdseries}{mdseries}
\item \commandpageref{normalsize}{normalsize}
\item \commandpageref{rm}{rm}
\item \commandpageref{rmfamily}{rmfamily}
\item \commandpageref{sc}{sc}
\item \commandpageref{scshape}{scshape}
\item \commandpageref{sf}{sf}
\item \commandpageref{sffamily}{sffamily}
\item \commandpageref{sl}{sl}
\item \commandpageref{slshape}{slshape}
\item \commandpageref{small}{small}
\item \commandpageref{textbf}{textbf}
\item \commandpageref{textit}{textit}
\item \commandpageref{textrm}{textrm}
\item \commandpageref{textsf}{textsf}
\item \commandpageref{textsc}{textsc}
\item \commandpageref{textsl}{textsl}
\item \commandpageref{texttt}{texttt}
\item \commandpageref{tiny}{tiny}
\item \commandpageref{tt}{tt}
\item \commandpageref{ttfamily}{ttfamily}
\item \commandpageref{underline}{underline}
\item \commandpageref{upshape}{upshape}
\end{itemize}

\subsection{Paragraph formatting}

\begin{itemize}\itemsep=0pt
\item \commandpageref{centerline}{centerline}
\item \commandpageref{comment}{comment}
\item \commandpageref{flushleft}{flushleft}
\item \commandpageref{footnote}{footnote}
\item \commandpageref{indented}{indented}
\item \commandpageref{marginparwidth}{marginparwidth}
\item \commandpageref{marginpar}{marginpar}
\item \commandpageref{marginpareven}{marginpareven}
\item \commandpageref{marginparodd}{marginparodd}
\item \commandpageref{multicolumn}{multicolumn}
\item \commandpageref{newpage}{newpage}
\item \commandpageref{noindent}{noindent}
\item \commandpageref{onecolumn}{onecolumn}
\item \commandpageref{parindent}{parindent}
\item \commandpageref{parskip}{parskip}
\item \commandpageref{par}{par}
\item \commandpageref{quote}{quote}
\item \commandpageref{quotation}{quotation}
\item \commandpageref{textwidth}{textwidth}
\item \commandpageref{twocolumn}{twocolumn}
\item \commandpageref{verbatim}{verbatim}
\item \commandpageref{verb}{verb}
\end{itemize}

\subsection{Special effects}

\begin{itemize}\itemsep=0pt
\item \commandpageref{backgroundcolour}{backgroundcolour}
\item \commandpageref{backgroundimage}{backgroundimage}
\item \commandpageref{backslashraw}{backslashraw}
\item \commandpageref{bcol}{bcol}
\item \commandpageref{definecolour}{definecolour}
\item \commandpageref{fcol}{fcol}
\item \commandpageref{followedlinkcolour}{followedlinkcolour}
\item \commandpageref{helpfontfamily}{helpfontfamily}
\item \commandpageref{helpfontsize}{helpfontsize}
\item \commandpageref{hrule}{hrule}
\item \commandpageref{linkcolour}{linkcolour}
\item \commandpageref{normalbox}{normalbox}
\item \commandpageref{normalboxd}{normalboxd}
\item \commandpageref{sethotspotcolour}{sethotspotcolour}
\item \commandpageref{sethotspotunderline}{sethotspotunderline}
\item \commandpageref{settransparency}{settransparency}
\item \commandpageref{textcolour}{textcolour}
\item \commandpageref{typeout}{typeout}
\end{itemize}

\subsection{Lists}

\begin{itemize}\itemsep=0pt
\item \commandpageref{description}{description}
\item \commandpageref{enumerate}{enumerate}
\item \commandpageref{itemize}{itemize}
\item \commandpageref{item}{item}
\item \commandpageref{itemsep}{itemsep}
\item \commandpageref{twocolitem}{twocolitem}
\item \commandpageref{twocolitemruled}{twocolitemruled}
\item \commandpageref{twocollist}{twocollist}
\item \commandpageref{twocolwidtha}{twocolwidtha}
\item \commandpageref{twocolwidthb}{twocolwidthb}
\end{itemize}

\subsection{Sectioning}

\begin{itemize}\itemsep=0pt
\item \commandpageref{chapter}{chapter}
\item \commandpageref{chapter*}{chaptersX}
\item \commandpageref{chapterheading}{chapterheading}
\item \commandpageref{insertatlevel}{insertatlevel}
\item \commandpageref{paragraph}{paragraph}
\item \commandpageref{paragraph*}{paragraphX}
\item \commandpageref{section}{section}
\item \commandpageref{section*}{sectionX}
\item \commandpageref{sectionheading}{sectionheading}
\item \commandpageref{subparagraph}{subparagraph}
\item \commandpageref{subparagraph*}{subparagraphX}
\item \commandpageref{subsection}{subsection}
\item \commandpageref{subsection*}{subsectionX}
\item \commandpageref{subsubsection}{subsubsection}
\item \commandpageref{subsubsection*}{subsubsectionX}
\end{itemize}

\subsection{Pictures}

\begin{itemize}\itemsep=0pt
\item \commandpageref{brclear}{brclear}
\item \commandpageref{image}{image}
\item \commandpageref{imagel}{imagel}
\item \commandpageref{imagemap}{imagemap}
\item \commandpageref{imager}{imager}
\item \commandpageref{psboxto}{psboxto}
\end{itemize}

\subsection{References and jumps}

\begin{itemize}\itemsep=0pt
\item \commandpageref{footnotepopup}{footnotepopup}
\item \commandpageref{helpref}{helpref}
\item \commandpageref{helprefn}{helprefn}
\item \commandpageref{label}{label}
\item \commandpageref{pageref}{pageref}
\item \commandpageref{popref}{popref}
\item \commandpageref{ref}{ref}
\item \commandpageref{urlref}{urlref}
\end{itemize}

\subsection{Tables and figures}

\begin{itemize}\itemsep=0pt
\item \commandpageref{caption}{caption}
\item \commandpageref{figure}{figure}
\item \commandpageref{hline}{hline}
\item \commandpageref{ruledrow}{ruledrow}
\item \commandpageref{tabbing}{tabbing}
\item \commandpageref{tabular}{tabular}
\end{itemize}

\subsection{Table of contents}

\begin{itemize}\itemsep=0pt
\item \commandpageref{addcontentsline}{addcontentsline}
\item \commandpageref{author}{author}
\item \commandpageref{date}{date}
\item \commandpageref{maketitle}{maketitle}
\item \commandpageref{tableofcontents}{tableofcontents}
\item \commandpageref{title}{title}
\end{itemize}

\subsection{Special sections}

\begin{itemize}\itemsep=0pt
\item \commandpageref{bibitem}{bibitem}
\item \commandpageref{bibliographystyle}{bibliographystyle}
\item \commandpageref{bibliography}{bibliographycmd}
\item \commandpageref{cite}{cite}
\item \commandpageref{gloss}{gloss}
\item \commandpageref{helpglossary}{helpglossary}
\item \commandpageref{index}{index}
\item \commandpageref{nocite}{nocite}
\item \commandpageref{printindex}{printindex}
\item \commandpageref{shortcite}{shortcite}
\item \commandpageref{thebibliography}{thebibliography}
\end{itemize}


\subsection{Symbols}

\begin{itemize}\itemsep=0pt
\item \commandpageref{backslash}{backslash}
\item \commandpageref{cdots}{cdots}
\item \commandpageref{cextract}{cextract}
\item \commandpageref{cinsert}{cinsert}
\item \commandpageref{copyright}{copyright}
\item \commandpageref{LaTeX}{LaTeX}
\item \commandpageref{lbraceraw}{lbraceraw}
\item \commandpageref{ldots}{ldots}
\item \commandpageref{rbraceraw}{rbraceraw}
\item \commandpageref{registered}{registered}
\item \commandpageref{rtfsp}{rtfsp}
\item \commandpageref{ss}{ss}
\item \commandpageref{TeX}{TeX}
\item \commandpageref{today}{today}
\end{itemize}

\subsection{Document organisation}

\begin{itemize}\itemsep=0pt
\item \commandpageref{document}{document}
\item \commandpageref{documentstyle}{documentstyle}
\item \commandpageref{helpignore}{helpignore}
\item \commandpageref{helponly}{helponly}
\item \commandpageref{helpinput}{helpinput}
\item \commandpageref{htmlignore}{htmlignore}
\item \commandpageref{htmlonly}{htmlonly}
\item \commandpageref{include}{include}
\item \commandpageref{input}{input}
\item \commandpageref{latexignore}{latexignore}
\item \commandpageref{latexonly}{latexonly}
\item \commandpageref{newcommand}{newcommand}
\item \commandpageref{pagestyle}{pagestyle}
\item \commandpageref{pagenumbering}{pagenumbering}
\item \commandpageref{rtfignore}{rtfignore}
\item \commandpageref{rtfonly}{rtfonly}
\item \commandpageref{setfooter}{setfooter}
\item \commandpageref{setheader}{setheader}
\item \commandpageref{special}{special}
\item \commandpageref{toocomplex}{toocomplex}
\item \commandpageref{verbatiminput}{verbatiminput}
\item \commandpageref{winhelpignore}{winhelpignore}
\item \commandpageref{winhelponly}{winhelponly}
\item \commandpageref{xlpignore}{xlpignore}
\item \commandpageref{xlponly}{xlponly}
\end{itemize}

\chapter{Bugs and troubleshooting}\label{errors}\index{bugs}\index{errors}\index{troubleshooting}%
\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\section{Bugs}

\begin{description}
\item[Command parsing.] If a command is used followed by inappropriate
argument syntax, Tex2RTF can crash. This an occur when a command is
used in an asterisk form that is only formed in the non-asterisk
variety. The non-asterisk form is assumed, which makes the following
asterisk trip up the parser.
\item[Setlength.] Using the $\backslash$setlength command doesn't work,
since its first argument looks like a command with the wrong number
of arguments. Use an alternative form instead, e.g. \verb$\parindent 0pt$ instead
of \verb$\setlength{parindent}{0pt}$.
\item[Newcommand bug.] Environments in a command definition confuse
Tex2RTF. Use the command form instead (e.g. $\backslash$flushleft\{...\} instead
of $\backslash$begin\{flushleft\} ... $\backslash$end\{flushleft\}.
\item[Bibliography.] There's no flexibility in the way references
are output: I expect I'll get round to doing something better,
but only if people tell me they need it!
\item[Tables.] Tables can't handle all \LaTeX\ syntax, and require
the Tex2RTF \verb$\row$ commands for decent formatting. Still, it's
better than it was (RTF only).
\item[Indexes and glossaries.] Not completely supported.
\item[Crashes.] Crashes may be due to an input file exceeding the fixed-size
buffer used for converting command arguments, especially for the \verb$\verbatim$\rtfsp
command. Use the {\tt -bufsize} switch to increase the buffer size.
\item[Verbatiminput.] Verbatiminput files which do not end with a blank line
can trip up following commands.
\end{description}

\section{Troubleshooting}

Below are some common problems and possible solutions.

\normalbox{Some of the syntax that is OK for true \LaTeX\ but which trips up
Tex2RTF, may be detected by the TCHECK program included in the tools
directory of the Tex2RTF distribution. Some \LaTeX\ errors may be picked up
by the LACHECK program, also found in the tools directory.}

\subsection{Macro not found}\label{macronotfound}\index{macro not found error}%

This error may indicate that Tex2RTF has not implemented a standard
\rtfsp\LaTeX\ command, or that a local macro package is being used that
Tex2RTF does not know about. It can cause spurious secondary
errors, such as not recognising the end document command.

You can get round this by defining a macro file (default name {\tt tex2rtf.ini})
containing command definitions, such as:

\begin{verbatim}
    \crazy      [2]{{\bf #2} is crazy but #1 is not}
    \something  [0]{}
    \julian     [0]{Julian Smart}
\end{verbatim}

New commands may be defined in \LaTeX\ files, but custom macro files
will have to be defined when local style files are being used. See\rtfsp
\helpref{Initialisation file syntax}{inifile} for further details.

The `Macro not found' error can also be caused by a syntax error such as
an unbalanced brace or passing the wrong number of arguments to a command,
so look in the vicinity of the reported error for the real cause.

Here is one obscure situation that causes this error:

\begin{verbatim}
    \begin{center}
    {\large{\underline{A}}}
    \end{center}
\end{verbatim}

The problem is too many curly brackets. This should be rewritten as:

\begin{verbatim}
    \begin{center}
    {\large \underline{A}}
    \end{center}
\end{verbatim}

Often you get a `Macro not found' error for \verb$\end{document}$. This
is a spurious side-effect of an earlier error, usually an incorrect number
of arguments to a command. The location of the true error is then anywhere
in the document. To home in on the error, try putting a verbatim environment
\rtfsp\verb$\begin{comment}...\end{comment}$ around much of the document,
and then move the \verb$\begin{comment}$ line down until the error
manifests itself.

\subsection{Unresolved reference}\index{references, unresolved}%

References and citations are usually resolved on a second pass of
Tex2RTF. If this doesn't work, then a missing label or bibliographical
entry is to blame.

\subsection{Output crashes the RTF reader}

This could be due to confusing table syntax. Set {\it compatibility} to\rtfsp
{\it TRUE} in {\tt .ini} file; also check for end of row characters backslash characters
on their own on a line, and insert correct number of ampersands for the number of
columns.  E.g.

\begin{verbatim}
    hello & world\\
    \\
\end{verbatim}

becomes

\begin{verbatim}
    hello & world\\
    &\\
\end{verbatim}

\subsection{Erratic list indentation}

Try increasing the value of the variable {\it listItemIndent} (default 40
points) to give more space between label and following text. A global
replacement of \verb$\item [$ with \verb$\item[$ may also be helpful to remove
unnecessary space before the item label.

\subsection{Missing figure or section reference}

Ensure all labels {\it directly} follow captions or sections (no intervening
white space).

\subsection{Linear RTF looks odd}

For viewing by programs other than MS Word, you should set the variable {\it useWord} to {\it false}. This
will turn off some of the special RTF keywords recognised by Word (and possibly other advanced RTF readers).

\subsection{Paragraphs preceding lists are formatted weirdly.}

If a list has spurious spacing in it, e.g. before a \verb$\item$ command, the preceding
paragraph can take on some of the list's indentation. This may be a WinHelp bug, or an aspect
of RTF I don't fully understand. The solution is to remove unnecessary space.

\subsection{Unresolved references in Word for Windows}\index{Microsoft Word}%

If question marks appear instead of numbers for figures and tables,
select all (e.g. CTRL-A), then press F9 {\it twice} to reformat the
document twice. For the second format, respond with {\it Update Entire
Table} to any prompts.

\subsection{The Windows 95 help file contents hierarchy looks wrong}\index{WinHelp files}%

WinHelp version 4 (or the WIN32 Help Compiler) does not allow a
book in the contents list to be followed by a page at the same level.
A book must be followed by a book, for some strange reason, otherwise
the page will be tacked on to the pages of the book above it, i.e. placed
at the wrong level.

To get around this, Tex2RTF inserts a book in some places, if there
was a book preceding it on the same level. This results in more
navigation than necessary, but is better than a wrong contents page.

\newpage

% Puts books in the bibliography without needing to cite them in the
% text
\nocite{smart93a}%
\nocite{kopka}%
\nocite{pfeiffer}%

\bibliography{refs}
\addcontentsline{toc}{chapter}{Bibliography}
\setheader{{\it REFERENCES}}{}{}{}{}{{\it REFERENCES}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\begin{helpglossary}
\setheader{{\it GLOSSARY}}{}{}{}{}{{\it GLOSSARY}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%

\gloss{GUI}

Graphical User Interface, such as Windows 3 or X.

\gloss{HTML}\label{html}

Hypertext Markup Language; an SGML document type, used for providing
hypertext information on the World Wide Web, a distributed hypertext
system on the Internet.

\gloss{LaTeX}\label{latexgloss}

A typesetting language implemented as a set of \TeX\ macros. It is
distinguished for allowing specification of the document structure,
while taking care of most layout concerns. It represents the opposite
end of the spectrum from WYSIWYG word processors.

\gloss{RTF}\label{rtf}

Rich Text Format: an interchange format for word processor files,
used for importing and exporting formatted documents, and as the
input to the Windows Help compiler.

\gloss{wxHelp}\label{wxhelp}

wxHelp is the hypertext help facility used to provide on-line
documentation for UNIX-based wxWidgets applications. Under Windows 3.1,
Windows Help is used instead.

\gloss{wxWidgets}\label{wxwidgets}

wxWidgets is a free C++ toolkit for writing applications that are
portable across several platforms. Currently these are Motif, Open Look,
Windows 3.1 and Windows NT. Tex2RTF is written using wxWidgets.

\end{helpglossary}

\addcontentsline{toc}{chapter}{Index}
\setheader{{\it INDEX}}{}{}{}{}{{\it INDEX}}%
\setfooter{\thepage}{}{}{}{}{\thepage}%
\printindex%

\end{document}