
Manual for Tex2RTF 1.2:  a LaTEX to RTF and


                     HTML converter


                          Julian Smart

          Artificial Intelligence Applications Institute

                    University of Edinburgh

                            EH1 1HN
                          January 1994



Contents

1  Introduction                                                   4


   1.1 Why use LaTEX?   : : : : : : : : : : : : : : : : : : : : : : : : : : :  4


   1.2 Output Formats   : : : : : : : : : : : : : : : : : : : : : : : : : : :  5


   1.3 What compromises must I make?  : : : : : : : : : : : : : : : : : :  5


   1.4 Changes to LaTEX syntax   : : : : : : : : : : : : : : : : : : : : : :  6


       1.4.1 Space  : : : : : : : : : : : : : : : : : : : : : : : : : : : : :  6


       1.4.2 Command arguments   : : : : : : : : : : : : : : : : : : : :  7


       1.4.3 Avoid the setlength macro : : : : : : : : : : : : : : : : : :  7


       1.4.4 Labels  : : : : : : : : : : : : : : : : : : : : : : : : : : : : : *
 * 8



2  Hypertext features                                             9



3  Special sections                                               10


   3.1 Bibliography   : : : : : : : : : : : : : : : : : : : : : : : : : : : : :*
 * 10


   3.2 Glossary  : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : *
 *: 10


   3.3 Index   : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : *
 *: 10



4  Running Tex2RTF                                            12



5  Tex2RTF for non-LaTEX users                                  13


   5.1 What is LaTEX?  : : : : : : : : : : : : : : : : : : : : : : : : : : : : *
 *13


   5.2 Document structure   : : : : : : : : : : : : : : : : : : : : : : : : : 14


   5.3 Command syntax  : : : : : : : : : : : : : : : : : : : : : : : : : : : 15


   5.4 Space   : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : *
 *: 15

                                 1


6  Macro reference                                               16



7  Errors and bugs                                               31


   7.1 Errors  : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : *
 *: 31


       7.1.1 Macro not found  : : : : : : : : : : : : : : : : : : : : : : : 31


       7.1.2 Unresolved references   : : : : : : : : : : : : : : : : : : : : 31


   7.2 Bugs  : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : *
 *: 32



Glossary                                                         34

                                 2



Copyright  notice
Copyright (c) 1993 Julian Smart.


Permission to use, copy, modify, and distribute this software and its documen-
tation 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 WITH-
OUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FIT-
NESS FOR A PARTICULAR PURPOSE.


IN NO EVENT SHALL JULIAN SMART OR THE ARTIFICIAL INTELLI-
GENCE APPLICATIONS INSTITUTE OR UNIVERSITY OF EDINBURGH
BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSE-
QUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSO-
EVER 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.

                                 3



Chapter  1



Introduction
This document describes a utility for converting LaTEX files into several other
formats, and the C++ library which the converters rely on for parsing and other
services.


Only a subset of LaTEX can be processed by this utility, especially since the t*
 *arget
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.


Tex2RTF is heavily biased towards making on-line, hypertext versions of LaTEX
documents, but the RTF converter can be used for normal, linear documents
too.


The latest version of Tex2RTF can be accessed by anonymous ftp from skye.aiai.e*
 *d.ac.uk
(192.41.104.6) in the directory /pub/tex2rtf.  It is available in SPARC Open
Look and Windows 3.1 versions.


Tex2RTF was developed using the free Open Look/Motif/Windows 3.1 C++
class library wxWindows, also available from the above FTP site in the /pub/wxw*
 *in/beta
directory.

1.1    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 pub-
lishing packages, it is for many purposes quite adequate, and sometimes more
flexible than its modern counterparts.



                                 4


The conversion utility gives LaTEX a new lease of life by allowing virtually all
other wordprocessor formats to be generated from documents containing a rea-
sonable subset of LaTEX syntax. From the same LaTEX sources, we can now gen-
erate printed manuals, Windows Help files, wxHelpfiles, RTF-compatible word
processor formats such as MS Word, and HTMLfiles 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.

1.2    Output Formats



At present the following output formats are supported:



   o RTF (Rich Text Format). 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.

   o wxHelp.  This is the platform-independent help system for the class li-
     brary wxWindows [8]. It can display ASCII files with embedded codes for
     changing font styles, but no formatting is done by wxHelp.

   o HTML (Hypertext Markup Language). This an SGML-like format com-
     monly used by documents in the World Wide Web distributed hypertext
     system, and formats text dynamically rather like Windows Help.

1.3    What compromises must I make?



