tex2rtf.tex

Wxpython Implemented on Windows CE, Source code

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. See the Tex2RTF {\tt src/makefile.dos} for an example
of maintaining both formats.}

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