tex2rtf.tex

Wxpython Implemented on Windows CE, Source code

\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