As a LaTEX user, you need to be aware that some macros 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. Examples of these are
the footnote macro, and all maths formatting.


Sometimes LaTEX facilities must be accessed in a slightly different way to supp*
 *ort
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 not at all to the other
formats) but an attempt is made to approximate tables so long as special row
macros are used, instead of the usual end of row delimiter.


Bibliographies are handled quite well since the utilities can read in .bib files
and resolve citations.  Bibliographies are not yet supported in Windows Help
files, and the references are not yet sorted alphabetically. Numbers are used in
citations.


Pictures are handled in a limited way: if the PSBOX macro package is used, an
image macro can be used to place Encapsulated PostScript files in LaTEX, and
Windows RGB-encoded bitmap files or placeable metafiles when converting to
RTF.



                                 5


Paragraph indentation is a little weak at present, but some is done automatical*
 *ly,
in list and quotation environments. More flexible control will be added later.


Nested file inclusion (input, include, verbatiminput), is handled, and the com-
ment environment is supported. However, using inputto include macro packages
is not advisable, although the psbox.tex package is ignored. In later versions,*
 * it
should be possible to specify files to ignore.


Because of the way LaTEX is parsed, some syntax has to conform to a few simple
rules.  Macros such as bf and 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 begin ... end, which is
usually a one argument macro (the argument is the text between the beginand
end). See Space (section 1.4.1).


As a Windows hypertext help writer, you don't have access to all RTF com-
mands 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 label, helpref, helprefn, and popref. Tex2RTF
outputs help files that may be read linearly using the << and >> buttons.


Similarly, HTML support is largely automatic, and 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. The class library wxWindows may be extended
in future to allow using a better help viewer, such as xmosaic. Of course there*
 * is
nothing to stop xmosaic being used as a help system, but it won't be integrated
with wxWindows programs as wxHelp is.


Sometimes you will use a local macro package that is unrecognised by the con-
verters.  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 Errors (section 7) for further
information.

1.4    Changes to LaTEX syntax



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



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

                                 6


Within a paragraph, you need to be careful about commands that begin
"rtfsp -"it at the start" of a line.



As normal with LaTEX, two newlines represents a paragraph break, although
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.
1.4.2   Command arguments



All commands that have more than one argument can be used in the following
three ways:



"begin-bf"
Some text.
"end-bf"


"bf-Some text."


-"bf Some text."



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.


Whitespace should be avoided between command names and their arguments.
1.4.3   Avoid the setlength macro



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



"parindent 0pt



instead of



$"backslash$setlength-$"backslash$parindent"-0pt"


                                 7


1.4.4   Labels



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


Chapter  2



Hypertext  features
LaTEX is inherently suitable for specifying hypertext documents since it encour-
ages 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 << 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 _contents appended to
the name. This may result in the generation of several hundred files for a large
LaTEX input file.


To specify explicit jumps around a hypertext file, the helpref macro 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 label
command in the file, following a section or figure).


To use extra features such as helpref and the C++ and CLIPS class reference
documentation features, include the style file texhelp.sty.
                                 9



Chapter  3



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

3.1    Bibliography



Tex2RTF recognises standard LaTEX bibliography files (usually with .bib exten-
sion) and resolves citations. The bibliographycommand reads the given .bib
file and includes a list of references at that point in the input. Only numbere*
 *d,
unsorted references are catered for at the moment, with no variation in bibli-
ography style. A References heading is placed in the contents section. Note
that Tex2RTF must be run twice to ensure the citations are resolved properly.

3.2    Glossary



Glossaries are formatted according to the following scheme. The helpglossary
environment is used together with the 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 poprefto provide a
quick popup explanation of a term.

3.3    Index



The explicit index is assumed to be redundant in on-line help, since search
facilities are provided. Therefore the printindex command does nothing in on-
line versions (nor in linear RTF). However, the automatic indexing of Tex2RTF
and the target help system may not always be adequate, so in a future release
the LaTEX index command may have some effect, and printindex may also be
used.

                                10


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.


In wxHelp, all section headings are indexed.

                                11



Chapter  4



Running  Tex2RTF
Tex2RTF accepts two arguments (input and output filenames) and trailing (op-
tional) switches. If both filenames are given, the utility will work in batch m*
 *ode.
Otherwise, if Tex2RTF has been compiled for GUI operation, a main window
will be shown, will appropriate menu items for selecting input and output file-
names, starting off the conversion process, and so on.


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



-interactiveForces interactive mode even if both filenames are given.

-sync Forces synchronous mode (no yielding to other processes) - usually use
     this in non-interactive mode.

-macros filename Specifies a file for the custom macro file - see Macro not
     found error (section 7.1.1).

