tex2rtf.tex

Wxpython Implemented on Windows CE, Source code

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}