-winhelp Specifies Windows Help RTF output.

-rtfSpecifies linear RTF output.

-html Specifies HTML (World Wide Web) output.

-twiceTells Tex2RTF to run the conversion twice to ensure all references and
     citations are resolved and the contents page included.



Note that if the file bullet.bmp is found by Tex2RTF, this bitmap will be used
as the bullet for items in itemize lists; otherwise, a bold `o' will be used in*
 *stead.


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

                                12



Chapter  5



Tex2RTF  for  non-LaT  X
                    E


users
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.

5.1    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 academic*
 *s)
because of its free availability and its flexibility in typesetting maths and o*
 *ther
symbols. It's more like a programming language than a word processor, with
embedded commands prefixed by a backslash and block structure.  Like pro-
grams, 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 pro-
cessors 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 complementary to WYSIWYG packages. These languages allow
automatic production and translation of documents, where manual mark-up is
impractical or undesirable.
                                13


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.

5.2    Document structure



Here is a sample of a typical LaTEX document:



"documentstyle[a4,texhelp]-report"
"title-A title"
"author-Julian Smart"
"date-October 1993"
"begin-document"
"maketitle


"chapter-Introduction"


...


"section-A section"


...


"end-document"



The first line is always a documentstyle command. The square brackets enclose
optional style files (suffix .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 \ begin{document}, you can write
various commands that have an effect on the appearance of the document or
define title page information. The 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.



                                14


5.3    Command syntax



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



"titlepage


"centerline-This is a centred line"


"begin-center"
This is a centred
paragraph
"end-center"


-"bf This is bold font"



The first example has no arguments. The second has one argument. The third
example is an 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.

5.4    Space



In LaTEX, white space is mostly ignored, line breaks make no difference. How-
ever, LaTEX interprets two successive newlines (a blank line) as denoting a par*
 *a-
graph break. You may also use the par command to end a paragraph.


To be continued!

                                15



Chapter  6



Macro  reference
The following lists macros which are recognised by the converters. Other macros
not not mentioned can be assumed to be unrecognised or ignored. Each macro
is given with its number of arguments (not including any optional arguments).

abstract:1



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

addcontentsline:3



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

author:1



Defines the author, for output when maketitle is used.

backslash:0



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

bf:1



Specifies bold font.


                                16


bibitem:2



For convenience, bibitem has two arguments:  label and item.  LaTEX syntax
permits writing this as if it were two arguments, even though it is in fact only
one.

bibliographystyle:1



Currently doesn't affect the style of bibliography, but probably will in the fu*
 *ture.

bibliography:0



Includes the bibliography at this point in the document.  See the section on
bibliographies (section 3.1).

boxit:1



Draws a box around the paragraph.

caption:1



Specifies a caption (within a figure environment). This may be followed imme-
diately by a label command.

cdots:0



Outputs three dots.

centerline:1



Centres (or centers!) a line of text.

center:1



Centres a block of text.



                                17


cextract:0



Prints a C++ extraction operator (>>).

chapter*:1



Outputs a chapter heading with no contents entry.

chapter:1



Outputs a chapter heading.

chapterheading:1



Like 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 glossaries (section 3.2) and other sections that
are not real chapters.

cinsert:0



Prints a C++ insertion operator (<<).

cite:1



Cite a reference. The argument is a reference key as defined in a LaTEX .bib fi*
 *le.

class:1



Outputs the argument, an index entry (LaTEX only) and a keyword entry (Win-
Help only). Used in class reference documentation.

clipsfunc:3



Formats a CLIPS function, given the return value, function name, and argu-
ments.


                                18


comment:1



Allows large comments in LaTEX files. Ignored by Tex2RTF.

copyright:0



Outputs the copyright symbol.

cparam:2



Formats a CLIPS type and argument.  Used within the third argument of a
clipsfunc command.

date:1



Specifies the date of a document; only output by maketitle.

description:1



A list environment, where each item command must be followed by optional
(!) square-bracketed text which will be highlighted.

documentstyle:1



Specifies the main style (report, article etc.) and, optionally, style files su*
 *ch as
texhelp.sty. A report has chapters, while an article's top-level sections are
specified using section.

document:1



This environment should enclose the body of a document.

em:1



Emphasizes text (italic in RTF).



                                19


enumerate:1



Enumerate list environment: numbers the items.

fbox:1



Boxes a paragraph in LaTEX and RTF.

figure:1



A figure enviroment: does nothin in RTF.

flushleft:1



Flushes the given text to the left margin.

flushright:1



Flushes the given text to the right margin.

footnote:1



Footnotes are not yet implemented in RTF: the text is bracketed instead.

framebox:1



Boxes a paragraph in LaTEX and RTF.

functionsection:1



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


Should be followed by a func command to specify function details.

                                20


func:3



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


Should occur after a functionsection command.

gloss:1



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


In Windows Help, this is identical to a section* in a report.


If labels are associated with the glossary entries, they can be referenced by
helpref (section 6) or popref (section 6) 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-helpglossary"


"gloss-API""label-api"


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


"gloss-Canvas""label-canvas"


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


"gloss-DDE""label-dde"


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


"end-helpglossary"

helpglossary:1



An environment for making a glossary (not standard LaTEX). See gloss for usage.

helpignore:1



Ignores the argument in Tex2RTF generated files, but not LaTEX.
                                21


helponly:1



Only outputs the argument in Tex2RTF generated files.

helpinput:1



Only includes the given file in Tex2RTF generated files.

helpfontfamily:1



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

helpfontsize:1



Specifies the font size for Tex2RTF generated files.

helpref:2



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 helprefn command is used instead, where
the section number is suppressed.


Note that when generating HTML, the label contents is automatically defined,
and may be referenced using helpref.

helprefn:2



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 helpref for the form where the section
number is printed in linear documents.



                                22


hline:0



Within a tabular environment, draws a horizontal rule below the current row.

hrule:0



Draws a horizontal line below the current paragraph.

huge:1



Outputs the argument in huge text.

Huge:1



Outputs the argument in huger text that huge.

HUGE:1



Outputs the argument in huger text that Huge.

include:1



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.

input:1



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.

itemize:1



Indents each item of a list and precedes with a bullet. If the file bullet.bmp
is found by Tex2RTF, this bitmap will be used as the bullet; otherwise, a bold
`o' will be used instead.
                                23


item:0



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

image:2



This is translated to a PSBOX macro package 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 or placeable metafile.
If a suitable file is found, in Windows Help mode a bmccommand 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. 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
wxWindows program by calling the function wxMakeMetafilePlaceable.  The
Microsoft Windows SDK has a sample program that loads and steps through
placeable and ordinary metafiles.

it:1



Marks the argument in italic.

label:1



Labels the chapter, section, subsection, subsubsection or figure caption with t*
 *he
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.

large:1



Marks the argument in large text.

                                24


Large:1



Makes the argument display in larger text than large.

LARGE:1



Makes the argument display in larger text than Large.

LaTeX:0



Outputs the annoying LaTEX upper and lower case name.

ldots



Outputs three dots.

maketitle



Makes the article or report title by outputting the title, author and optionally
date.

mbox:1



Draws a box around the given paragraph in LaTEX and RTF, for example:


This should be a boxed paragraph for highlighting important information, such a*
 *s information for registering a shareware program.

membersection:1



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

member:1



Used to format a C++ member variable name.

                                25


newcommand:3



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



"newcommand-"crazy"[2]--"bf #1" is crazy but -"bf #2" is not."



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 tex2rtf.ini file using slightly dif-
ferent syntax (see Macro not found error (section 7.1.1)).

newpage:0



Inserts a page break.

nocite:1



Specifies that this reference should appear in the bibliography, but the citati*
 *on
should not appear in the text.


See also cite.

noindent:0



Sets paragraph indentation to zero. See also parindent.

normalsize:1



Sets the font size back to normal.

param:1



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

parindent:1



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



                                26


parskip:1



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

par:0



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

popref:2



Similar to 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 gloss.

psboxto:2



Identical to image.

quote:1



Indents a short quotation.

quotation:1



Indents a long quotation.

ref:1



In LaTEX and linear RTF, refers to a label and causes the number of that section
or figure to be printed.

rm:1



Causes the argument to be formatted in a plain, roman font.



                                27


rtfsp:0



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.

sc:1



Prints the output in small capitals.

section*:1



Section header, with no entry in the contents page.

section:1



Section header, with an entry in the contents page.

sectionheading:1



Like 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.

shortcite:1



The same as cite.

small:1



Prints the argument in a small font.

subsection*:1



Subsection header, with no entry in the contents page.



                                28


subsection:1



Subsection header, with an entry in the contents page.

subsubsection*:1



Subsubsection header, with no entry in the contents page.

subsubsection:1



Subsubsection header, with an entry in the contents page.

tabbing:1



Tabbing environment: doesn't work properly in RTF.

tableofcontents:0



Inserts the table of contents at this point.

tabular:2



Tabular environment: an attempt is made to output something reasonable in
RTF and XLP formats, although only simple tables will work.

TeX:0



Outputs the annoying TEX upper and lower case name.

title:1



Sets the title, to be output when the command maketitle is used.

                                29


tiny:1



Prints the argument in a very small font.

today:0



Outputs today's date.

tt:1



Outputs the argument in teletype font.

typeout:1



Outputs the text on the Tex2RTF text window.

underline:1



Underlines the argument.

verbatiminput:1



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

verbatim:1



Uses a fixed-width font to format the argument without interpreting any LaTEX
commands.
                                30



Chapter  7



Errors  and  bugs
7.1    Errors



The following sections explain some of the errors that may occur, and how to
deal with them.
7.1.1   Macro not found



This error indicates that Tex2RTF has not implemented a standard LaTEX
macro, 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 tex2rtf.ini)
containing command definitions, such as:



"crazy      [2]--"bf #2" is crazy but #1 is not"
"something  [0]-"
"julian     [0]-Julian Smart"



New commands may be defined in LaTEX files, but custom macro files will have
to be defined when local style files are being used.


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 macro, so
look in the vicinity of the reported error for the real cause.
7.1.2   Unresolved references



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.


                                31


7.2    Bugs


Space. Currently too much space is put after some commands and environ-
     ments (an extra par) because in RTF you need a par before the command
     takes effect, and then the source may have another blank line after that.
     We need a way of remembering we've just output a par.

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.

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


     "parindent 0pt


     instead of


     $"backslash$setlength-$"backslash$parindent"-0pt"


newcommand bug.    Environments in a command definition confuse Tex2RTF.
     Use the command form instead (e.g. \flushleft{...} instead of \begin{flush*
 *left}
     ... \end{flushleft}.

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!

Tables.Tables aren't handled very well. Any suggestions how they could be
     done better?

Footnotes. Not yet supported, since I can't get MS Works to recognise them
     in RTF files.

Indexes and glossaries.Not yet supported.

                                32



Bibliography



[1]Shinsuke Akagi and Kikuo Fujita.  Building an expert system for the pre-
   liminary design of ships. AI EDAM, 1(3):191-205, 1987.

[2]J. Allen et al. From text to speech: the MITalk System. Camb. Univ. Press,
   New York, 1987.

[3]James Allen. Natural Language Understanding. Benjamin/Cummings, 1987.

[4]P.R. Benyon. Presenting models in plain english. In Mathematics and Com-
   puters in Simulation, number 30, pages 17-25, 1988.

[5]Bertram C. Bruce.  Natural communication between person and computer,
   chapter 3, pages 16-87. Lawrence Erlbaum Associates, 1982.

[6]Brian Drabble. Intelligent execution monitoring and error analysis in plan-
   ning involving processes.  PhD thesis, University of Aston, Birmingham,
   1988.

[7]Kenneth Forbus and Albert Stevens.  Using qualitative simulation to gen-
   erate explanations: report no. 4490. Technical report, Navy Personnel Re-
   search and Development Center, March 1981.

[8]Julian Smart. wxWindows 1.50 User Manual. University of Edinburgh, 80
   South Bridge, Edinburgh, EH1 1HN, 1993.


                                33



Glossary
GUI  Graphical User Interface, such as Windows 3 or X.

HTML   Hypertext Markup Language; an SGML document type, used for pro-
     viding hypertext information on the World Wide Web, a distributed hy-
     pertext system on the Internet.

LaTEX A typesetting language implemented as a set of TEX macros. It is distin-
     guished for allowing specification of the document structure, whilst taking
     care of most layout concerns. It represents the opposite end of the spec-
     trum from WYSIWYG word processors.

Metafile Microsoft Windows-specific object which may contain a restricted
     set of GDI primitives.  It is device independent, since it may be scaled
     without losing precision, unlike a bitmap. A metafile may exist in a file *
 *or
     in memory. wxWindows implements enough metafile functionality to use
     it to pass graphics to other applications via the clipboard.  A placeable
     metafile is a metafile with a 22-byte header which can be imported into
     several Windows applications, and is a format used by the Microsoft help
     compiler.

Open Look  A specification for a GUI `look and feel', initiated by Sun Mi-
     crosystems.  XView is one toolkit for writing Open Look applications
     under X, and wxWindows sits on top of XView.

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.

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

wxWindows   wxWindows 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.

XView  An X toolkit supplied by Sun Microsystems, initially just for porting
     SunView applications to X, but which has become a popular toolkit in
     its own right due to its simplicity of use. XView implements Sun's Open
     Look `look and feel' for X, but is not the only toolkit to do so.



                                34
