]> git.saurik.com Git - wxWidgets.git/blob - utils/tex2rtf/docs/tex2rtf.tex
Applied [ 1235509 ] wxCocoa unicode wxT("fixes")
[wxWidgets.git] / utils / tex2rtf / docs / tex2rtf.tex
1 \documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
2 %\input{psbox.tex}
3 \newcommand{\commandref}[2]{\helpref{{\tt $\backslash$#1}}{#2}}%
4 \newcommand{\commandrefn}[2]{\helprefn{{\tt $\backslash$#1}}{#2}\index{#1}}%
5 \newcommand{\commandpageref}[2]{\latexignore{\helprefn{{\tt $\backslash$#1}}{#2}}\latexonly{{\tt $\backslash$#1} {\it page \pageref{#2}}}\index{#1}}%
6 \newcommand{\indexit}[1]{#1\index{#1}}%
7 \newcommand{\inioption}[1]{{\bf {\tt #1}}\index{#1}}%
8 \parskip=10pt%
9 \parindent=0pt%
10 %\backgroundcolour{255;255;255}\textcolour{0;0;0}% Has an effect in HTML only
11 \winhelpignore{\title{Manual for Tex2RTF 2.0: A \LaTeX\ to RTF and HTML converter}%
12 \author{Julian Smart}%
13 \date{November 1999}%
14 }%
15 \winhelponly{\title{Manual for Tex2RTF 2.0}%
16 \author{by Julian Smart\\$$\image{1cm;0cm}{tex2rtf.wmf}$$}%
17 }%
18 \makeindex%
19 \begin{document}%
20 \maketitle%
21 \pagestyle{fancyplain}%
22 \bibliographystyle{plain}%
23 \pagenumbering{roman}%
24 \setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}%
25 \setfooter{\thepage}{}{}{}{}{\thepage}%
26 \tableofcontents%
27
28 \chapter*{Copyright notice}%
29 \setheader{{\it COPYRIGHT}}{}{}{}{}{{\it COPYRIGHT}}%
30 \setfooter{\thepage}{}{}{}{}{\thepage}%
31
32 Copyright (c) 1997 Julian Smart.
33
34 Permission to use, copy, modify, and distribute this software and its
35 documentation for any purpose is hereby granted without fee, provided that the
36 above copyright notice, author statement and this permission notice appear in
37 all copies of this software and related documentation.
38
39 THE SOFTWARE IS PROVIDED ``AS-IS'' AND WITHOUT WARRANTY OF ANY KIND, EXPRESS,
40 IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF
41 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
42
43 IN NO EVENT SHALL JULIAN SMART OR THE ARTIFICIAL INTELLIGENCE
44 APPLICATIONS INSTITUTE OR UNIVERSITY OF EDINBURGH BE LIABLE FOR ANY
45 SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR
46 ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
47 WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY
48 OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
49 PERFORMANCE OF THIS SOFTWARE.
50
51 \chapter{Introduction}%
52 \pagenumbering{arabic}%
53 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
54 \setfooter{\thepage}{}{}{}{}{\thepage}%
55
56 This document describes a utility for converting \popref{\LaTeX}{latexgloss}\ files into
57 several other formats.
58
59 Only a subset of \LaTeX\ can be processed by this utility, especially
60 since the target document language will never perfectly match \LaTeX.
61 Whether the quality of the results is good enough will depend upon the
62 application and your own expectations. {\it This caveat is worth emphasizing}, because
63 many people assume that any old \LaTeX\ document will go through without modification: it might,
64 but the chances are you'll need to modify it a bit for Tex2RTF. Tex2RTF was written with
65 portable document maintenance and generation in mind, with less emphasis on accepting all \LaTeX\ syntax.
66 You have been warned!
67
68 Tex2RTF is heavily biased towards making on-line, hypertext versions of
69 \rtfsp\LaTeX\ documents, but the \popref{RTF}{rtf} converter can be used to generate linear,
70 paper-based documents too.
71
72 The latest version of Tex2RTF, plus source code, can be accessedfrom:
73
74 \begin{verbatim}
75 http://web.ukonline.co.uk/julian.smart/tex2rtf
76 ftp://www.remstar.com/pub/wxwin/tex2rtf
77 \end{verbatim}
78
79 It is available in Sun Open Look, Motif, Windows 3.1, Windows 95/NT, and
80 non-GUI UNIX versions.
81
82 Tex2RTF was developed using the free Open Look, Motif and Windows 3.1
83 C++ class library \popref{wxWidgets}{wxwidgets}.
84
85 \section{Status of Tex2RTF}\index{status of Tex2RTF}%
86
87 Windows HTML help, and wxWidgets 2 wxHTML help, are now catered for using
88 the htmlWorkshopFiles setting.
89
90 Tex2RTF is very rarely updated these days: it would be nice to
91 rewrite the parser (and indeed the rest of it) at some point,
92 to improve error reporting, space handling and ability to
93 handle more advanced Tex/Latex commands.
94
95 \section{Acknowledgements}\index{acknowledgements}%
96
97 Thanks are due to the many people in AIAI and on the Internet at large
98 who have pointed out bugs or shortcomings in Tex2RTF. Michel Lavaud has been
99 a great help in giving advice for improvements to the manual.
100
101 \section{Change log}\index{change log}%
102
103 Version 2.0, August 24th 1999
104
105 \begin{itemize}\itemsep=0pt
106 \item Added htmlWorkshopFiles setting, to output .hpp, .hhc
107 and .hhk (HTML Workshop) files, for generating MS HTML Help or wxHTML Help.
108 \end{itemize}
109
110 Version 1.64, October 20th 1998
111
112 \begin{itemize}\itemsep=0pt
113 \item Added \verb$\insertatlevel$ command.
114 \end{itemize}
115
116 Version 1.63, October 21st 1997
117
118 \begin{itemize}\itemsep=0pt
119 \item Debugged problem with Word bookmarks not being inserted for unnumbered
120 sections.
121 \end{itemize}
122
123 Version 1.62, August 18th 1997
124
125 \begin{itemize}\itemsep=0pt
126 \item Added contributed changes by Andreas Münzenmaier to support German
127 accents by allowing the characters to be placed in input files, and also
128 converting them back to character codes in the WinHelp {\tt .cnt} file.
129 \item Now \verb$\helpref$ causes page references to be inserted in linear RTF,
130 or section references if not on Word mode.
131 \item WinHelp table caption bug fixed.
132 \end{itemize}
133
134 Version 1.61, June 11th 1997
135
136 \begin{itemize}\itemsep=0pt
137 \item \verb$\fcol$ now works in HTML using the FONT tag.
138 \item \verb$\twocollist$ works in indented paragraphs, and is now
139 implemented properly using tables in HTML.
140 \item New boolean option {\bf combineSubSections} added, which switches off
141 the generation of separate HTML files below section level. This can reduce the
142 number of HTML files substantially.
143 \end{itemize}
144
145 Version 1.60, February 18th 1997
146
147 \begin{itemize}\itemsep=0pt
148 \item The index command now allows complex LaTeX instead of inserting the
149 first argument verbatim.
150 \end{itemize}
151
152 Version 1.59, February 14th 1997
153
154 \begin{itemize}\itemsep=0pt
155 \item Added special processing for a chapter called Popups.
156 \end{itemize}
157
158 Version 1.58, August 1st 1996
159
160 \begin{itemize}\itemsep=0pt
161 \item Added HTML settings: backgroundImage, backgroundColour, textColour,
162 linkColour, followedLinkColour.
163 \item Added \verb$\backgroundimage$, \verb$\backgroundcolour$, \verb$\linkcolour$,
164 \verb$followedLinkColour$. \verb$\background$ now obsolete (but behaviour is
165 backward compatible).
166 \item The default background colour is now white.
167 \item Debugged HTML \verb$\ss$ (put in wrong place in code).
168 \end{itemize}
169
170 Version 1.57, July 27th 1996
171
172 \begin{itemize}\itemsep=0pt
173 \item Added upperCaseNames setting; now all links in HTML files are in lower
174 case unless specified otherwise.
175 \end{itemize}
176
177 Version 1.56, May 25th 1996
178
179 \begin{itemize}\itemsep=0pt
180 \item Debugged \verb$\special$ processing for HTML (escaped characters such ampersand).
181 \item Added contentsDepth for Word RTF contents page.
182 \item Removed overlapping href in HTML pages.
183 \end{itemize}
184
185 Version 1.55, May 6th 1996
186
187 \begin{itemize}\itemsep=0pt
188 \item \verb$\verb$ support corrected for HTML.
189 \item Added {\it abstractName} setting.
190 \item Debugged incorrect centring for HTML buttons.
191 \end{itemize}
192
193 Version 1.54, Feburary 28th 1996
194
195 \begin{itemize}\itemsep=0pt
196 \item Bug fix for 24-bit bitmap inclusion when generating RTF:
197 caused a floating point error.
198 \item Added htmlIndex setting, to generate an {\tt .htx} index file of an HTML document for
199 use in wxHelp version 2 or other programs.
200 \item Fixed header/footer bug.
201 \item Change colons to spaces for WinHelp RTF keywords, since the colon has a specific meaning in WinHelp.
202 \end{itemize}
203
204 Version 1.53, January 1995
205
206 \begin{itemize}\itemsep=0pt
207 \item Now stores paths from file inclusions, so that if you include
208 a file A from a separate directory, which then includes a file B
209 relative to that directory, Tex2RTF will search in the path
210 of A to find file B.
211 \end{itemize}
212
213 Version 1.52, December 1995
214
215 \begin{itemize}\itemsep=0pt
216 \item \verb$\helpref$ and related commands now generate italicized instead
217 of bold `anchor' text for linear formats.
218 \item Cured bug where Tex2RTF could hang on start up, while reading
219 the {\tt tex2rtf.ini} file. This occurred when a comment finished with
220 the end of file.
221 \item Split the commands reference in two (\LaTeX\ and Tex2RTF commands),
222 and added a {\it Commands by category} section.
223 \item Removed a bug that caused HTML output to be garbled on the
224 second pass.
225 \end{itemize}
226
227 Version 1.51: Windows 95 enhancements.
228
229 \begin{itemize}\itemsep=0pt
230 \item Added settings winHelpContents (for generating {\tt .cnt} file), winHelpVersion (for specifying
231 target version of WinHelp).
232 \item Added space to non-scrolling region of topic.
233 \item If winHelpVersion is 4, makes non-scrolling region grey and the rest yellow.
234 \item Added \verb$\settransparency$ command for WinHelp 4 transparent bitmaps.
235 \end{itemize}
236
237 Version 1.50:
238
239 \begin{itemize}\itemsep=0pt
240 \item Tidied up HTML generation (headers and bodies in the right places).
241 \item Eliminated extra space after verbatim in HTML.
242 \item Added support for simple tables in HTML.
243 \item Added \verb$\textcolour$, \verb$\background$ for colouring text and background in HTML.
244 \item Added \verb$\copyright$, \verb$\registered$ symbols in HTML.
245 \item Added \verb$\imagel$, \verb$\imager$ for left and right aligned images
246 in HTML.
247 \item Added \verb$\brclear$ for clearing image alignment in HTML.
248 \item Added \LaTeX\ font size support in HTML (\verb$\small$, \verb$\large$ etc.) using Netscape font extensions.
249 \item HTML button-bar change: always shows the same buttons, but may make one or more insensitive. Changing button positions
250 could be very annoying.
251 \item Tidied up RTF generation for non-Word viewers ({\it useWord} set to {\it false}). Will now look reasonable using
252 Windows 95 Quick View and WordPad: WordPad doesn't do tables but does bitmaps, and QuickView does tables but not
253 bitmaps. Such is life.
254 \end{itemize}
255
256 Version 1.49:
257
258 \begin{itemize}\itemsep=0pt
259 \item Cured some bugs (char used for fgetc instead of int) so now compiles for
260 WIN32s.
261 \end{itemize}
262
263 Version 1.48:
264
265 \begin{itemize}\itemsep=0pt
266 \item Added some LaTeX2e fonts commands such as \verb$\rmfamily$, \verb$\textrm$, \verb$\emph$.
267 Most of these are aliases for other commands.
268 \end{itemize}
269
270 Up to version 1.47:
271
272 \begin{itemize}\itemsep=0pt
273 \item Added \verb$\backslashraw$, \verb$\rbraceraw$ and \verb$\lbraceraw$ commands
274 to help output arbitrary RTF.
275 \item Added \verb$\sethotspotcolour$, \verb$\sethotspotunderline$ commands for controlling
276 WinHelp hotspot appearance.
277 \item Added truncateFilenames option.
278 \item Improved HTML inline image handling.
279 \end{itemize}
280
281 Up to version 1.46:
282
283 \begin{itemize}
284 \itemsep=0pt
285 \item Added \verb$\urlref$ command for specifying HTML URLs.
286 \item Started support for translating .SHG files to HTML .map files
287 (this works if compiled under Borland, not MS VC++ for some reason!)
288 \item Fixed nasty memory bug in HTML code (thanks Petr).
289 \end{itemize}
290
291 Version 1.40:
292
293 \begin{itemize}
294 \itemsep=0pt
295 \item Added {\it generateHPJ} option for generating the .HPJ WinHelp project file
296 \item Added support for DDE via a small command set
297 \end{itemize}
298
299 Version 1.39:
300
301 \begin{itemize}
302 \itemsep=0pt
303 \item Option for using Word's INCLUDEPICTURE or IMPORT field, since the method that
304 works for Works, doesn't work for Word! See {\it bitmapMethod} in the
305 settings section.
306 \end{itemize}
307
308 Version 1.37-1.38:
309
310 \begin{itemize}
311 \itemsep=0pt
312 \item Improved bibliography reading and cured some minor bugs
313 \item Added \verb$\ss$ German sharp s
314 \item Added rudimentary \verb$\special$ command (simply copies the argument
315 to the output)
316 \item Added missing '.' in subsubsection reference
317 \item Added primitive internationalisation support with contentsName, tablesName etc.
318 \end{itemize}
319
320 Version 1.36:
321
322 \begin{itemize}
323 \itemsep=0pt
324 \item All HTML special characters now correctly delimited by a semicolon.
325 \item Cured HTML section-duplicating bug I introduced in 1.35.
326 \item Cured too much spacing after sections in RTF, introduced in 1.35.
327 \end{itemize}
328
329 Version 1.35:
330
331 \begin{itemize}
332 \itemsep=0pt
333 \item Added TCHECK tool, to help track down common Tex2RTF syntax problems.
334 \item Included Kresten Thorup's LACHECK \LaTeX\ checking tool with DOS executable.
335 \item Now ignores \verb|\@| command.
336 \item Table of contents now includes numbered subsubsections.
337 \end{itemize}
338
339 Version 1.34:
340
341 \begin{itemize}
342 \itemsep=0pt
343 \item Added \verb$\multicolumn$ `support' to stop RTF readers crashing.
344 \item Added {\it useWord, defaultColumnWidth, compatibility} options to {\tt .ini} file.
345 \item \verb$\comment$ environment now doesn't complain about unknown syntax.
346 \item Added \verb$\toocomplex$ environment that treats its contents as
347 verbatim in output, treated as normal output in true \LaTeX.
348 \item End-of-line comments allowed in in {\tt .ini} files, using semicolon,
349 percent or hash characters to denote a comment.
350 \item For linear RTF, Word for Windows support for \verb$\printindex$,\rtfsp
351 \verb$\index$, \verb$\pageref$, \verb$\listoftables$, \verb$\listoffigures$, contents page.
352 \item Added RTF support for various symbols.
353 \item Added colour support, with \verb$\definecolour$, \verb$\fcol$ and \verb$\bcol$ commands.
354 \item Fixed some bugs: page numbering problems, macros deleted after first pass.
355 \end{itemize}
356
357 Version 1.33:
358
359 \begin{itemize}
360 \itemsep=0pt
361 \item Added -charset command-line switch.
362 \item Added \verb$\itemsep$, \verb$\twocolumn$, \verb$\onecolumn$, \verb$\setfooter$, \verb$\setheader$, \verb$\pagestyle$,
363 \verb$\pagenumbering$, \verb$\thechapter$, \verb$\thesection$, \verb$\thepage$, \verb$\thebibliography$, \verb$\bibitem$ commands.
364 \item New environment called \verb$\twocollist$ for making two-column lists,
365 with formatting optimized for target file format.
366 \item New \verb$\indented$ environment for controlling indentation.
367 \item List indentation and bulleting improved.
368 \item Added commands \verb$\normalbox$, \verb$\normalboxd$ for putting borders around text.
369 \item Many options can now be specified in the {\tt .ini} file along with custom macros.
370 \item Cured bug that put too much vertical space after some commands.
371 \item Improved table formatting.
372 \item Optional `Up' button in WinHelp files for easier navigation.
373 \item Verbatim lines followed by \verb$\par$ in RTF, to improve WinHelp wrapping.
374 \item Conversion may now be aborted under Windows by attempting to close the application.
375 \item Added conditional output for all formats: \verb$\latexignore$, \verb$\latexonly$, \verb$\rtfignore$, \verb$\rtfonly$,
376 \verb$\winhelpignore$, \verb$\winhelponly$, \verb$\htmlignore$, \verb$\htmlonly$, \verb$\xlpignore$, \verb$\xlponly$.
377 \item HTML generator can now add Contents, Up, $<<$ and $>>$ buttons (text or bitmap) to
378 each page except titlepage.
379 \end{itemize}
380
381 Version 1.32:
382
383 \begin{itemize}
384 \itemsep=0pt
385 \item \verb$\footnote$ command now supported in WinHelp RTF, and \verb$\footnotepopup$\rtfsp
386 added.
387 \end{itemize}
388
389 Version 1.31:
390
391 \begin{itemize}
392 \itemsep=0pt
393 \item \verb$\footnote$ command now supported, in linear RTF only.
394 \item Added {\tt -bufsize} option, for converting large documents.
395 \end{itemize}
396
397 Version 1.30:
398
399 \begin{itemize}
400 \itemsep=0pt
401 \item \verb$\image$ command now scales metafiles (but not bitmaps).
402 \item Fixed macro loading bug, now informs the user of the found macro filename.
403 \item Now supports paragraph and subparagraph commands.
404 \item Support for some accents added.
405 \item \verb$\verb$ command now supported.
406 \item Bug in subsubsection handling fixed.
407 \item Can save conversion log in a text file.
408 \end{itemize}
409
410 Version 1.22:
411
412 \begin{itemize}
413 \itemsep=0pt
414 \item More informative, warns against use of some commands.
415 \item Added compile-time support for non-GUI environments (such as plain UNIX).
416 \item Improved HTML support.
417 \end{itemize}
418
419 \chapter{Running Tex2RTF}\index{running Tex2RTF}%
420 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
421 \setfooter{\thepage}{}{}{}{}{\thepage}%
422
423 Tex2RTF may be run in a number of ways: with or without command line arguments,
424 interactively or in batch mode, and with an optional initialisation file
425 for specifying \LaTeX\ macros and detailed options.
426
427 Tex2RTF accepts two arguments (input and output filenames) and trailing
428 (optional) switches. If both filenames are given, the utility will work
429 in batch mode. Otherwise, if Tex2RTF has been compiled for GUI
430 operation, a main window will be shown, with appropriate menu items for
431 selecting input and output filenames, starting off the conversion
432 process, and so on.
433
434 Note that if the file {\tt bullet.bmp}\index{bullets} is found by Tex2RTF, this bitmap
435 will be used as the bullet for items in \verb$\itemize$ lists, for WinHelp
436 output. Otherwise, a symbol will be inserted (linear RTF) or bold `o'
437 will be used instead (all other formats).
438
439 Syntax error reporting is fairly minimal. Unrecognised macro errors may
440 actually be produced by an unbalanced brace or passing the wrong number of
441 arguments to a command, so look in the vicinity of the error for the
442 real cause.
443
444 \normalbox{Some of the syntax that is OK for true \LaTeX\ but which trips up
445 Tex2RTF, may be detected by the TCHECK\index{TCHECK} program included in the tools
446 directory of the Tex2RTF distribution. Some \LaTeX\ errors may be picked up
447 by the LACHECK\index{LACHECK} program, also found in the tools directory.}
448
449 It is recommended that you run Tex2RTF twice in order to be sure of
450 resolving all references and including an up-to-date contents page.
451
452 If importing RTF files into Word for Windows\index{Microsoft Word}, you may need to reformat
453 the document. The easiest way to do this is to select all text with
454 CTRL-A, then reformat with F9. Reformat again to ensure all references
455 are resolved. For the second format, respond with {\it Update Entire
456 Table} to prompts.
457
458 \winhelponly{
459 \section{Tex2RTF Interface}
460
461 This is the Tex2RTF interface under Windows. Click on an area of the
462 picture for more information.
463
464 $$\imagemap{1cm;0cm}{screen}{mapref}$$
465
466 \subsection{Menu bar}\label{menubar}
467
468 Use the menubar for interactive operations.
469
470 \subsection{Message area}\label{messagearea}
471
472 Tex2RTF writes warning and error messages on this window.
473
474 \subsection{Status line}\label{statusline}
475
476 Displays help on menu items as the user drags the cursor over the menus.
477
478 \subsection{Mode indicator}\label{modeindicator}
479
480 Displays the output mode Tex2RTF is currently in.
481 }
482
483 \section{Command line arguments}\index{command line arguments}%
484
485 These are the optional arguments you may give Tex2RTF on the command line.
486
487 \twocolwidtha{5cm}
488 \begin{twocollist}
489 \twocolitem{{\bf -bufsize}}{Specifies buffer size in K (default 60 under Windows,
490 500 under UNIX). Large files (particularly large verbatim environments)
491 may require a large buffer size, equal to the largest argument of a \LaTeX\ command.
492 Note that this value may not be larger than 64 under Windows.}
493 \twocolitem{{\bf -html}}{Specifies HTML (World Wide Web) output.}
494 \twocolitem{{\bf -interactive}}{Forces interactive mode even if both
495 filenames are given.}
496 \twocolitem{{\bf -charset charset}}{Specifies a character set for
497 RTF production. This can be one of ansi, mac, pc, and pca.
498 The default is ansi.}
499 \twocolitem{{\bf -macros filename}}{Specifies a file for the custom macro
500 file -- see \helpref{Macro not found error}{macronotfound}.}
501 \twocolitem{{\bf -rtf}}{Specifies linear RTF output.}
502 \twocolitem{{\bf -sync}}{Forces synchronous mode (no yielding to other
503 processes) -- usually use this in non-interactive mode.}
504 \twocolitem{{\bf -twice}}{Tells Tex2RTF to run the conversion twice to ensure all
505 references and citations are resolved and the contents page included.}
506 \twocolitem{{\bf -winhelp}}{Specifies Windows Help RTF output.}
507 \end{twocollist}
508
509 \section{Initialisation file syntax}\label{inifile}\index{initialisation file}%
510
511 The initialisation file contains further detailed options for
512 customising Tex2RTF's behaviour. A file may be specified
513 with the {\tt -macros} command line switch, otherwise Tex2RTF
514 looks for the file {\tt tex2rtf.ini} in the working directory
515 or input file directory.
516
517 The file may comprise macro\index{macros} (command) definitions or option settings.
518
519 The syntax for a macro definition is:
520
521 \begin{verbatim}
522 \name [number of args] {...LaTeX code...}
523 \end{verbatim}
524
525 For example:
526
527 \begin{verbatim}
528 \crazy [2]{{\bf #2} is crazy but #1 is not}
529 \something [0]{}
530 \julian [0]{Julian Smart}
531 \end{verbatim}
532
533 The syntax for an option setting is:
534
535 \begin{verbatim}
536 name = value
537 \end{verbatim}
538
539 or
540
541 \begin{verbatim}
542 name = "value"
543 \end{verbatim}
544
545 For example:
546
547 \begin{verbatim}
548 conversionMode = RTF
549 runTwice = true
550 titleFontSize = 12
551 authorFontSize = 10
552 headerRule = yes
553 footerRule = yes
554 \end{verbatim}
555
556 Options expecting boolean values accept {\it 1, 0, true, false, yes, no} in any combination of upper or
557 lower case.
558
559 End-of-line comments are allowed in an initialisation file, using the
560 hash, semicolon or percent signs to denote the start of a comment, which runs
561 until the end of the line.
562
563 \subsection{Tex2RTF options}\index{options in initialisation file}\index{tex2rtf.ini}\index{initialisation file}\index{macros}%
564
565 These are the allowable options in an initialisation file.
566
567 \subsubsection{General options}\label{generaloptions}
568
569 \twocolwidtha{5cm}
570 \begin{twocollist}
571 \htmlignore{\twocolitemruled{Option}{Description}}
572 \twocolitem{\inioption{compatibility}}{Set to true for maximum \LaTeX\ compatibility, e.g. if
573 tables crash RTF readers. Should be false (default) if the Tex2RTF guidelines
574 are followed, e.g. use of $\backslash${\tt row} command in tabular environment.}
575 \twocolitem{\inioption{conversionMode}}{One of RTF, WinHelp, XLP (or wxHelp), and HTML.}
576 \twocolitem{\inioption{ignoreInput}}{Adds the filename to the list of files ignored by the $\backslash${\tt input} command.
577 The only default filename in the list is {\tt psbox.tex}.}
578 \twocolitem{\inioption{isInteractive}}{If true, runs in interactive mode (the default).}
579 \twocolitem{\inioption{runTwice}}{If true, runs the converter twice.}
580 \twocolitem{\inioption{ignoreBadRefs}}{If true (or yes), ignores bad helpref references
581 and simply writes the text in the first argument. Useful when a program such as HelpGen
582 generates references to classes documented in another manual.}
583 \end{twocollist}
584
585 \subsubsection{Presentation options}\index{options, presentation}%
586
587 \begin{twocollist}
588 \htmlignore{\twocolitemruled{Option}{Description}}
589 \twocolitem{\inioption{authorFontSize}}{Specifies the point size for the author and date (RTF only).}
590 \twocolitem{\inioption{chapterFontSize}}{Specifies the point size for chapter headings (RTF only).}
591 \twocolitem{\inioption{documentFontSize}}{One of 10, 11 and 12, to specify the main font size
592 independently of the \LaTeX\ document style command.}
593 \twocolitem{\inioption{sectionFontSize}}{Specifies the point size for section headings (RTF only).}
594 \twocolitem{\inioption{subsectionFontSize}}{Specifies the point size for subsection headings (RTF only).}
595 \twocolitem{\inioption{titleFontSize}}{Specifies the point size for the title (RTF only).}
596 \twocolitem{\inioption{chapterName}}{The string used when referencing chapters. The default is ``chapter".}
597 \twocolitem{\inioption{sectionName}}{The string used when referencing sections. The default is ``section".}
598 \twocolitem{\inioption{subsectionName}}{The string used when referencing subsections. The default is ``subsection".}
599 \twocolitem{\inioption{subsubsectionName}}{The string used when referencing subsubsections. The default is ``subsubsection".}
600 \twocolitem{\inioption{indexName}}{The string used for printing the index heading. The default is ``Index".}
601 \twocolitem{\inioption{contentsName}}{The string used for printing the contents heading. The default is ``Contents".}
602 \twocolitem{\inioption{abstractName}}{The string used for printing the abstract heading. The default is ``Abstract".}
603 \twocolitem{\inioption{tablesName}}{The string used for printing the list of tables heading. The default is ``List of Tables".}
604 \twocolitem{\inioption{tableName}}{The string used when referencing a table. The default is ``table".}
605 \twocolitem{\inioption{figuresName}}{The string used for printing the list of figures heading. The default is ``List of Figures".}
606 \twocolitem{\inioption{figureName}}{The string used when referencing a figure. The default is ``figure".}
607 \twocolitem{\inioption{glossaryName}}{The string used for printing the glossary heading. The default is ``Glossary".}
608 \twocolitem{\inioption{referencesName}}{The string used for printing the references heading. The default is ``References".}
609 \end{twocollist}
610
611 \subsubsection{RTF and WinHelp options}\label{rtfwinhelpoptions}\index{options, RTF}\index{RTF}%
612
613 \begin{twocollist}
614 \htmlignore{\twocolitemruled{Option}{Description}}
615 \twocolitem{\inioption{bitmapMethod}}{Can be ``hex'' (embed the hex data in the file with a $\backslash$dibitmap keyword),
616 ``includepicture'' (use the MS Word 6.0 INCLUDEPICTURE field) or ``import'' (an earlier name
617 for INCLUDEPICTURE). ``hex'' may be used for importing into MS Works, but this doesn't work
618 for Word 6.0. The default is ``includepicture''.}
619 \twocolitem{\inioption{contentsDepth}}{The depth of headings that is displayed in the table of contents. The default
620 is 4 but you may wish to reduce this, for example for manuals that document C++ and have a large number of
621 headings for member functions.}
622 \twocolitem{\inioption{defaultColumnWidth}}{The width in points for columns in tables
623 where the width of the column is not set by using {\it p} in the tabular
624 argument. The default is 100.}
625 \twocolitem{\inioption{footerRule}}{If true, draws a rule above footers (linear RTF only).}
626 \twocolitem{\inioption{generateHPJ}}{If true, generates a .HPJ project file (WinHelp mode only).}
627 \twocolitem{\inioption{headerRule}}{If true, draws a rule below headers (linear RTF only).}
628 \twocolitem{\inioption{listLabelIndent}}{Specifies the size of list item label indentation, in points.
629 The default is 18.}
630 \twocolitem{\inioption{listItemIndent}}{Specifies the size of list item indentation, in points. The default
631 is 40.}
632 \twocolitem{\inioption{indexSubsections}}{If true (the default), subsection and subsubsection
633 titles are indexed in RTF mode.}
634 \twocolitem{\inioption{mirrorMargins}}{If true, margins are mirrored in twosided documents (linear RTF only).}
635 \twocolitem{\inioption{useWord}}{If true (the default), Word for Windows RTF
636 formatting is used where possibly, e.g. for the table of contents, list of
637 tables, and list of figures.}
638 \twocolitem{\inioption{useHeadingStyles}}{If true (the default), sections are marked with
639 appropriate heading styles for generating the table of contents in RTF.}
640 \twocolitem{\inioption{useUpButton}}{If true (the default), WinHelp files will be generated with an {\bf Up}\rtfsp
641 button to make browsing easier. Note that you need to put an extra line in the CONFIG section
642 of your .HPJ file:
643
644 {\tt CreateButton("Up", "\&Up", "JumpId(`name.hlp', `Contents')")}
645
646 where {\tt name.hlp} is the name of your help file.}
647 %%% NEED TO BREAK THE LIST AT THE PAGE BREAK BECAUSE LATEX IS STUPID
648 %%% UNFORTUNATELY, Tex2RTF IS STUPIDER SO NEED TO COMMENT OUT THIS
649 %%% LINE WHEN MAKING HTML, RTF, XLP
650 %\latexonly{\end{twocollist}\newpage\begin{twocollist}}
651 \twocolitem{\inioption{winHelpContents}}{If yes, ok or true, a WinHelp {\tt .cnt} file will be generated (used in Windows 95 for either old WinHelp
652 files or new WinHelp 4 files).}
653 \twocolitem{\inioption{winHelpVersion}}{The version of WinHelp being targetted. This affects the generated {\tt .hpj} file and features
654 such as transparent bitmaps which are new to version 4 or later. The default is 3.}
655 \twocolitem{\inioption{winHelpTitle}}{Windows Help file title, inserted into the project file if {\it generateHPJ} is true.}
656 \end{twocollist}
657
658 \subsubsection{HTML options}\label{htmloptions}\index{options, HTML}\index{HTML}%
659
660 \begin{twocollist}
661 \htmlignore{\twocolitemruled{Option}{Description}}
662 \twocolitem{\inioption{htmlBrowseButtons}}{Allows generation of Contents, Up, browse back and browse forward
663 buttons on each HTML page except title page. Specify none, text or bitmap. If you specify
664 bitmap, make sure that the files {\tt contents.gif}, {\tt up.gif}, {\tt back.gif} and {\tt forward.gif} are in the
665 directory where the HTML files will reside: samples are given in the docs directory.}
666 \twocolitem{\inioption{truncateFilenames}}{If true, uses {\tt .htm} suffix instead of {\tt .html},
667 and truncates filenames within HTML documents.}
668 \twocolitem{\inioption{htmlIndex}}{If true, specifies generation of an {\tt .htx} index file for an HTML document.
669 This file can be used in wxHelp version 2 or other programs. The file consists of a number of lines,
670 each line with three fields separated by bar characters: the indexed phrase, the file, and a label in the file.}
671
672 \twocolitem{\inioption{htmlWorkshopFiles}}{If true, specifies generation of {\tt .hpp, .hhc} and {\tt .hhk} files
673 which can be used to create both MS HTML Help and wxHTML Help files. wxHTML Help
674 is the HTML help facility that can be used by wxWidgets 2 applications (see the wxWidgets manual
675 and the wxWidgets HTML sample).}
676 \twocolitem{\inioption{upperCaseNames}}{If true, filenames in links are in upper case. By default
677 filenames are in lower case.}
678 \twocolitem{\inioption{backgroundColour}}{Specifies the RGB background colour for the document, e.g. {\tt 255;255;255} for white.
679 The default is white.}
680 \twocolitem{\inioption{backgroundImage}}{Specifies the RGB background image for the document, e.g. {\tt tile.gif}.}
681 \twocolitem{\inioption{textColour}}{Specifies the RGB text colour for the document, e.g. {\tt 0;0;0} for black.}
682 \twocolitem{\inioption{linkColour}}{Specifies the RGB link colour for the document, e.g. {\tt 0;0;255} for blue.}
683 \twocolitem{\inioption{followedLinkColour}}{Specifies the RGB followed link colour for the document, e.g. {\tt 0;0;255} for blue.}
684 \twocolitem{\inioption{combineSubSections}}{If true (or yes), switches off
685 the generation of separate HTML files below section level. This can reduce the
686 number of HTML files substantially. A subsection contents list is inserted before
687 the first subsection.}
688 \twocolitem{\inioption{htmlFaceName}}{A string specifying the overall font face, such as ``"Arial, Lucida, Helvetica".}
689 \end{twocollist}
690
691 \section{DDE commands}\index{DDE}%
692
693 A Windows program can hold a conversation with Tex2RTF using DDE. The Tex2RTF server name is
694 ``TEX2RTF'', and the topic name to use is also ``TEX2RTF''.
695
696 Tex2RTF functionality is accessed using the DDE {\it Execute} message.
697 The {\it Execute} data should consist of a command name and possibly one
698 argument, e.g.
699
700 \begin{verbatim}
701 INPUT c:\docs\mine.tex
702 \end{verbatim}
703
704 If the command is not recognised, a standard TEX2RTF.INI option is assumed.
705
706 The {\it Request} DDE message can be used to query the return status of an {\it Execute}
707 command, and will be one of {\it OK} (no error), {\it CONVERSION ERROR}, or a more
708 specific error string.
709
710 The following DDE commands may be used:
711
712 \begin{twocollist}
713 \htmlignore{\twocolitemruled{Command}{Description}}
714 \twocolitem{\inioption{EXIT}}{Takes no argument, and exits Tex2RTF.}
715 \twocolitem{\inioption{GO}}{Takes no argument, and initiates the conversion.}
716 \twocolitem{\inioption{INPUT}}{Takes a file name as the argument, and sets the input file to be this name.}
717 \twocolitem{\inioption{MINIMIZE}}{Takes no argument, and minimizes Tex2RTF.}
718 \twocolitem{\inioption{OUTPUT}}{Takes a file name as the argument, and sets the input file to be this name.}
719 \twocolitem{\inioption{RESTORE}}{The same as SHOW.}
720 \twocolitem{\inioption{SHOW}}{Takes no argument, and unminimizes Tex2RTF.}
721 \end{twocollist}
722
723 \section{Performance issues}\index{performance}%
724
725 Since Tex2RTF reads the whole file into memory, a lot of memory is needed.
726 For very large documents, 16MB of RAM is adviseable.
727
728 I tested conversion of the wxWidgets 1.63 manual on both VC++ 1.5 and
729 Watcom WIN32s versions of Tex2RTF, both running under Windows 3.11 on a
730 Gateway P60 with 16MB of RAM and a 2MB disk cache. Two passes were
731 made, with 1.5MB of WinHelp RTF being generated. The unoptimized 16-bit
732 version took 169 seconds. The optimized WIN32s version took 126 seconds,
733 a significant improvement. Systems with faster disk subsystems should see
734 an even better relative performance of the 32-bit version.
735
736 \chapter{Writing documents with Tex2RTF}\index{LaTeX}%
737 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
738 \setfooter{\thepage}{}{}{}{}{\thepage}%
739
740 \section{Why use \LaTeX?}
741
742 \LaTeX\ happens to be a very convenient format if you need to produce
743 documents (such as manuals, help facilities, up-to-date information) in
744 both printed and on-line media. Being a language rather than a WYSIWYG system,
745 it allows explicit specification of layout and document structure, lending
746 itself well to hypertext applications and automatic document generation.
747 Many people also prefer to use \LaTeX\ for ordinary use since it encourages
748 a logical document structure and the user is not distracted by having to perfect
749 the appearance; many layout decisions are taken by \LaTeX\ automatically.
750
751 Although \LaTeX\ is not as fancy as modern word processors and desk-top
752 publishing packages, it is for many purposes quite adequate, and sometimes
753 more flexible than its modern counterparts.
754
755 The conversion utility gives \LaTeX\ a new lease of life by allowing
756 virtually all other wordprocessor formats to be generated from documents
757 containing a reasonable subset of \LaTeX\ syntax. From the same \LaTeX\
758 sources, we can now generate printed manuals, Windows Help files, \popref{wxHelp}{wxhelp}\rtfsp
759 files, RTF-compatible word processor formats such as MS Word, and \popref{HTML}{html}\rtfsp
760 files for use in the World Wide Web. Since the conversion tool is
761 free, as are \LaTeX, HTML viewers, wxHelp and (effectively) Windows
762 Help, there are no financial or time penalties for providing
763 documentation in a wide range of printed and hypertext formats.
764
765 \section{Help versus the printed page}\index{on-line help}%
766
767 The purist may argue, quite rightly, that on-line help systems and
768 printed manuals have different characteristics; help windows tend to be
769 much smaller than pages, help topics should be more stand-alone than
770 pages in a manual, navigation methods are very different, etc. Therefore,
771 help systems should be {\it based} on printed documentation but
772 separately hand-crafted into hypertext help, preferably by an
773 independent person or team.
774
775 This might be the ideal, but many organisations or individuals simply
776 do not have the time: on-line help wouldn't get done if the
777 documentation effort had to be doubled. However, Tex2RTF does provide
778 some commands to allow tailoring the documentation to printed or
779 on-line form, such as \verb$\helponly$ and \verb$\helpignore$. An awareness
780 of the design issues should go a long way to making the compromise
781 a good one, so a book such as {\it Developing On-line Help for Windows} \cite{helpbook} is highly recommended.
782
783 \section{Output Formats}\index{output formats}%
784
785 At present the following output formats are supported:
786
787 \begin{itemize}
788 \itemsep=0pt
789 \item RTF (Rich Text Format)\index{RTF}. This is the most well developed
790 converter. RTF is commonly used as a document exchange format amongst
791 Windows-based applications, and is the input for the Windows Help
792 Compiler. Tex2RTF supports both linear documents and Windows Help
793 hypertext format.
794 \item HTML (Hypertext Markup Language)\index{HTML}. This an SGML-based format
795 commonly used by documents in the World Wide Web distributed hypertext
796 system, and formats text dynamically rather like Windows Help.
797 \item wxHelp\index{wxHelp}. This is the platform-independent help system for
798 the class library wxWidgets (see the wxWidgets User Manual \cite{smart93a}).
799 It can display ASCII files with embedded codes
800 for changing font styles, but no formatting is done by wxHelp.
801 \end{itemize}
802
803 \section{What compromises must I make?}\index{compromises}\index{LaTeX}%
804
805 As a \LaTeX\ user, you need to be aware that some commands or facilities
806 don't transfer to other formats, either because they are not supported
807 by the target format or because the converter does not support them.
808 Maths formatting is a good example of an unsupported feature.
809
810 Sometimes \LaTeX\ facilities must be accessed in a slightly different
811 way to support the variety of formats, particularly hypertext formats
812 where \LaTeX\ references are often replaced by hypertext jumps (but must
813 still look right in printed documentation). Tables don't transfer well
814 to RTF and HTML (and not at all to wxHelp) but an attempt is made
815 to approximate tables so long as special row commands are used, instead
816 of the usual end of row delimiter.
817
818 Bibliographies are handled quite well since the utilities can read in\rtfsp
819 {\tt .bib} files and resolve citations. Numbers are used in citations;
820 the references are not yet sorted alphabetically.
821
822 Pictures\index{pictures} are handled in a limited way: if the PSBOX\index{PSBOX} macro package is
823 used, an \verb$\image$ command can be used to place Encapsulated PostScript
824 files in \LaTeX, and Windows RGB-encoded bitmap files or placeable
825 metafiles when converting to RTF.
826
827 Nested file inclusion\index{file inclusion} is handled with \verb$\input$, \verb$\include$ and \verb$\verbatiminput$,
828 and the comment environment is supported. However, using \verb$\input$\rtfsp
829 to include macro packages is not advisable. If you do this,
830 make sure you add a line in the Tex2RTF initialisation file to ignore
831 this file, unless it's a simple \LaTeX\ file that conforms to Tex2RTF
832 restrictions. The file {\tt psbox.tex} is the only file ignored
833 by Tex2RTF by default.
834
835 Because of the way \LaTeX\ is parsed, some syntax\index{syntax restrictions} has to conform to a
836 few simple rules. Commands such as \verb$\bf$ and \verb$\it$ need to occur
837 immediately after a left brace, and have a block of their own, since
838 the text within their scope is regarded as its argument. This syntax
839 means the same thing as using \verb$\begin ... \end$, which is usually
840 a one argument command (the argument is the text between the \verb$\begin$\rtfsp
841 and \verb$\end$). See \helpref{Space}{space}.
842
843 As a Windows hypertext help writer\index{on-line help}, you don't have access to all RTF
844 commands but you'll be able to get most of what you want. In particular,
845 any \LaTeX\ document you write will automatically be a hypertext
846 document, because the converter takes advantage of the hierarchy of
847 sections. Further jumps can be placed using the commands
848 \rtfsp\commandrefn{label}{label}, \commandrefn{helpref}{helpref},
849 \rtfsp\commandrefn{helprefn}{helprefn}, and \commandrefn{popref}{popref}.
850 Tex2RTF outputs help files that may be read linearly using the
851 \rtfsp$<<$ and $>>$ buttons, with an additional Up button for
852 ease of navigation.
853
854 When writing HTML, multiple files are generated from one \LaTeX\ file
855 since browsing HTML works best with many small files rather than a few
856 large ones.
857
858 wxHelp files are least well supported since there is no formatting
859 support, only font style, sizes and colours. Still, some hypertext help
860 support on UNIX/X platforms is better than none. wxHelp is now being rewritten (March 1996)
861 to use HTML files.
862
863 Sometimes you will use a local macro package that is unrecognised by
864 the converters. In this case, you may define a custom macro file
865 where macros are defined in terms of supported \LaTeX\ commands
866 and text. Even if the result is not the same as in \LaTeX, you
867 can probably end up with something adequate, and at least avoid
868 undefined macro errors. See \helpref{Initialisation file syntax}{inifile} for
869 further information.
870
871 \section{Changes to LaTeX syntax}
872
873 Here are the conventions you need to observe to satisfy the Tex2RTF
874 parser.
875
876 \subsection{Space}\label{space}\index{space}%
877
878 Tex2RTF attempts to insert spaces where \LaTeX\ assumes whitespace.
879 However, for the benefit of RTF conversion, you need to use the \commandrefn{rtfsp}{rtfsp} command
880 where a command or brace within a paragraph begins or ends with a macro. For example:
881
882 \begin{verbatim}
883 Within a paragraph, you need to be careful about commands
884 \rtfsp{\it that begin at the start of a line.}
885 \end{verbatim}
886
887 As normal with \LaTeX, two newlines represents a paragraph break,
888 although \commandrefn{par}{par} can also be used at the end of a paragraph.
889
890 You need to have a blank line between section and some environment
891 commands and the first paragraph or your document will look rather
892 weird, e.g. headings running into paragraphs.
893
894 wxHelp is more fussy than \LaTeX\ or RTF: you need to use percent
895 characters at line ends liberally to eliminate newlines after commands
896 on single lines.
897
898 \subsection{Command arguments}\index{LaTeX commands}%
899
900 Commands that have one or more arguments can be used in the following
901 three ways:
902
903 \begin{verbatim}
904 \bf{Some text.}
905
906 \begin{bf}
907 Some text.
908 \end{bf}
909
910 {\bf Some text.}
911 \end{verbatim}
912
913 The first method is a normal \LaTeX\ command.
914
915 The second method is called an {\it environment}; \LaTeX\ has specific
916 environments that do not always correspond to normal commands, but
917 Tex2RTF recognizes environments and normal commands interchangeably, so
918 long as the command has no more than two arguments.
919
920 With the third method, it is important that the command has its own
921 pair of braces, and that the command immediately follows the first brace.
922 Otherwise, the parser cannot parse the argument(s) properly.
923 With multiple arguments, each should be enclosed in braces.
924
925 Optional arguments are specified using square brackets or parentheses.
926
927 The braces that start command arguments must not be separated from
928 the other arguments by whitespace. For example, the following produces
929 an error:
930
931 \begin{verbatim}
932 \image{5cm;0cm}
933 {picture.eps}
934 \end{verbatim}
935
936 and should be replaced by
937
938 \begin{verbatim}
939 \image{5cm;0cm}{picture.eps}
940 \end{verbatim}
941
942 \subsection{Avoid the setlength command}
943
944 Using the $\backslash$setlength command doesn't work, since its first
945 argument looks like a command with the wrong number of arguments. Use an
946 alternative form instead, e.g.
947
948 \begin{verbatim}
949 \parindent 0pt
950 \end{verbatim}
951
952 instead of
953
954 \begin{verbatim}
955 \setlength{\parindent}{0pt}
956 \end{verbatim}
957
958 \subsection{Units}\index{units}%
959
960 Only a subset of \LaTeX\ units may be used for specifying dimensions.
961 Valid units are {\tt pt, mm, cm} and {\tt in}. Units should usually
962 be specified for dimensions or the results may be unexpected.
963
964 \subsection{Labels}\index{labels}%
965
966 The \verb$\label$ command may be used for sections and figure captions,
967 but must come immediately after the section or caption commands with no
968 intervening whitespace.
969
970 \subsection{Tables}\label{tables}\index{tables}%
971
972 For best layout, table rows should be enclosed in a \verb$\row$\rtfsp
973 or \verb$\ruledrow$ command, since Tex2RTF can't cope with parsing
974 the \LaTeX\ tabular syntax unaided. However, if you really don't want
975 to go through \LaTeX\ files inserting new syntax, set the {\it compatibility}\rtfsp
976 flag to TRUE in your {\tt tex2rtf.ini} file. In this mode, Tex2RTF tries to make
977 the best of a bad job, but the results won't be optimal (e.g., no table
978 borders). Without this flag set, normal \LaTeX\ tables can crash RTF readers
979 such as Word for Windows.
980
981 \section{Tex2RTF for non-LaTeX users}\index{LaTeX}%
982
983 You don't need to have \LaTeX\ installed to use Tex2RTF. You
984 can still output RTF files to be imported into your favourite
985 word processor, and hypertext files for on-line help.
986
987 This chapter gives a very brief introduction to \LaTeX. For further
988 information, Kopka and Daly's {\it A Guide to \LaTeX} \cite{kopka} is
989 recommended.
990
991 \subsection{What is \LaTeX?}
992
993 \LaTeX\ is a macro package built on top of the typesetting package,
994 \TeX. \TeX\ was written by Donald Knuth in the 1970s, and Leslie
995 Lamport wrote \LaTeX\ as a higher-level, easier way to write \TeX.
996
997 \TeX\ was quite advanced for its day, and is still used (particularly by
998 academics) because of its free availability and its flexibility in
999 typesetting maths and other symbols. It's more like a programming
1000 language than a word processor, with embedded commands prefixed by a
1001 backslash and block structure. Like programs, \TeX\ documents are
1002 processed by a `compiler', outputting a .dvi file, which is a device
1003 independent file which can be read by many converters for output
1004 onto physical devices, such as screens and printers.
1005
1006 A reason for its longevity is the ability to add facilities to
1007 \TeX, using macro packages that define new commands.
1008
1009 \LaTeX\ is the most popular way to write \TeX. Although WYSIWYG
1010 word processors and DTP packages are outstripping \LaTeX, the increasing
1011 interest in hypertext and mark-up languages makes \LaTeX\ relevant as
1012 a similar language to SGML documents (such as World Wide Web HTML files).
1013
1014 Also, languages such as \LaTeX\ (and Rich Text Format, which it resembles
1015 in many ways) are {\it complementary} to WYSIWYG packages. These languages
1016 allow automatic production and translation of documents, where manual
1017 mark-up is impractical or undesirable.
1018
1019 Since the source code of \TeX\ and \LaTeX\ is in the public domain,
1020 there are many free and commercial implementations of \LaTeX\ for almost
1021 every computer in existance. Of PC implementations, EmTeX is arguably
1022 the best and most complete. You can download it from various FTP sites.
1023
1024 If you don't want to use \LaTeX\ itself, you may wish to use a program
1025 called lacheck to check your documents before using Tex2RTF, since it
1026 catches some mistakes that Tex2RTF doesn't.
1027
1028 \subsection{Document structure}
1029
1030 Here is a sample of a typical \LaTeX\ document:
1031
1032 \begin{verbatim}
1033 \documentstyle[a4,texhelp]{report}
1034 \title{A title}
1035 \author{Julian Smart}
1036 \date{October 1993}
1037 \begin{document}
1038 \maketitle
1039
1040 \chapter{Introduction}
1041
1042 ...
1043
1044 \section{A section}
1045
1046 ...
1047
1048 \end{document}
1049 \end{verbatim}
1050
1051 The first line is always a \verb$\documentstyle$ command. The square brackets
1052 enclose optional {\it style} files (suffix {\tt .sty}) that alter the appearance
1053 of the document or provide new commands, and the curly brackets enclose
1054 the mandatory style, in this case `report'.
1055
1056 Before the document begins properly with \verb$\begin{document}$,
1057 you can write various commands that have an effect on the appearance of the
1058 document or define title page information. The \verb$\maketitle$ command
1059 writes the title page using information defined previously (title, author,
1060 date).
1061
1062 A report has chapters, which are divided into sections, and can be further
1063 divided into subsections and subsubsections. To start a new section, you
1064 write the appropriate section command with the section heading; there is
1065 no specific end section command, since a new section heading or the end
1066 of the document will indicate the end of the previous section.
1067
1068 An article is divided into sections, subsections and subsubsections, but
1069 has no chapters. This is so an article can be included in a report as a chapter.
1070
1071 Tex2RTF is written to deal with reports best, so stick with the report
1072 style if you can.
1073
1074 \subsection{Command syntax}
1075
1076 There are several kinds of commands in \LaTeX. Most involve a keyword
1077 prefixed with a backslash. Here are some examples:
1078
1079 \begin{verbatim}
1080 \titlepage
1081
1082 \centerline{This is a centred line}
1083
1084 \begin{center}
1085 This is a centred
1086 paragraph
1087 \end{center}
1088
1089 {\bf This is bold font}
1090 \end{verbatim}
1091
1092 The first example has no arguments. The second has one argument. The third
1093 example is an {\it environment} which uses the begin and end keywords instead
1094 of a pair of braces to enclose an argument (usually one). The fourth is an example
1095 of using a command within a pair of braces: the command applies to the scope within
1096 the braces. Tex2RTF treats this form as if it were a command with one argument,
1097 with the right brace delimiting the argument. In this case, the command must
1098 immediately follow a left brace as shown.
1099
1100 Commands may be nested, but not overlapped.
1101
1102 \subsection{Space}\index{space}%
1103
1104 In \LaTeX, white space is mostly ignored, line breaks make no difference.
1105 However, \LaTeX\ interprets two successive newlines (a blank line) as
1106 denoting a paragraph break. You may also use the \verb$\par$ command to end
1107 a paragraph.
1108
1109 \section{Hypertext features}\index{hypertext}%
1110
1111 \LaTeX\ is inherently suitable for specifying hypertext documents since
1112 it encourages description of the logical structure of a document using
1113 section commands. Therefore, a \LaTeX\ document is automatically
1114 a hypertext document, without any further editing.
1115
1116 For Windows Help, a single RTF file is generated with topics
1117 corresponding to sections. A top level contents page shows each chapter
1118 or top-level section, and each chapter or section ends with a list of
1119 further sections or subsections. Tex2RTF outputs help files that may be
1120 read linearly using the \rtfsp$<<$ and $>>$ buttons.
1121
1122 Similarly, a single wxHelp XLP file is generated.
1123
1124 For HTML, a different file is generated for each section, since the
1125 XMOSAIC browser works best with a large number of small files. The files
1126 are named automatically based on the name of the output file, with the
1127 contents page filename being formed from the output filename with {\tt
1128 \_contents} appended to the name. If the truncateFilenames option is
1129 begin used, then the contents page is just the root name, with a .htm
1130 suffix. The conversion may result in the generation of several hundred
1131 files for a large \LaTeX\ input file.
1132
1133 To specify explicit jumps around a hypertext file, the \commandrefn{helpref}{helpref} command is
1134 used. The first argument is the text to be displayed at the point of reference,
1135 which will be highlighted in a hypertext file to allow jumping to a reference.
1136 The second argument is the reference label (there should be a corresponding
1137 \rtfsp\commandrefn{label}{label} command in the file, following a section or figure).
1138
1139 To use extra Tex2RTF features in proper \LaTeX, such as \verb$\helpref$\rtfsp
1140 and the C++ and CLIPS class reference documentation features, include
1141 the style file {\tt texhelp.sty}.
1142
1143 \section{Special sections}\index{special sections}%
1144
1145 The treatment of bibliography, glossary and index are worth special mention.
1146
1147 \subsection{Bibliography}\label{bibsection}\index{bibliography}%
1148
1149 Tex2RTF recognises standard \LaTeX\ bibliography files (usually with {\tt .bib} extension)
1150 and resolves citations. The \commandrefn{bibliography}{bibliographycmd}\rtfsp
1151 command reads the given {\tt .bib} file and includes a list of
1152 references at that point in the input. Only numbered, unsorted
1153 references are catered for at the moment, with no variation in
1154 bibliography style. A {\bf References} heading is placed in the contents
1155 section. Note that Tex2RTF must be run twice to ensure the citations are
1156 resolved properly.
1157
1158 Tex2RTF can also cope with the \verb$\thebibliography$ environment, with \rtfsp
1159 \verb$\bibitem$ commands, so long as the text following the first \verb$\bibitem$\rtfsp
1160 argument is enclosed in braces as if it were a second argument.
1161
1162 \subsection{Glossary}\label{glossarysection}\index{glossary}%
1163
1164 Glossaries are formatted according to the following scheme.
1165 The \commandrefn{helpglossary}{helpglossary} environment is used together with
1166 the \commandrefn{gloss}{gloss} command for glossary entries. In \LaTeX\ this
1167 is interpreted as a description list, and each glossary entry is an item.
1168 In on-line help, each glossary entry is a section.
1169
1170 A labelled glossary entry command may be referenced by \commandrefn{popref}{popref}\rtfsp
1171 to provide a quick popup explanation of a term.
1172
1173 \subsection{Index}\index{index}%
1174
1175 The explicit index is assumed to be redundant in on-line help, since
1176 search facilities are provided. Therefore the \verb$\printindex$ command
1177 does nothing in on-line versions. In linear RTF an index field is
1178 added, and \commandrefn{index}{index} marks words for inserting in the index.
1179
1180 In Windows Help, all section headings and C++ function names are treated
1181 as keywords. A keyword may be ambiguous, that is, refer to more than one
1182 section in the help file. This automatic indexing may not always be
1183 adequate, so the \LaTeX\ \commandrefn{index}{index} command may be used
1184 to add keywords.
1185
1186 In wxHelp, all section headings are indexed.
1187
1188 \section{Authoring HTML documents}
1189
1190 When an HTML document is generated, the suffix `\_contents' is appended
1191 to the input file root. This will be the contents page for the document.
1192 A number of further HTML files will be generated, possibly a large number
1193 for a document with a large number of sections. If you are running
1194 a 16-bit Windows version of Tex2RTF, you may wish to use
1195 the {\it truncateFilenames} option to generate DOS filenames with
1196 appropriately truncated references inside the HTML files.
1197
1198 \normalbox{Tip: to reduce the number of sections generated and make
1199 the document more linear, you could define new chapter and section
1200 commands. Alias them to the normal commands in real LaTeX (edit {\tt texhelp.sty}), and
1201 to appropriate bold/large headings (but not section commands) in
1202 the Tex2RTF initialisation file.}
1203
1204 Each HTML section file (except for the contents page) is given browse
1205 buttons, similar to a Windows Help file: Contents, Up, Down, Back, Forward.
1206 You can set {\it htmlBrowseButtons} to specify whether bitmaps or text should
1207 be used for these buttons. On a text-only browser, the buttons will show
1208 as text even if images have been specified.
1209
1210 As well as the usual jumps within a document, you can use the \commandref{urlref}{urlref} command to jump
1211 to other documents. `Advanced features' which are implemented for HTML include:
1212
1213 \begin{itemize}\itemsep=0pt
1214 \item Simple tables: \commandref{tabular}{tabular} command
1215 \item Background colour/bitmap: \commandref{backgroundcolour}{backgroundcolour} and
1216 \rtfsp\commandref{backgroundimage}{backgroundimage}
1217 \item Text colour: \commandref{textcolour}{textcolour} command
1218 \end{itemize}
1219
1220 See \helpref{HTML options}{htmloptions} for relevant initialisation file
1221 switches.
1222
1223 \section{Authoring Windows Help documents}\index{WinHelp files}%
1224
1225 To produce a Windows Help file, you need to generate a WinHelp RTF file
1226 with Tex2RTF and then invoke a Windows Help compiler (such as hc505.exe)
1227 to translate this to a .hlp file.
1228
1229 WinHelp support has split into two streams, Windows 3.1 help format
1230 and Windows 95 (WinHelp 4) format. You control this with the {\it winHelpVersion} option,
1231 setting it to 3 for Windows 3.1, and 4 for Windows 95. In the latter case,
1232 you also need the Help Compiler for Windows (hcw.exe and associated components)
1233 which are available in the WIN32 SDK and with Windows 95 compilers.
1234
1235 Tex2RTF can produce a Windows 95 {\tt .cnt} file if {\it winHelpContents}\index{CNT file} is switched
1236 on. This file is used to generate the new-style contents page, allowing
1237 hierarchical browsing of the topic contents. In fact this file can be used
1238 with ordinary Windows 3.1 files on Windows 95: so to hedge your bets,
1239 generate a Windows 3.1 help file along with {\tt .cnt} file.
1240
1241 Tex2RTF also generates (optionally) a {\tt .hpj} (Help Project) file\index{HPJ file} which is
1242 fed to the help compiler and specifies the RTF file being used amongst
1243 other things. In WinHelp 4 mode, Tex2RTF adds entries to the project
1244 to enhance the appearance of the help file. In particular, the
1245 non-scrolling (topic title) region is coloured grey, and the rest
1246 is coloured a light yellow in keeping with other Windows 95 help
1247 files.
1248
1249 \normalbox{Tip: you can maintain two versions of a help file
1250 by specifying an alternative {\tt .ini} file on the command
1251 line when invoking Tex2RTF, and compiling to a different directory.
1252 Tex2RTF instructs the help compiler to use the input file directory
1253 to find bitmaps and metafiles, so using a different output directory
1254 is not a problem. See the Tex2RTF {\tt src/makefile.dos} for an example
1255 of maintaining both formats.}
1256
1257 There is a slight wrinkle with generation of the {\tt .cnt} file:
1258 to work around a `feature' in the Windows 95 help compiler, Tex2RTF may insert
1259 extra book icons in the contents page. So your contents page
1260 may not exactly match the structure in your LaTeX file.
1261
1262 `Advanced features' which are implemented for WinHelp include:
1263
1264 \begin{itemize}\itemsep=0pt
1265 \item Transparency: \commandref{settransparency}{settransparency} command
1266 \item Colour: \commandref{definecolour}{definecolour}, \commandref{fcol}{fcol}, \commandref{bcol}{bcol} commands
1267 \item Hot spot appearance: \commandref{sethotspotcolour}{sethotspotcolour}, \commandref{sethotspotunderline}{sethotspotunderline} commands
1268 \end{itemize}
1269
1270 Tex2RTF automatically generates browse buttons for jumping to the
1271 above, previous and next topics.
1272
1273 See \helpref{RTF/WinHelp options}{rtfwinhelpoptions} for
1274 relevant initialisation file switches.
1275
1276 \section{Authoring linear RTF documents}\index{RTF}%
1277
1278 Linear RTF documents come in two main flavours. It can produce simple
1279 RTF that can be read by a wide variety of readers, such as
1280 Windows 95 WordPad, the Windows 95 viewer, and most word processors.
1281 Tex2RTF can also output MS Word compatible RTF which has special
1282 fields for contents page and index formatting, headings, and
1283 other enhancements.
1284
1285 Use the {\it useWord} initialisation file flag to switch Word mode
1286 on or off.
1287 Hypertext links (using \verb$\helpref$ and other commands) will be formatted as
1288 bold `anchor' text plus a section or figure number in parentheses.
1289
1290 In Word mode, using an index section generates a proper Word index.
1291 Similarly, a Word table of contents, list of figures, list of tables
1292 and page reference may be generated.
1293
1294 See \helpref{RTF/WinHelp options}{rtfwinhelpoptions} for
1295 relevant initialisation file switches.
1296
1297 \section{Authoring wxHelp documents}\index{wxHelp}%
1298
1299 The wxHelp (.xlp) file is the most basic kind of file that Tex2RTF
1300 can handle. Since spacing is passed through to the output, you need to
1301 format your input document appropriately, with lines of reasonable length.
1302
1303 The generated xlp file is an ASCII file that can be read directly by
1304 wxHelp, the generic wxWidgets help viewer.
1305
1306 \chapter{Command reference}\index{command reference}%
1307 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
1308 \setfooter{\thepage}{}{}{}{}{\thepage}%
1309
1310 The following lists commands which are recognised by the converters. The reader
1311 can assume that commands not mentioned here are unrecognised or ignored.
1312
1313 Each command is listed with its name, the number of arguments it takes
1314 (excluding optional arguments), and a description. Note that if the
1315 command is used as an environment (using \verb$\begin$ and \verb$\end$) then
1316 the number of arguments must be either one or two. For example, the\rtfsp
1317 \verb$\tabular$ environment takes two arguments: a first argument for
1318 specifying the formatting, and the second argument for the body of the
1319 environment.
1320
1321 \begin{verbatim}
1322 \begin{tabular}{|l|l|}
1323 \row{One&Two}
1324 \row{Three&Four}
1325 \end{tabular}
1326 \end{verbatim}
1327
1328 \section{\LaTeX\ Commands}
1329
1330 \subsection*{abstract:1}\label{abstract}
1331
1332 This standard \LaTeX\ environment prepares an abstract page, and is
1333 treated as an ordinary chapter or section in on-line help.
1334
1335 \subsection*{addcontentsline:3}\label{addcontentsline}
1336
1337 Adds a chapter title to the contents page. Linear RTF. Rarely required.
1338
1339 %\subsection*{appendix}
1340 %\subsection*{arabic}
1341 %\subsection*{array}
1342 \subsection*{author:1}\label{author}
1343
1344 Defines the author, for output when \verb$\maketitle$ is used.
1345
1346 \subsection*{backslash:0}\label{backslash}
1347
1348 Outputs a backslash in math mode (should be enclosed by two dollar symbols).
1349
1350 \subsection*{bf:1}\label{bf}
1351
1352 Specifies bold font.
1353
1354 \subsection*{bffamily:1}\label{bffamily}
1355
1356 Specifies bold font.
1357
1358 \subsection*{bibitem:2}\label{bibitem}
1359
1360 For parsing convenience, \verb$\bibitem$ requires two arguments: a cite key and item.
1361 \rtfsp\LaTeX\ syntax permits writing this as if it were two arguments,
1362 even though it is in fact only one. This command is used within
1363 a \commandrefn{thebibliography}{thebibliography} environment. The preferred
1364 method is to store references in {\tt .bib} files and use the \commandrefn{bibliography}{bibliographycmd}\rtfsp
1365 command to generate a bibliography section automatically.
1366
1367 \subsection*{bibliographystyle:1}\label{bibliographystyle}
1368
1369 Currently doesn't affect the style of bibliography, but probably will
1370 in the future.
1371
1372 \subsection*{bibliography:0}\label{bibliographycmd}
1373
1374 Includes the bibliography at this point in the document. See the section
1375 on \helpref{bibliographies}{bibsection}.
1376
1377 %\subsection*{caption*}
1378 \subsection*{caption:1}\label{caption}
1379
1380 Specifies a caption (within a \commandrefn{figure}{figure} or \commandrefn{table}{table} environment). This may
1381 be followed immediately by a \commandrefn{label}{label} command.
1382
1383 \subsection*{cdots:0}\label{cdots}
1384
1385 Outputs three dots.
1386
1387 \subsection*{centerline:1}\label{centerline}
1388
1389 Centres (or centers!) a line of text.
1390
1391 %\subsection*{centering}
1392 \subsection*{center:1}\label{center}
1393
1394 Centres a block of text.
1395
1396 \subsection*{chapter:1}\label{chapter}
1397
1398 Outputs a chapter heading. If the chapter's name is Popups\index{popups}, the chapter title will not be
1399 put in the contents, to allow popups to be placed in a document without the popup
1400 sections being directly accessible.
1401
1402 \subsection*{chapter*:1}\label{chaptersX}
1403
1404 Outputs a chapter heading with no contents entry.
1405
1406 \subsection*{cite:1}\label{cite}
1407
1408 Cite a reference. The argument is a reference key as defined in a \LaTeX\ {\tt .bib}\rtfsp
1409 file.
1410
1411 \subsection*{comment:1}\label{comment}
1412
1413 An environment that allows large comments in \LaTeX\ files: the argument
1414 is ignored in all formats. Useful for commenting out parts of files that
1415 cannot be handled by \LaTeX, such as the picture environment. See also\rtfsp
1416 \commandrefn{toocomplex}{toocomplex}.
1417
1418 \subsection*{date:1}\label{date}
1419
1420 Specifies the date of a document; only output by \commandrefn{maketitle}{maketitle}.
1421
1422 \subsection*{description:1}\label{description}
1423
1424 A list environment, where each \commandrefn{item}{item} command must be
1425 followed by optional square-bracketed text which will be highlighted.
1426
1427 %\subsection*{destruct:1}\label{destruct}
1428
1429 \subsection*{document:1}\label{document}
1430
1431 This environment should enclose the body of a document.
1432
1433 \subsection*{documentstyle:1}\label{documentstyle}
1434
1435 Specifies the main style (report, article etc.) and, optionally, style files
1436 such as {\tt texhelp.sty}. A report has \commandrefn{chapters}{chapter}, while an article's top-level
1437 sections are specified using \commandrefn{section}{section}.
1438
1439 %\subsection*{doublespace}\label{doublespace}
1440 \subsection*{em:1}\label{em}
1441
1442 Emphasizes text (italic in RTF).
1443
1444 \subsection*{emph:1}\label{emph}
1445
1446 Same as \commandrefn{em}{em}.
1447
1448 \subsection*{enumerate:1}\label{enumerate}
1449
1450 Enumerate list environment: numbers the \commandrefn{items}{item}.
1451
1452 %\subsection*{equation}\label{equation}
1453 %\subsection*{evensidemargin}
1454 %\subsection*{fbox:1}\label{fbox}
1455
1456 \subsection*{figure:1}\label{figure}
1457
1458 A figure environment: does nothing special, except allows interpretation of
1459 embedded \helpref{caption}{caption} commands as figures rather than (say) tables.
1460
1461 \subsection*{flushleft:1}\label{flushleft}
1462
1463 Flushes the given text to the left margin.
1464
1465 \subsection*{flushright:1}\label{flushright}
1466
1467 Flushes the given text to the right margin.
1468
1469 %\subsection*{footheight}\label{footheight}
1470 \subsection*{footnote:1}\label{footnote}
1471
1472 In linear RTF, a footnote is created. Whether this appears at the end of
1473 the section or the bottom of the page appears to depend on the current
1474 document style, at least for MS Word 6.0 for Windows. The default seems
1475 to be to put the footnotes at the end of the section, which is probably
1476 not the best assumption.
1477
1478 In WinHelp RTF, a bracketed number is generated for the footnote
1479 and the footnote becomes a popup topic. It is probably preferable
1480 to change footnote commands to \commandref{footnotepopup}{footnotepopup},
1481 or \commandref{popref}{popref} references to glossary entries.
1482
1483 This command is not supported for formats other than \LaTeX,
1484 linear RTF and WinHelp RTF.
1485
1486 \subsection*{hline:0}\label{hline}
1487
1488 Within a \commandrefn{tabular}{tabular} environment, draws a horizontal
1489 rule below the current row. Note that this does not work in RTF for the
1490 last row of a table, in which case the command \commandrefn{ruledrow}{ruledrow}\rtfsp
1491 should be used instead.
1492
1493 \subsection*{hrule:0}\label{hrule}
1494
1495 Draws a horizontal line below the current paragraph. For example:
1496
1497 \begin{verbatim}
1498 This paragraph should have a horizontal rule following it.\hrule
1499 \end{verbatim}
1500
1501 gives:
1502
1503 This paragraph should have a horizontal rule following it.\hrule
1504
1505 %\subsection*{hspace*}\label{hspaceX}
1506 %\subsection*{hspace}\label{hspace}
1507 %\subsection*{hskip*}\label{hskipX}
1508 %\subsection*{hskip}\label{hskip}
1509
1510 \subsection*{huge:1}\label{huge1}
1511
1512 Outputs the argument in huge text.
1513
1514 \subsection*{Huge:1}\label{Huge2}
1515
1516 Outputs the argument in huger text than \commandrefn{huge}{huge1}.
1517
1518 \subsection*{HUGE:1}\label{HUGE3}
1519
1520 Outputs the argument in huger text than \commandrefn{Huge}{Huge2}.
1521
1522 \subsection*{include:1}\label{include}
1523
1524 Include the given file. The command must not be preceded by any whitespace,
1525 and spurious whitespace between elements of the command will also
1526 trip up Tex2RTF.
1527
1528 \subsection*{index:1}\label{index}
1529
1530 In WinHelp mode, adds a keyword to the keyword list for the current
1531 topic. This keyword must currently be straight text, with no embedded
1532 commands. The conversion process must be run twice (without quitting
1533 Tex2RTF inbetween) to resolve the keyword references.
1534
1535 \subsection*{input:1}\label{input}
1536
1537 Include the given file. The command must not be preceded by any whitespace,
1538 and spurious whitespace between elements of the command will also
1539 trip up Tex2RTF.
1540
1541 \subsection*{insertatlevel:2}\label{insertatlevel}
1542
1543 Insert some text at a particular level of the document. For example,
1544
1545 \begin{verbatim}
1546 \insertatlevel{2}{Some text}
1547 \end{verbatim}
1548
1549 inserts "Some text" at level 2 (for a report, the current section). This
1550 allows you to insert headings into an automatically-generated section contents,
1551 for example.
1552
1553 \subsection*{it:1}\label{it}
1554
1555 Marks the argument in italic.
1556
1557 \subsection*{itemize:1}\label{itemize}
1558
1559 Indents each \commandrefn{item}{item} of a list and precedes with a bullet.
1560 If the file {\tt bullet.bmp} is found by Tex2RTF, this bitmap will be
1561 used as the bullet (WinHelp RTF); otherwise, a symbol or bold `o' will be used instead,
1562 depending on output format.
1563
1564 Use \commandrefn{itemsep}{itemsep} to specify the separation between
1565 list items. Currently this only works for linear or WinHelp RTF output.
1566 If the value is more than zero, an extra paragraph is inserted.
1567
1568 \subsection*{item:0}\label{item}
1569
1570 Marks an item of a \commandrefn{itemize}{itemize}, \commandrefn{description}{description} or \commandrefn{enumerate}{enumerate}
1571 list. Items within a description environment should have an `optional' argument
1572 in square brackets which will be highlighted.
1573
1574 \subsection*{itemsep:0}\label{itemsep}
1575
1576 Use this command to specify the separation between
1577 list items. Currently this only works for linear or WinHelp RTF output.
1578 If the value is zero, no extra paragraph is inserted; if the value
1579 is more than zero, an extra paragraph is inserted.
1580
1581 \subsection*{itshape:1}\label{itshape}
1582
1583 Marks the argument in italic.
1584
1585 %\subsection*{kill}\label{kill}
1586 \subsection*{label:1}\label{label}
1587
1588 Labels the chapter, section, subsection, subsubsection or figure caption
1589 with the given label. This must be an ASCII string, and duplicate items
1590 with different case letters are not allowed.
1591
1592 The command must follow immediately after the section or caption command,
1593 with no intervening whitespace.
1594
1595 \subsection*{large:1}\label{large1}
1596
1597 Marks the argument in large text.
1598
1599 \subsection*{Large:1}\label{Large2}
1600
1601 Makes the argument display in larger text than \commandrefn{large}{large1}.
1602
1603 \subsection*{LARGE:1}\label{LARGE3}
1604
1605 Makes the argument display in larger text than \commandrefn{Large}{Large2}.
1606
1607 \subsection*{LaTeX:0}\label{LaTeX}
1608
1609 Outputs the annoying \LaTeX\ upper and lower case name.
1610
1611 \subsection*{ldots:0}\label{ldots}
1612
1613 Outputs three dots.
1614
1615 %\subsection*{linebreak}\label{linebreak}
1616 %\subsection*{listoffigures}\label{listoffigures}
1617 %\subsection*{listoftables}\label{listoftables}
1618 %\subsection*{makeglossary}\label{makeglossary}
1619 %\subsection*{makeindex}\label{makeindex}
1620 \subsection*{maketitle:0}\label{maketitle}
1621
1622 Makes the article or report title by outputting the \commandrefn{title}{title},
1623 \rtfsp\commandrefn{author}{author} and optionally \commandrefn{date}{date}.
1624
1625 %\subsection*{markright}\label{markright}
1626 %\subsection*{markboth}\label{markboth}
1627
1628 \subsection*{marginparwidth:1}\label{marginparwidth}
1629
1630 Specifies the width of a margin paragraph.
1631
1632 \subsection*{marginpar:1}\label{marginpar}
1633
1634 Inserts a marginal note. It is best to use the Tex2RTF extensions \rtfsp
1635 \commandrefn{marginparodd}{marginparodd} and \commandrefn{marginpareven}{marginpareven} \rtfsp
1636 for best results.
1637
1638 \subsection*{marginpareven:1}\label{marginpareven}
1639
1640 Inserts a marginal note on even pages. This is required for RTF generation since
1641 it is impossible for Tex2RTF to know in advance which side of paper the marginal note
1642 will fall upon, and the text has to be positioned using absolute dimensions.
1643 If only one sided output is required, use \commandrefn{marginparodd}{marginparodd} \rtfsp
1644 instead.
1645
1646 \subsection*{marginparodd:1}\label{marginparodd}
1647
1648 Inserts a marginal note on odd pages. This is required for RTF generation since
1649 it is impossible for Tex2RTF to know in advance which side of paper the marginal note
1650 will fall upon, and the text has to be positioned using absolute dimensions.
1651
1652 Also, even if one-sided output is required, this command should be used instead
1653 of \verb$\marginpar$ because the \LaTeX\ command allows it to be used
1654 just before a paragraph. Normally, if this were done, the marginal note would
1655 not be aligned with the paragraph succeeding it. For example:
1656
1657 \begin{verbatim}
1658 \marginparodd{{\it Note:} if nothing happens, perhaps you
1659 have not plugged your computer in at the mains.}%
1660 To start using your computer, push the Power button
1661 and wait for text to appear on the screen.
1662 \end{verbatim}
1663
1664 Note the percent sign after the \verb$\marginparodd$ command: without it,
1665 \LaTeX\ refuses to believe that the following text is part of the
1666 same paragraph, and will print the note at the wrong place.
1667
1668 You should use \commandrefn{textwidth}{textwidth} to allow space for marginal
1669 notes, and also \commandrefn{marginparwidth}{marginparwidth} to specify the size of
1670 the marginal note.
1671
1672 In WinHelp, HTML and wxHelp, marginal notes are treated as normal text delineated
1673 with horizontal rules above and below.
1674
1675 %\subsection*{mbox:1}\label{mbox}
1676
1677 \subsection*{mdseries:1}\label{mdseries}
1678
1679 Changes to a medium-weight font. Un-emboldens in RTF mode, no effect in other modes.
1680
1681 \subsection*{multicolumn:3}\label{multicolumn}
1682
1683 Used in \commandrefn{tabular}{tabular} environment to denote a cell that
1684 spans more than one column. Only supplied for compatibility with
1685 existing \LaTeX\ files, since all it does in RTF is output the correct
1686 number of cell commands, with the multicolumn text squashed into one cell.
1687
1688 \subsection*{newcommand:3}\label{newcommand}
1689
1690 Define a new command; arguments are the command, the number of
1691 arguments, and the command body. For example:
1692
1693 \begin{verbatim}
1694 \newcommand{\crazy}[2]{{\bf #1} is crazy but {\bf #2} is not.}
1695 \end{verbatim}
1696
1697 The command must have no whitespace at the start of the line or between
1698 the three arguments.
1699
1700 New commands may also be defined in the {\tt tex2rtf.ini} file using
1701 slightly different syntax (see \helpref{Macro not found error}{macronotfound}).
1702
1703 %\subsection*{newcounter}\label{newcounter}
1704 %\subsection*{newline}\label{newline}
1705 \subsection*{newpage:0}\label{newpage}
1706
1707 Inserts a page break.
1708
1709 \subsection*{nocite:1}\label{nocite}
1710
1711 Specifies that this reference should appear in the bibliography,
1712 but the citation should not appear in the text.
1713
1714 See also \commandrefn{cite}{cite}.
1715
1716 \subsection*{noindent:0}\label{noindent}
1717
1718 Sets paragraph indentation to zero. See also \commandrefn{parindent}{parindent}.
1719
1720 %\subsection*{nolinebreak}\label{nolinebreak}
1721 %\subsection*{nopagebreak}\label{nopagebreak}
1722
1723 \subsection*{normalsize:1}\label{normalsize}
1724
1725 Sets the font size back to normal.
1726
1727 \subsection*{onecolumn:0}\label{onecolumn}
1728
1729 Sets the number of columns to one. \LaTeX\ and linear RTF only.
1730
1731 %\subsection*{oddsidemargin}\label{oddsidemargin}
1732 %\subsection*{pagebreak}\label{pagebreak}
1733 \subsection*{pageref:1}\label{pageref}
1734
1735 In linear RTF, generates a page reference to the given label.
1736
1737 \subsection*{pagestyle:1}\label{pagestyle}
1738
1739 If argument is {\tt fancyplain} or {\tt fancy}, Tex2RTF
1740 separates the header from the rest of the page with a rule.
1741 This command must be defined for headers and footers to
1742 work properly. See also \commandrefn{setheader}{setheader},
1743 \commandrefn{setfooter}{setfooter}.
1744
1745 \LaTeX\ and linear RTF only.
1746
1747 \subsection*{pagenumbering:1}\label{pagenumbering}
1748
1749 The argument may be one of:
1750
1751 \begin{description}
1752 \itemsep=0pt
1753 \item[alph] a, b, ...
1754 \item[Alph] A, B, ...
1755 \item[arabic] 1, 2, ...
1756 \item[roman] i, ii, ...
1757 \item[Roman] I, II, ...
1758 \end{description}
1759
1760 \LaTeX\ and linear RTF only.
1761
1762 \subsection*{paragraph:0}\label{paragraph}
1763
1764 Behaves as for a subsubsection.
1765
1766 \subsection*{paragraph*:0}\label{paragraphX}
1767
1768 Behaves as for a subsubsection.
1769
1770 \subsection*{parindent:1}\label{parindent}
1771
1772 Indents the first line of succeeding paragraphs by the given amount.
1773
1774 \subsection*{parskip:1}\label{parskip}
1775
1776 Changes the spacing between paragraphs. In fact, in RTF this will cause
1777 two \commandrefn{par}{par} commands to be output if parskip is greater
1778 than zero.
1779
1780 %\subsection*{part*}\label{partX}
1781 %\subsection*{part}\label{part}
1782 \subsection*{par:0}\label{par}
1783
1784 Causes the paragraph to end at this point. \LaTeX\ and Tex2RTF also
1785 treat two consecutive newlines as a paragraph break.
1786
1787 %\subsection*{pfunc}\label{pfunc}
1788 %\subsection*{picture}\label{picture}
1789 \subsection*{printindex:0}\label{printindex}
1790
1791 In linear RTF, inserts an index.
1792
1793 \subsection*{quote:1}\label{quote}
1794
1795 Indents a short quotation.
1796
1797 \subsection*{quotation:1}\label{quotation}
1798
1799 Indents a long quotation.
1800
1801 %\subsection*{raggedbottom}\label{raggedbottom}
1802 %\subsection*{raggedleft}\label{raggedleft}
1803 %\subsection*{raggedright}\label{raggedright}
1804
1805 \subsection*{ref:1}\label{ref}
1806
1807 In \LaTeX\ and linear RTF, refers to a \commandrefn{label}{label} and
1808 causes the number of that section or figure to be printed.
1809
1810 \subsection*{rm:1}\label{rm}
1811
1812 Causes the argument to be formatted in a plain, roman font.
1813 In fact, does nothing in RTF, HTML and XLP modes.
1814
1815 \subsection*{rmfamily:1}\label{rmfamily}
1816
1817 Causes the argument to be formatted in a plain, roman font.
1818 In fact, does nothing in RTF, HTML and XLP modes.
1819
1820 %\subsection*{roman}\label{roman1}
1821 %\subsection*{Roman}\label{Roman2}
1822
1823 \subsection*{sc:1}\label{sc}
1824
1825 Prints the output in small capitals.
1826
1827 \subsection*{scshape:1}\label{scshape}
1828
1829 Prints the output in small capitals.
1830
1831 \subsection*{section:1}\label{section}
1832
1833 Section header, with an entry in the contents page.
1834
1835 \subsection*{section*:1}\label{sectionX}
1836
1837 Section header, with no entry in the contents page.
1838
1839 %\subsection*{setcounter}\label{setcounter}
1840 \subsection*{sf:1}\label{sf}
1841
1842 Should format in a sans-serif font. Does nothing in Tex2RTF.
1843
1844 \subsection*{sffamily:1}\label{sffamily}
1845
1846 Should format in a sans-serif font. Does nothing in Tex2RTF.
1847
1848 \subsection*{shortcite:1}\label{shortcite}
1849
1850 The same as \commandrefn{cite}{cite}.
1851
1852 %\subsection*{singlespace}\label{singlespace}
1853 %\subsection*{sloppypar}\label{sloppypar}
1854 %\subsection*{sloppy}\label{sloppy}
1855
1856 \subsection*{sl:1}\label{sl}
1857
1858 In Tex2RTF, the same as \commandrefn{it}{it}. The LaTeX interpretation is `slanted text'.
1859
1860 \subsection*{slshape:1}\label{slshape}
1861
1862 In Tex2RTF, the same as \commandrefn{itshape}{itshape}. The LaTeX interpretation is `slanted text'.
1863
1864 \subsection*{small:1}\label{small}
1865
1866 Prints the argument in a small font.
1867
1868 \subsection*{special:1}\label{special}
1869
1870 Simply copies the argument to the output file without processing
1871 (except \verb$\}$ is translated to \verb$}$, and \verb$\{$ is
1872 translated to \verb${$, to allow for insertion of braces).
1873
1874 \subsection*{ss:0}\label{ss}
1875
1876 Outputs the German sharp S character \ss.
1877
1878 %\subsection*{subitem}\label{subitem}
1879 \subsection*{subparagraph:1}\label{subparagraph}
1880
1881 Behaves as for a subsubsection.
1882
1883 \subsection*{subparagraph*:1}\label{subparagraphX}
1884
1885 Behaves as for a subsubsection.
1886
1887 \subsection*{subsection:1}\label{subsection}
1888
1889 Subsection header, with an entry in the contents page.
1890
1891 \subsection*{subsection*:1}\label{subsectionX}
1892
1893 Subsection header, with no entry in the contents page.
1894
1895 \subsection*{subsubsection:1}\label{subsubsection}
1896
1897 Subsubsection header, with an entry in the contents page.
1898
1899 \subsection*{subsubsection*:1}\label{subsubsectionX}
1900
1901 Subsubsection header, with no entry in the contents page.
1902
1903 \subsection*{tabbing:1}\label{tabbing}
1904
1905 Tabbing environment: doesn't work properly in RTF.
1906
1907 \subsection*{table:1}\label{table}
1908
1909 An environment for tables. The only thing that Tex2RTF does with this
1910 is to interpret an embedded \helpref{caption}{caption} command differently
1911 from figures.
1912
1913 \subsection*{tableofcontents:0}\label{tableofcontents}
1914
1915 Inserts the table of contents at this point. In linear RTF mode, a
1916 proper Word for Windows table of contents will be inserted unless either
1917 of the variables {\it insertTOC} or {\it useWord} is set to {\it false}.
1918
1919 \subsection*{tabular:2}\label{tabular}
1920
1921 Tabular environment: an attempt is made to output something
1922 reasonable in RTF and HTML formats, although currently only simple
1923 tables will work. The first argument specifies the column formatting.
1924 a pipe symbol (\verb$|$) denotes a vertical border, one of {\tt l, r, c}\rtfsp
1925 signifies a normal column of default width, and {\tt p} followed by
1926 a dimension specifies a column of given width. It is recommended that
1927 the {\tt p} is used since Tex2RTF cannot deduce a column width in the
1928 same way that \LaTeX\ can.
1929
1930 Horizontal rules are achieved with \commandrefn{hline}{hline}; two together
1931 signify a double rule. Note that in HTML, all rows and the table itself are bordered
1932 automatically.
1933
1934 Use the Tex2RTF \commandrefn{row}{row} and \commandrefn{ruledrow}{ruledrow} commands
1935 for best effect.
1936
1937 For two-column tables that work in WinHelp files, use \commandrefn{twocollist}{twocollist} instead.
1938
1939 Example:
1940
1941 \begin{verbatim}
1942 \begin{tabular}{|l|p{8.5cm}|}\hline
1943 \row{{\bf A.I.}&{\bf Simulation}}\hline\hline
1944 \row{rules&constraints/methods}
1945 \row{planning&design of experiments}
1946 \row{diagnosis&analysis of results}
1947 \ruledrow{learning&detection of connections}
1948 \end{tabular}
1949 \end{verbatim}
1950
1951 This produces:
1952
1953 \begin{tabular}{|l|p{8.5cm}|}\hline
1954 \row{{\bf A.I.}&{\bf Simulation}}\hline\hline
1955 \row{rules&constraints/methods}
1956 \row{planning&design of experiments}
1957 \row{diagnosis&analysis of results}
1958 \ruledrow{learning&detection of connections}
1959 \end{tabular}
1960
1961 %\subsection*{tab:1}\label{tab}
1962 \subsection*{TeX:0}\label{TeX}
1963
1964 Outputs the annoying \TeX\ upper and lower case name.
1965
1966 \subsection*{textbf:1}\label{textbf}
1967
1968 Same as \commandrefn{bf}{bf}.
1969
1970 \subsection*{textit:1}\label{textit}
1971
1972 Same as \commandrefn{it}{it}.
1973
1974 \subsection*{textrm:1}\label{textrm}
1975
1976 Same as \commandrefn{rm}{rm}.
1977
1978 \subsection*{textsf:1}\label{textsf}
1979
1980 Same as \commandrefn{sf}{sf}.
1981
1982 \subsection*{textsc:1}\label{textsc}
1983
1984 Same as \commandrefn{sc}{sc}.
1985
1986 \subsection*{textsl:1}\label{textsl}
1987
1988 Same as \commandrefn{sl}{sl}.
1989
1990 \subsection*{texttt:1}\label{texttt}
1991
1992 Same as \commandrefn{tt}{tt}.
1993
1994
1995 \subsection*{textwidth:1}\label{textwidth}
1996
1997 Sets the text width (valid for RTF only). This might be used
1998 in conjunction with \commandrefn{marginpar}{marginpar}, for example,
1999 to leave space for marginal notes.
2000
2001 %\subsection*{textheight}\label{textheight}
2002 \subsection*{thebibliography:1}\label{thebibliography}
2003
2004 An environment for specifying the bibliography as a series of\rtfsp
2005 \commandrefn{bibitem}{bibitem} commands; the preferred method is to use
2006 \rtfsp{\tt .bib} files and \commandrefn{bibliography}{bibliographycmd} instead.
2007
2008 %\subsection*{titlepage:0}\label{titlepage}
2009
2010 \subsection*{title:1}\label{title}
2011
2012 Sets the title, to be output when the command \commandrefn{maketitle}{maketitle}\rtfsp
2013 is used.
2014
2015 \subsection*{tiny:1}\label{tiny}
2016
2017 Prints the argument in a very small font.
2018
2019 \subsection*{today:0}\label{today}
2020
2021 Outputs today's date.
2022
2023 %\subsection*{topmargin}\label{topmargin}
2024 %\subsection*{topskip}\label{topskip}
2025 \subsection*{tt:1}\label{tt}
2026
2027 Outputs the argument in teletype font.
2028
2029 \subsection*{ttfamily:1}\label{ttfamily}
2030
2031 Outputs the argument in teletype font.
2032
2033 %\subsection*{typein}\label{typein}
2034 \subsection*{typeout:1}\label{typeout}
2035
2036 Outputs the text on the Tex2RTF text window.
2037
2038 \subsection*{twocolumn:0}\label{twocolumn}
2039
2040 Sets the number of columns to two. \LaTeX\ and linear RTF only.
2041
2042 \subsection*{underline:1}\label{underline}
2043
2044 Underlines the argument.
2045
2046 \subsection*{upshape:1}\label{upshape}
2047
2048 Changes to an upright font. Un-italicizes in RTF mode, no effect in other modes.
2049
2050 \subsection*{verbatiminput:1}\label{verbatiminput}
2051
2052 Include the given file as if it were within a \commandrefn{verbatim}{verbatim}\rtfsp
2053 environment. The command must not be preceded by any whitespace,
2054 and spurious whitespace between elements of the command will also
2055 trip up Tex2RTF.
2056
2057 \subsection*{verbatim:1}\label{verbatim}
2058
2059 Uses a fixed-width font to format the argument without interpreting
2060 any \LaTeX\ commands.
2061
2062 \subsection*{verb}\label{verb}
2063
2064 The \verb$\verb$ command is like the \commandref{verbatim}{verbatim} environment,
2065 but for small amounts of text. The syntax is:
2066
2067 \begin{verbatim}
2068 \verb<char><text><char>
2069 \end{verbatim}
2070
2071 The character {\it char} is used as a delimiter; it may be any character
2072 not ocurring in the following text, except asterisk.
2073
2074 For example, \verb@\verb$\thing%^&$@ produces \verb$\thing%^&$.
2075
2076 %\subsection*{verse}\label{verse}
2077 %\subsection*{vfill}\label{vfill}
2078 %\subsection*{vline}\label{vline}
2079 %\subsection*{void}\label{void}
2080 %\subsection*{vrule}\label{vrule}
2081 %\subsection*{vspace*}\label{vspaceX}
2082 %\subsection*{vskip*}\label{vskipX}
2083 %\subsection*{vspace}\label{vspace}
2084 %\subsection*{vskip}\label{vskip}
2085
2086
2087 \section{Tex2RTF Commands}
2088
2089 \subsection*{backgroundcolour:1}\label{backgroundcolour}
2090
2091 Specifies the page background colour, in HTML only. The argument consists
2092 of three numbers from 0 to 255 separated by semicolons, for red, green and blue values respectively.
2093
2094 \begin{verbatim}
2095 \backgroundcolour{255;255;255}
2096 \backgroundcolour{0;0;255}
2097 \end{verbatim}
2098
2099 The first example sets the background to white, the second sets the background to blue.
2100
2101 Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
2102 setting, {\it backgroundColour}.
2103
2104 \subsection*{backgroundimage:1}\label{backgroundimage}
2105
2106 Specifies the page background image, in HTML only. The argument
2107 is a URL for the GIF file to be used as the background.
2108
2109 For example:
2110
2111 \begin{verbatim}
2112 \backgroundimage{tile.gif}
2113 \end{verbatim}
2114
2115 This sets the background to a tile file.
2116
2117 Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
2118 setting, {\it backgroundImage}.
2119
2120 \subsection*{backslashraw:0}\label{backslashraw}
2121
2122 Outputs a raw backslash into the output (not LaTeX). Useful when
2123 inserting RTF (for example) that cannot be dealt with by Tex2RTF.
2124 E.g.
2125
2126 \begin{verbatim}
2127 \backslashraw{'e3}
2128 \end{verbatim}
2129
2130 inserts the text \verb$\'e3$ into the RTF file.
2131
2132 \subsection*{bcol:2}\label{bcol}
2133
2134 Sets the background colour for a block of text (RTF only). Has no known effect
2135 in the RTF readers currently tried (Word for Window and Windows Help).
2136
2137 See also \commandrefn{definecolour}{definecolour}, \commandrefn{fcol}{fcol}.
2138
2139 %\subsection*{baselineskip}
2140 %\subsection*{boxit:1}\label{boxit}
2141
2142 \subsection*{brclear:0}\label{brclear}
2143
2144 Stops aligning content following a left or right-aligned image in HTML only.
2145
2146 See also \commandrefn{imagel}{imagel}, \commandrefn{imager}{imager}.
2147
2148 \subsection*{cextract:0}\label{cextract}
2149
2150 Prints a C++ extraction operator (\cextract).
2151
2152 \subsection*{chapterheading:1}\label{chapterheading}
2153
2154 Like \commandrefn{chapter}{chapter}, but does not increment the chapter
2155 number and does not print a chapter number in the printed documentation
2156 contents page, or in the chapter heading. Used to implement \helpref{glossaries}{glossarysection} and
2157 other sections that are not real chapters.
2158
2159 \subsection*{cinsert:0}\label{cinsert}
2160
2161 Prints a C++ insertion operator (\cinsert).
2162
2163 \subsection*{class:1}\label{class}
2164
2165 Outputs the argument, an index entry (\LaTeX\ only) and a keyword entry (WinHelp only).
2166 Used in class reference documentation.
2167
2168 %\subsection*{cleardoublepage}
2169 %\subsection*{clearpage}
2170 %\subsection*{cline}
2171 \subsection*{clipsfunc:3}\label{clipsfunc}
2172
2173 Formats a CLIPS function, given the return value, function name, and
2174 arguments.
2175
2176 %\subsection*{columnsep}
2177 \subsection*{copyright:0}\label{copyright}
2178
2179 Outputs the copyright symbol.
2180
2181 \subsection*{cparam:2}\label{cparam}
2182
2183 Formats a CLIPS type and argument. Used within the third argument of
2184 a \commandrefn{clipsfunc}{clipsfunc} command.
2185
2186 \subsection*{definecolour:4}\label{definecolour}
2187
2188 Defines a new colour that can be used in the document (RTF only). This
2189 command can also be spelt \verb$\definecolor$.
2190
2191 The first argument is the lower-case name of the colour, and the following
2192 three arguments specify the red, green and blue intensities, in the range 0 to 255.
2193
2194 The default colours are equivalent to the following definitions:
2195
2196 \begin{verbatim}
2197 \definecolour{black}{0}{0}{0}
2198 \definecolour{cyan}{0}{255}{255}
2199 \definecolour{green}{0}{255}{0}
2200 \definecolour{magenta}{255}{0}{255}
2201 \definecolour{red}{255}{0}{0}
2202 \definecolour{yellow}{255}{255}{0}
2203 \definecolour{white}{255}{255}{255}
2204 \end{verbatim}
2205
2206 To use colours in a document, use the \commandrefn{fcol}{fcol} and \commandrefn{bcol}{bcol} commands.
2207
2208 Note that a document that defines its own colours should be converted twice within
2209 the same Tex2RTF session.
2210
2211 \subsection*{fcol:2}\label{fcol}
2212
2213 Sets the foreground colour for a block of text (RTF and HTML).
2214
2215 For example:
2216
2217 \begin{verbatim}
2218 This sentence is brightened up by some \fcol{red}{red text}.
2219 \end{verbatim}
2220
2221 gives:
2222
2223 This sentence is brightened up by some \fcol{red}{red text}.
2224
2225 See also \commandrefn{definecolour}{definecolour}, \commandrefn{bcol}{bcol}.
2226
2227 \subsection*{followedlinkcolour:1}\label{followedlinkcolour}
2228
2229 Specifies the followed link colour for the whole page, HTML only. The argument consists
2230 of three numbers from 0 to 255 separated by semicolons, for red, green and blue values respectively.
2231
2232 For example:
2233
2234 \begin{verbatim}
2235 \followedlinkcolour{255;255;255}
2236 \followedlinkcolour{0;0;255}
2237 \end{verbatim}
2238
2239 The first example sets the followed link text to white, and the second sets the followed link text to blue.
2240
2241 See also \commandrefn{backgroundcolour}{backgroundcolour}, \commandrefn{textcolour}{textcolour},
2242 \rtfsp\commandrefn{linkcolour}{linkcolour}.
2243
2244 Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
2245 setting, {\it followedLinkColour}.
2246
2247 \subsection*{footnotepopup:2}\label{footnotepopup}
2248
2249 In linear RTF, a footnote is created following the first argument, as with
2250 \commandref{footnote}{footnote}.
2251
2252 In WinHelp RTF, a the first argument is highlighted and becomes
2253 a popup reference to the second argument. See also \commandref{footnote}{footnote}\rtfsp
2254 and \commandref{popref}{popref}.
2255
2256 This command is not supported for formats other than \LaTeX,
2257 linear RTF and WinHelp RTF.
2258
2259 %\subsection*{footskip}\label{footskip}
2260 %\subsection*{framebox:1}\label{framebox}
2261
2262 \subsection*{functionsection:1}\label{functionsection}
2263
2264 Defines a subsection, adding the C++ function name to the \LaTeX\ index or the
2265 WinHelp keyword list.
2266
2267 Should be followed by a \commandrefn{func}{func} command to specify function
2268 details.
2269
2270 \subsection*{func:3}\label{func}
2271
2272 Defines a C++ function, given the return type, function name, and parameter list.
2273
2274 Should occur after a \commandrefn{functionsection}{functionsection} command.
2275
2276 %\subsection*{glossary:}\label{glossary}
2277 \subsection*{gloss:1}\label{gloss}
2278
2279 Marks a glossary entry. In \LaTeX, this is a synonym for an \commandrefn{item}{item}
2280 with an optional argument, within a \commandrefn{description}{description} environment,
2281 and the argument is added to the index.
2282
2283 In Windows Help, this is identical to a \commandrefn{section*}{sectionX} in a report.
2284
2285 If labels are associated with the glossary entries, they can be referenced by
2286 \commandref{helpref}{helpref} or \commandref{popref}{popref} jumps. A glossary entry is
2287 currently the only type of destination that popref may refer to.
2288
2289 This is an example of making a glossary in a report:
2290
2291 \begin{verbatim}
2292 \begin{helpglossary}
2293
2294 \gloss{API}\label{api}
2295
2296 Application Programmer's Interface - a set of calls and
2297 classes defining how a library (in this case, wxWidgets)
2298 can be used.
2299
2300 \gloss{Canvas}\label{canvas}
2301
2302 A canvas in XView and wxWidgets is a subwindow...
2303
2304 \gloss{DDE}\label{dde}
2305
2306 Dynamic Data Exchange - Microsoft's interprocess
2307 communication protocol. wxWidgets provides an abstraction
2308 of DDE under both Windows and UNIX.
2309
2310 \end{helpglossary}
2311 \end{verbatim}
2312
2313 %\subsection*{headheight}\label{headheight}
2314 \subsection*{helpglossary:1}\label{helpglossary}
2315
2316 An environment for making a glossary (not standard \LaTeX). See \commandrefn{gloss}{gloss} for
2317 usage.
2318
2319 \subsection*{helpignore:1}\label{helpignore}
2320
2321 Ignores the argument in Tex2RTF generated files, but not \LaTeX.
2322
2323 \subsection*{helponly:1}\label{helponly}
2324
2325 Only outputs the argument in Tex2RTF generated files.
2326
2327 \subsection*{helpinput:1}\label{helpinput}
2328
2329 Only includes the given file in Tex2RTF generated files.
2330
2331 \subsection*{helpfontfamily:1}\label{helpfontfamily}
2332
2333 Specifies the font family for Tex2RTF generated files. The argument
2334 may be Swiss or Times.
2335
2336 \subsection*{helpfontsize:1}\label{helpfontsize}
2337
2338 Specifies the font size for Tex2RTF generated files.
2339
2340 \subsection*{helpref:2}\label{helpref}
2341
2342 Specifies a jump to a labelled chapter, section, subsection subsubsection
2343 or figure.
2344
2345 The first argument is text to be highlighted (mouseable in help systems)
2346 and the second is the reference label. In linear documents, the section number
2347 is given following the text, unless the \commandrefn{helprefn}{helprefn} command
2348 is used instead, where the section number is suppressed.
2349
2350 Note that when generating HTML, the label {\it contents} is automatically defined,
2351 and may be referenced using \verb$\helpref$.
2352
2353 \subsection*{helprefn:2}\label{helprefn}
2354
2355 Specifies a jump to a labelled chapter, section, subsection subsubsection
2356 or figure.
2357
2358 The first argument is text to be highlighted (mouseable in help systems)
2359 and the second is the reference label. See \commandrefn{helpref}{helpref} for
2360 the form where the section number is printed in linear documents.
2361
2362 %\subsection*{hfill}\label{hfill}
2363 \subsection*{htmlignore:1}\label{htmlignore}
2364
2365 Ignores the argument in HTML.
2366
2367 \subsection*{htmlonly:1}\label{htmlonly}
2368
2369 Only outputs the argument in HTML.
2370
2371 \subsection*{image:2}\label{image}
2372
2373 This is translated to a PSBOX macro package \verb$\psboxto$ command in \LaTeX,
2374 the first argument being a sizing command and the second a filename.
2375
2376 In HTML mode, the second argument is used to generate a PostScript file reference.
2377
2378 In RTF mode, the second argument is tried with first a BMP extension and
2379 then a WMF extension to find a suitable Windows bitmap file, placeable
2380 metafile, or segmented hypergraphics file (.SHG). If a suitable file is
2381 found, in Windows Help mode a {\tt bmc}\rtfsp command is inserted into
2382 the RTF file with a reference to the file. In linear RTF mode, the
2383 bitmap or metafile is converted into hex and inserted into the RTF
2384 document.
2385
2386 Note that only RGB-encoded Windows bitmaps, or placeable metafiles, are
2387 valid for input to Tex2RTF. You can convert a RLE (run length encoded)
2388 bitmap file into a (bigger) RGB file using a program such as Paintshop
2389 Pro. A placeable metafile has a special header with dimension
2390 information. One may be constructed by a wxWidgets program by calling
2391 the function wxMakeMetafilePlaceable. The Microsoft Windows SDK has a
2392 sample program that loads and steps through placeable and ordinary
2393 metafiles.
2394
2395 Another wrinkle is that programs differ in the methods they
2396 use to recognise pictures in RTF files. You may need to use the {\it bitmapMethod} setting,
2397 which can be ``hex'' (embed the hex data in the file with a \verb$\dibitmap$ keyword),
2398 ``includepicture'' (use the MS Word 6.0 INCLUDEPICTURE field) or ``import''
2399 (an earlier name for INCLUDEPICTURE).
2400
2401 Here is an example of using the \verb$\image$ command.
2402
2403 \begin{verbatim}
2404 \begin{figure}
2405 $$\image{5cm;0cm}{heart.ps}$$
2406
2407 \caption{My picture}\label{piccy}
2408 \end{figure}
2409 \end{verbatim}
2410
2411 The dollars centre the image in the horizontal plane. The syntax
2412 of the first argument to \verb$\image$ is taken from syntax used by the \verb$\psbox$\rtfsp
2413 package: it allows specification of the horizontal and vertical
2414 dimensions of the image. Scaling will take place for PostScript
2415 and metafile images. A value of zero indicates that the image should
2416 be scaled in proportion to the non-zero dimension. Zeros for both
2417 dimensions will leave the image unscaled in the case of metafiles,
2418 or scaled to fit the page in the case of PostScript.
2419
2420 See also \commandrefn{imagel}{imagel}, \commandrefn{imager}{imager} for aligned images in
2421 HTML.
2422
2423 \subsection*{imagel:2}\label{imagel}
2424
2425 Similar to \commandrefn{image}{image}, but left-aligns the image with respect to the following
2426 content. Use \commandrefn{brclear}{brclear} to stop aligning the content to the right of the image.
2427
2428 See also \commandrefn{imager}{imager}.
2429
2430 \subsection*{imagemap:3}\label{imagemap}
2431
2432 This is translated to an HTML image map reference, or (in LaTeX) a PostScript psbox
2433 command. This allows images in HTML to have hotspots, where the user clicks on a
2434 part of the image and the browser jumps to a particular file.
2435
2436 The first argument is the same as the first argument to the \commandref{image}{image}\rtfsp
2437 command (ignored in HTML). The second argument must be the name of the
2438 image map entry, and the second is the filename to be displayed inline.
2439
2440 \begin{verbatim}
2441 \imagemap{}{tree.gif}{myname}
2442 \end{verbatim}
2443
2444 translates to:
2445
2446 \begin{verbatim}
2447 <a href="/cgi-bin/imagemap/mymap">
2448 <img src="tree.gif" ismap></a><p>
2449 \end{verbatim}
2450
2451 The snag with this is that, apart from the inconvenience of having to
2452 register a map file with the server, the map file will also have
2453 references to particular HTML files. If they exist in the current
2454 document, these names are not known until the file is generated. In which case, the
2455 map entries should probably refer to symbolic links that can be easily
2456 changed later.
2457
2458 \subsection*{imager:2}\label{imager}
2459
2460 Similar to \commandrefn{image}{image}, but right-aligns the image with respect to the following
2461 content. Use \commandrefn{brclear}{brclear} to stop aligning the content to the left of the image.
2462
2463 See also \commandrefn{imagel}{imagel}.
2464
2465 %\subsection*{includeonly}\label{includeonly}
2466 \subsection*{indented:2}\label{indented}
2467
2468 Environment supplied by Tex2RTF to allow (possibly nested) indentation of
2469 \LaTeX\ and RTF text. The first argument is the amount to be indented.
2470
2471 For example:
2472
2473 \begin{verbatim}
2474 \begin{indented}{2cm}
2475 This text should be indented by a couple of centimetres.
2476 This can be useful to highlight paragraphs.
2477 \end{indented}
2478 \end{verbatim}
2479
2480 produces:
2481
2482 \begin{indented}{2cm}
2483 This text should be indented by a couple of centimetres. This can be
2484 useful to highlight paragraphs.
2485 \end{indented}
2486
2487 \subsection*{latexignore:1}\label{latexignore}
2488
2489 Ignores the argument in \LaTeX.
2490
2491 \subsection*{latexonly:1}\label{latexonly}
2492
2493 Only prints the argument in \LaTeX.
2494
2495 %\subsection*{lbox}\label{lbox}
2496
2497 \subsection*{lbraceraw:0}\label{lbraceraw}
2498
2499 Outputs a raw left brace into the output (not LaTeX). Useful when
2500 inserting RTF (for example) that cannot be dealt with by Tex2RTF.
2501
2502 \subsection*{linkcolour:1}\label{linkcolour}
2503
2504 Specifies the link colour for the whole page, HTML only. The argument consists
2505 of three numbers from 0 to 255 separated by semicolons, for red, green and blue values respectively.
2506
2507 For example:
2508
2509 \begin{verbatim}
2510 \linkcolour{255;255;255}
2511 \linkcolour{0;0;255}
2512 \end{verbatim}
2513
2514 The first example sets the link text to white, and the second sets the link text to blue.
2515
2516 See also \commandrefn{backgroundcolour}{backgroundcolour}, \commandrefn{textcolour}{textcolour},
2517 \rtfsp\commandrefn{followedlinkcolour}{followedlinkcolour}.
2518
2519 Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
2520 setting, {\it linkColour}.
2521
2522 \subsection*{membersection:1}\label{membersection}
2523
2524 Used when formatting C++ classes to print a subsection for the member name.
2525
2526 \subsection*{member:1}\label{member}
2527
2528 Used to format a C++ member variable name.
2529
2530 \subsection*{normalbox:1}\label{normalbox}
2531
2532 Draws a box around the given paragraph in \LaTeX\ and RTF. In HTML
2533 and XLP formats, horizontal rules are drawn before and after the text.
2534
2535 For example:
2536
2537 \begin{verbatim}
2538 \normalbox{This should be a boxed paragraph for highlighting
2539 important information, such as information for registering
2540 a shareware program.}
2541 \end{verbatim}
2542
2543 gives:
2544
2545 \normalbox{This should be a boxed paragraph for highlighting important
2546 information, such as information for registering a shareware program.}
2547
2548 See also \commandrefn{normalboxd}{normalboxd} for double-bordered text.
2549
2550 \subsection*{normalboxd:1}\label{normalboxd}
2551
2552 Draws a double border around the given paragraph in \LaTeX\ and RTF. In
2553 HTML and XLP formats, horizontal rules are drawn before and after the
2554 text.
2555
2556 For example:
2557
2558 \begin{verbatim}
2559 \normalboxd{This should be a boxed paragraph for
2560 highlighting important information, such as information
2561 for registering a shareware program.}
2562 \end{verbatim}
2563
2564 gives:
2565
2566 \normalboxd{This should be a boxed paragraph for highlighting important
2567 information,such as information for registering a shareware program.}
2568
2569 See also \commandrefn{normalbox}{normalbox} for single-bordered text.
2570
2571 \subsection*{param:1}\label{param}
2572
2573 Formats a C++ type and argument pair. Should be used within the third argument
2574 of a a \commandrefn{func}{func} command.
2575
2576 \subsection*{popref:2}\label{popref}
2577
2578 Similar to \commandrefn{helprefn}{helprefn}, except that in Windows Help,
2579 the destination text is popped up in a small window to be dismissed with
2580 a mouse click, instead of going to a separate section.
2581
2582 Currently this command can only refer to a labelled glossary entry; see
2583 \commandrefn{gloss}{gloss}.
2584
2585 \subsection*{psboxto:2}\label{psboxto}
2586
2587 Identical to \commandrefn{image}{image}.
2588
2589 %\subsection*{psbox}\label{psbox}
2590 \subsection*{rbraceraw:0}\label{rbraceraw}
2591
2592 Outputs a raw right brace into the output (not LaTeX). Useful when
2593 inserting RTF (for example) that cannot be dealt with by Tex2RTF.
2594
2595 \subsection*{registered:0}\label{registered}
2596
2597 Outputs the `registered' symbol in HTML, and (r) in other formats.
2598
2599 \subsection*{row:1}\label{row}
2600
2601 A Tex2RTF command signifying the row of a table within the \commandrefn{tabular}{tabular}\rtfsp
2602 environment. See also \commandrefn{ruledrow}{ruledrow}.
2603
2604 \subsection*{ruledrow:1}\label{ruledrow}
2605
2606 A Tex2RTF command signifying a ruled row of a table within the \commandrefn{tabular}{tabular}\rtfsp
2607 environment. See also \commandrefn{row}{row}.
2608
2609 \subsection*{rtfignore:1}\label{rtfignore}
2610
2611 Ignores the argument in linear RTF.
2612
2613 \subsection*{rtfonly:1}\label{rtfonly}
2614
2615 Only outputs the argument in linear RTF.
2616
2617 \subsection*{rtfsp:0}\label{rtfsp}
2618
2619 Outputs a space in RTF. Tex2RTF tries to insert a space where one is implied
2620 by a newline, but cannot cope where a line starts or ends with a command,
2621 in the middle of a paragraph. Use this command to insert a space explicitly.
2622
2623 \subsection*{sectionheading:1}\label{sectionheading}
2624
2625 Like \commandrefn{section}{section}, but does not increment the section
2626 number and does not print a section number in the printed documentation
2627 contents page, or in the section heading.
2628
2629 \subsection*{setfooter:6}\label{setfooter}
2630
2631 Tex2RTF has a non-standard way of setting headers and footers,
2632 but the default macro definitions in {\tt texhelp.sty} may be altered
2633 to your current method.
2634
2635 The arguments are as follows:
2636
2637 \begin{enumerate}
2638 \itemsep=0pt
2639 \item Left footer, even pages
2640 \item Centre footer, even pages
2641 \item Right footer, even pages
2642 \item Left footer, odd pages
2643 \item Centre footer, odd pages
2644 \item Right footer, odd pages
2645 \end{enumerate}
2646
2647 For many documents, the first three arguments will be left empty.
2648
2649 The behaviour for first pages of a chapter, section or document
2650 is to have a blank header, but print the footer.
2651
2652 For best results, define headers and footers for {\it each chapter or
2653 section}.
2654
2655 Note that this command works only for \LaTeX\ and linear RTF. See also\rtfsp
2656 \commandrefn{setheader}{setheader}.
2657
2658 \subsection*{setheader:6}\label{setheader}
2659
2660 Tex2RTF has a non-standard way of setting headers and footers,
2661 but the default macro definitions in {\tt texhelp.sty} may be altered
2662 to your current method.
2663
2664 The arguments are as follows:
2665
2666 \begin{enumerate}
2667 \itemsep=0pt
2668 \item Left header, even pages
2669 \item Centre header, even pages
2670 \item Right header, even pages
2671 \item Left header, odd pages
2672 \item Centre header, odd pages
2673 \item Right header, odd pages
2674 \end{enumerate}
2675
2676 For many documents, the first three arguments will be left empty.
2677 If \commandrefn{pagestyle}{pagestyle} is not plain or empty, the
2678 header will separated from the rest of the page by a rule.
2679
2680 The behaviour for first pages of a chapter, section or document
2681 is to have a blank header, but print the footer.
2682
2683 For best results, define headers and footers for {\it each chapter or
2684 section}.
2685
2686 Note that this command works only for \LaTeX\ and linear RTF. See also\rtfsp
2687 \commandrefn{setfooter}{setfooter}.
2688
2689 \subsection*{sethotspotcolour:1}\label{sethotspotcolour}
2690
2691 If the argument is yes, on or ok, subsequent WinHelp hotspots will be green.
2692 If any other value, the hotspots will be the normal text colour. Note that this
2693 doesn't apply to section hotspots, only to helpref hotspots.
2694
2695 \subsection*{sethotspotunderline:1}\label{sethotspotunderline}
2696
2697 If the argument is yes, on or ok, subsequent WinHelp hotspots will be
2698 underlined (the default). If any other value, the hotspots will not be
2699 underlined. Note that this doesn't apply to section hotspots, only to
2700 helpref hotspots.
2701
2702 \subsection*{settransparency:1}\label{settransparency}
2703
2704 WinHelp mode only (version 4 of WinHelp). If the argument is yes, on or ok, subsequent bitmaps
2705 will be inserted in transparent mode: areas of white will be made transparent.
2706 If the argument is any other value (such as no, ok or false), the bitmaps will not be transparent.
2707
2708 \subsection*{textcolour:1}\label{textcolour}
2709
2710 Specifies the text foreground colour for the whole page, HTML only. The argument consists
2711 of three numbers from 0 to 255 separated by semicolons, for red, green and blue values respectively.
2712
2713 For example:
2714
2715 \begin{verbatim}
2716 \textcolour{255;255;255}
2717 \textcolour{0;0;255}
2718 \end{verbatim}
2719
2720 The first example sets the text to white, and the second sets the text to blue.
2721
2722 See also \commandrefn{backgroundcolour}{backgroundcolour}, \commandrefn{linkcolour}{linkcolour},
2723 \rtfsp\commandrefn{followedlinkcolour}{followedlinkcolour}.
2724
2725 Instead of using a LaTeX command, you may find it more convenient to use the equivalent {\tt .ini} file
2726 setting, {\it textColour}.
2727
2728 \subsection*{toocomplex:1}\label{toocomplex}
2729
2730 An environment for dealing with complex \LaTeX\ commands that
2731 Tex2RTF cannot handle. In normal \LaTeX, the argument will be output
2732 as normal. In Tex2RTF output, the argument will be output as verbatim text,
2733 for the user to hand-translate into the desired output format.
2734
2735 See also \commandrefn{comment}{comment}.
2736
2737 \subsection*{twocolitem:2}\label{twocolitem}
2738
2739 Used to specify a row for a two column list, a Tex2RTF
2740 extension to optimize two-column lists for different
2741 file formats. See \commandrefn{twocollist}{twocollist},
2742 \rtfsp\commandrefn{twocolitemruled}{twocolitemruled}.
2743
2744 \subsection*{twocolitemruled:2}\label{twocolitemruled}
2745
2746 Used to specify a ruled row for a two column list, a Tex2RTF
2747 extension to optimize two-column lists for different
2748 file formats. See \commandrefn{twocollist}{twocollist},
2749 \rtfsp\commandrefn{twocolitem}{twocolitem}.
2750
2751 \subsection*{twocollist:1}\label{twocollist}
2752
2753 A Tex2RTF environment for specifying a table of two columns, often
2754 used in manuals and help files (for example, for listing commands and
2755 their meanings). The first column should be one line only, and
2756 the second can be an arbitrary number of paragraphs.
2757
2758 The reason that a normal tabular environment cannot be used is that
2759 WinHelp does not allow borders in table cells, so a different method
2760 must be employed if any of the rows are to be ruled. In \LaTeX, a table
2761 is used to implement this environment. In RTF, indentation is used instead.
2762
2763 Use this environment in conjunction with \commandrefn{twocolitem}{twocolitem} and\rtfsp
2764 \commandrefn{twocolitemruled}{twocolitemruled}. To set the widths of the first
2765 and second column, use \commandrefn{twocolwidtha}{twocolwidtha} and\rtfsp
2766 \commandrefn{twocolwidthb}{twocolwidthb}.
2767
2768 Example:
2769
2770 \begin{verbatim}
2771 \htmlignore{\begin{twocollist}}
2772 \twocolitemruled{{\bf Command}}{{\bf Description}}
2773 \twocolitem{File}{The file menu is used to select various
2774 file-related operations, such as saving and loading.}
2775 \twocolitem{Edit}{The Edit menu is used for
2776 selection, copying, pasting, etc.}
2777 \end{twocollist}
2778 \end{verbatim}
2779
2780 This produces:
2781
2782 \begin{twocollist}
2783 \twocolitemruled{{\bf Command}}{{\bf Description}}
2784 \twocolitem{File}{The file menu is used to select various file-related
2785 operations, such as saving and loading.}
2786 \twocolitem{Edit}{The Edit menu is used for selection, copying, pasting, etc.}
2787 \end{twocollist}
2788
2789 \subsection*{twocolwidtha:1}\label{twocolwidtha}
2790
2791 Sets the width of the first column in a two column list to the given
2792 dimension. See also \commandrefn{twocollist}{twocollist} and \commandrefn{twocolwidthb}{twocolwidthb}.
2793
2794 \subsection*{twocolwidthb:1}\label{twocolwidthb}
2795
2796 Sets the width of the second column in a two column list to the given
2797 dimension. See also \commandrefn{twocollist}{twocollist} and \commandrefn{twocolwidtha}{twocolwidtha}.
2798
2799 \subsection*{urlref:2}\label{urlref}
2800
2801 Specifies a jump to a URL (univeral resource location).
2802
2803 The first argument is text to be highlighted (mouseable in HTML browsers)
2804 and the second is the URL. In linear documents, the URL
2805 is given following the text.
2806
2807 Example:
2808
2809 \begin{verbatim}
2810 See also the \urlref{wxWidgets manual}
2811 {http://www.aiai.ed.ac.uk/~jacs.html}.
2812 \end{verbatim}
2813
2814 (the line is broken only to keep to this manual's page width).
2815
2816 \subsection*{winhelpignore:1}\label{winhelpignore}
2817
2818 Ignores the argument in WinHelp RTF.
2819
2820 \subsection*{winhelponly:1}\label{winhelponly}
2821
2822 Only outputs the argument in WinHelp RTF.
2823
2824 \subsection*{xlpignore:1}\label{xlpignore}
2825
2826 Ignores the argument in XLP mode (wxHelp files).
2827
2828 \subsection*{xlponly:1}\label{xlponly}
2829
2830 Only outputs the argument in XLP mode (wxHelp files).
2831
2832 \section{Accents}\label{accents}
2833
2834 The following \LaTeX\ accents work for RTF and HTML production:
2835
2836 \begin{itemize}%
2837 \itemsep=0pt
2838 \item \verb$\'{a}$ produces \'{a}. Valid for a, e, i, o, u, A, E, I, O, U
2839 \item \verb$\`{a}$ produces \`{a}. Valid for a, e, i, o, u, y, A, E, I, O, U, Y
2840 \item \verb$\^{a}$ produces \^{a}. Valid for a, e, i, o, u, A, E, I, O, U
2841 \item \verb$\~{a}$ produces \~{a}. Valid for a, n, o, A, N, O
2842 \item \verb$\"{a}$ produces \"{a}. Valid for a, e, i, o, u, y, A, E, I, O, U, Y
2843 \item \verb$\.{a}$ produces \.{a}. Valid for a, A
2844 \end{itemize}
2845
2846 \section{Commands by category}\index{commands}%
2847
2848 Below are categories of \LaTeX\ commands, to help you find the right
2849 command for a particular purpose.
2850
2851 \subsection{Font commands}
2852
2853 \begin{itemize}\itemsep=0pt
2854 \item \commandpageref{bf}{bf}
2855 \item \commandpageref{bffamily}{bffamily}
2856 \item \commandpageref{em}{em}
2857 \item \commandpageref{emph}{emph}
2858 \item \commandpageref{huge}{huge1}
2859 \item \commandpageref{Huge}{Huge2}
2860 \item \commandpageref{HUGE}{HUGE3}
2861 \item \commandpageref{it}{it}
2862 \item \commandpageref{itshape}{itshape}
2863 \item \commandpageref{large}{large1}
2864 \item \commandpageref{Large}{Large2}
2865 \item \commandpageref{LARGE}{LARGE3}
2866 \item \commandpageref{mdseries}{mdseries}
2867 \item \commandpageref{normalsize}{normalsize}
2868 \item \commandpageref{rm}{rm}
2869 \item \commandpageref{rmfamily}{rmfamily}
2870 \item \commandpageref{sc}{sc}
2871 \item \commandpageref{scshape}{scshape}
2872 \item \commandpageref{sf}{sf}
2873 \item \commandpageref{sffamily}{sffamily}
2874 \item \commandpageref{sl}{sl}
2875 \item \commandpageref{slshape}{slshape}
2876 \item \commandpageref{small}{small}
2877 \item \commandpageref{textbf}{textbf}
2878 \item \commandpageref{textit}{textit}
2879 \item \commandpageref{textrm}{textrm}
2880 \item \commandpageref{textsf}{textsf}
2881 \item \commandpageref{textsc}{textsc}
2882 \item \commandpageref{textsl}{textsl}
2883 \item \commandpageref{texttt}{texttt}
2884 \item \commandpageref{tiny}{tiny}
2885 \item \commandpageref{tt}{tt}
2886 \item \commandpageref{ttfamily}{ttfamily}
2887 \item \commandpageref{underline}{underline}
2888 \item \commandpageref{upshape}{upshape}
2889 \end{itemize}
2890
2891 \subsection{Paragraph formatting}
2892
2893 \begin{itemize}\itemsep=0pt
2894 \item \commandpageref{centerline}{centerline}
2895 \item \commandpageref{comment}{comment}
2896 \item \commandpageref{flushleft}{flushleft}
2897 \item \commandpageref{footnote}{footnote}
2898 \item \commandpageref{indented}{indented}
2899 \item \commandpageref{marginparwidth}{marginparwidth}
2900 \item \commandpageref{marginpar}{marginpar}
2901 \item \commandpageref{marginpareven}{marginpareven}
2902 \item \commandpageref{marginparodd}{marginparodd}
2903 \item \commandpageref{multicolumn}{multicolumn}
2904 \item \commandpageref{newpage}{newpage}
2905 \item \commandpageref{noindent}{noindent}
2906 \item \commandpageref{onecolumn}{onecolumn}
2907 \item \commandpageref{parindent}{parindent}
2908 \item \commandpageref{parskip}{parskip}
2909 \item \commandpageref{par}{par}
2910 \item \commandpageref{quote}{quote}
2911 \item \commandpageref{quotation}{quotation}
2912 \item \commandpageref{textwidth}{textwidth}
2913 \item \commandpageref{twocolumn}{twocolumn}
2914 \item \commandpageref{verbatim}{verbatim}
2915 \item \commandpageref{verb}{verb}
2916 \end{itemize}
2917
2918 \subsection{Special effects}
2919
2920 \begin{itemize}\itemsep=0pt
2921 \item \commandpageref{backgroundcolour}{backgroundcolour}
2922 \item \commandpageref{backgroundimage}{backgroundimage}
2923 \item \commandpageref{backslashraw}{backslashraw}
2924 \item \commandpageref{bcol}{bcol}
2925 \item \commandpageref{definecolour}{definecolour}
2926 \item \commandpageref{fcol}{fcol}
2927 \item \commandpageref{followedlinkcolour}{followedlinkcolour}
2928 \item \commandpageref{helpfontfamily}{helpfontfamily}
2929 \item \commandpageref{helpfontsize}{helpfontsize}
2930 \item \commandpageref{hrule}{hrule}
2931 \item \commandpageref{linkcolour}{linkcolour}
2932 \item \commandpageref{normalbox}{normalbox}
2933 \item \commandpageref{normalboxd}{normalboxd}
2934 \item \commandpageref{sethotspotcolour}{sethotspotcolour}
2935 \item \commandpageref{sethotspotunderline}{sethotspotunderline}
2936 \item \commandpageref{settransparency}{settransparency}
2937 \item \commandpageref{textcolour}{textcolour}
2938 \item \commandpageref{typeout}{typeout}
2939 \end{itemize}
2940
2941 \subsection{Lists}
2942
2943 \begin{itemize}\itemsep=0pt
2944 \item \commandpageref{description}{description}
2945 \item \commandpageref{enumerate}{enumerate}
2946 \item \commandpageref{itemize}{itemize}
2947 \item \commandpageref{item}{item}
2948 \item \commandpageref{itemsep}{itemsep}
2949 \item \commandpageref{twocolitem}{twocolitem}
2950 \item \commandpageref{twocolitemruled}{twocolitemruled}
2951 \item \commandpageref{twocollist}{twocollist}
2952 \item \commandpageref{twocolwidtha}{twocolwidtha}
2953 \item \commandpageref{twocolwidthb}{twocolwidthb}
2954 \end{itemize}
2955
2956 \subsection{Sectioning}
2957
2958 \begin{itemize}\itemsep=0pt
2959 \item \commandpageref{chapter}{chapter}
2960 \item \commandpageref{chapter*}{chaptersX}
2961 \item \commandpageref{chapterheading}{chapterheading}
2962 \item \commandpageref{insertatlevel}{insertatlevel}
2963 \item \commandpageref{paragraph}{paragraph}
2964 \item \commandpageref{paragraph*}{paragraphX}
2965 \item \commandpageref{section}{section}
2966 \item \commandpageref{section*}{sectionX}
2967 \item \commandpageref{sectionheading}{sectionheading}
2968 \item \commandpageref{subparagraph}{subparagraph}
2969 \item \commandpageref{subparagraph*}{subparagraphX}
2970 \item \commandpageref{subsection}{subsection}
2971 \item \commandpageref{subsection*}{subsectionX}
2972 \item \commandpageref{subsubsection}{subsubsection}
2973 \item \commandpageref{subsubsection*}{subsubsectionX}
2974 \end{itemize}
2975
2976 \subsection{Pictures}
2977
2978 \begin{itemize}\itemsep=0pt
2979 \item \commandpageref{brclear}{brclear}
2980 \item \commandpageref{image}{image}
2981 \item \commandpageref{imagel}{imagel}
2982 \item \commandpageref{imagemap}{imagemap}
2983 \item \commandpageref{imager}{imager}
2984 \item \commandpageref{psboxto}{psboxto}
2985 \end{itemize}
2986
2987 \subsection{References and jumps}
2988
2989 \begin{itemize}\itemsep=0pt
2990 \item \commandpageref{footnotepopup}{footnotepopup}
2991 \item \commandpageref{helpref}{helpref}
2992 \item \commandpageref{helprefn}{helprefn}
2993 \item \commandpageref{label}{label}
2994 \item \commandpageref{pageref}{pageref}
2995 \item \commandpageref{popref}{popref}
2996 \item \commandpageref{ref}{ref}
2997 \item \commandpageref{urlref}{urlref}
2998 \end{itemize}
2999
3000 \subsection{Tables and figures}
3001
3002 \begin{itemize}\itemsep=0pt
3003 \item \commandpageref{caption}{caption}
3004 \item \commandpageref{figure}{figure}
3005 \item \commandpageref{hline}{hline}
3006 \item \commandpageref{ruledrow}{ruledrow}
3007 \item \commandpageref{tabbing}{tabbing}
3008 \item \commandpageref{tabular}{tabular}
3009 \end{itemize}
3010
3011 \subsection{Table of contents}
3012
3013 \begin{itemize}\itemsep=0pt
3014 \item \commandpageref{addcontentsline}{addcontentsline}
3015 \item \commandpageref{author}{author}
3016 \item \commandpageref{date}{date}
3017 \item \commandpageref{maketitle}{maketitle}
3018 \item \commandpageref{tableofcontents}{tableofcontents}
3019 \item \commandpageref{title}{title}
3020 \end{itemize}
3021
3022 \subsection{Special sections}
3023
3024 \begin{itemize}\itemsep=0pt
3025 \item \commandpageref{bibitem}{bibitem}
3026 \item \commandpageref{bibliographystyle}{bibliographystyle}
3027 \item \commandpageref{bibliography}{bibliographycmd}
3028 \item \commandpageref{cite}{cite}
3029 \item \commandpageref{gloss}{gloss}
3030 \item \commandpageref{helpglossary}{helpglossary}
3031 \item \commandpageref{index}{index}
3032 \item \commandpageref{nocite}{nocite}
3033 \item \commandpageref{printindex}{printindex}
3034 \item \commandpageref{shortcite}{shortcite}
3035 \item \commandpageref{thebibliography}{thebibliography}
3036 \end{itemize}
3037
3038
3039 \subsection{Symbols}
3040
3041 \begin{itemize}\itemsep=0pt
3042 \item \commandpageref{backslash}{backslash}
3043 \item \commandpageref{cdots}{cdots}
3044 \item \commandpageref{cextract}{cextract}
3045 \item \commandpageref{cinsert}{cinsert}
3046 \item \commandpageref{copyright}{copyright}
3047 \item \commandpageref{LaTeX}{LaTeX}
3048 \item \commandpageref{lbraceraw}{lbraceraw}
3049 \item \commandpageref{ldots}{ldots}
3050 \item \commandpageref{rbraceraw}{rbraceraw}
3051 \item \commandpageref{registered}{registered}
3052 \item \commandpageref{rtfsp}{rtfsp}
3053 \item \commandpageref{ss}{ss}
3054 \item \commandpageref{TeX}{TeX}
3055 \item \commandpageref{today}{today}
3056 \end{itemize}
3057
3058 \subsection{Document organisation}
3059
3060 \begin{itemize}\itemsep=0pt
3061 \item \commandpageref{document}{document}
3062 \item \commandpageref{documentstyle}{documentstyle}
3063 \item \commandpageref{helpignore}{helpignore}
3064 \item \commandpageref{helponly}{helponly}
3065 \item \commandpageref{helpinput}{helpinput}
3066 \item \commandpageref{htmlignore}{htmlignore}
3067 \item \commandpageref{htmlonly}{htmlonly}
3068 \item \commandpageref{include}{include}
3069 \item \commandpageref{input}{input}
3070 \item \commandpageref{latexignore}{latexignore}
3071 \item \commandpageref{latexonly}{latexonly}
3072 \item \commandpageref{newcommand}{newcommand}
3073 \item \commandpageref{pagestyle}{pagestyle}
3074 \item \commandpageref{pagenumbering}{pagenumbering}
3075 \item \commandpageref{rtfignore}{rtfignore}
3076 \item \commandpageref{rtfonly}{rtfonly}
3077 \item \commandpageref{setfooter}{setfooter}
3078 \item \commandpageref{setheader}{setheader}
3079 \item \commandpageref{special}{special}
3080 \item \commandpageref{toocomplex}{toocomplex}
3081 \item \commandpageref{verbatiminput}{verbatiminput}
3082 \item \commandpageref{winhelpignore}{winhelpignore}
3083 \item \commandpageref{winhelponly}{winhelponly}
3084 \item \commandpageref{xlpignore}{xlpignore}
3085 \item \commandpageref{xlponly}{xlponly}
3086 \end{itemize}
3087
3088 \chapter{Bugs and troubleshooting}\label{errors}\index{bugs}\index{errors}\index{troubleshooting}%
3089 \setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
3090 \setfooter{\thepage}{}{}{}{}{\thepage}%
3091
3092 \section{Bugs}
3093
3094 \begin{description}
3095 \item[Command parsing.] If a command is used followed by inappropriate
3096 argument syntax, Tex2RTF can crash. This an occur when a command is
3097 used in an asterisk form that is only formed in the non-asterisk
3098 variety. The non-asterisk form is assumed, which makes the following
3099 asterisk trip up the parser.
3100 \item[Setlength.] Using the $\backslash$setlength command doesn't work,
3101 since its first argument looks like a command with the wrong number
3102 of arguments. Use an alternative form instead, e.g. \verb$\parindent 0pt$ instead
3103 of \verb$\setlength{parindent}{0pt}$.
3104 \item[Newcommand bug.] Environments in a command definition confuse
3105 Tex2RTF. Use the command form instead (e.g. $\backslash$flushleft\{...\} instead
3106 of $\backslash$begin\{flushleft\} ... $\backslash$end\{flushleft\}.
3107 \item[Bibliography.] There's no flexibility in the way references
3108 are output: I expect I'll get round to doing something better,
3109 but only if people tell me they need it!
3110 \item[Tables.] Tables can't handle all \LaTeX\ syntax, and require
3111 the Tex2RTF \verb$\row$ commands for decent formatting. Still, it's
3112 better than it was (RTF only).
3113 \item[Indexes and glossaries.] Not completely supported.
3114 \item[Crashes.] Crashes may be due to an input file exceeding the fixed-size
3115 buffer used for converting command arguments, especially for the \verb$\verbatim$\rtfsp
3116 command. Use the {\tt -bufsize} switch to increase the buffer size.
3117 \item[Verbatiminput.] Verbatiminput files which do not end with a blank line
3118 can trip up following commands.
3119 \end{description}
3120
3121 \section{Troubleshooting}
3122
3123 Below are some common problems and possible solutions.
3124
3125 \normalbox{Some of the syntax that is OK for true \LaTeX\ but which trips up
3126 Tex2RTF, may be detected by the TCHECK program included in the tools
3127 directory of the Tex2RTF distribution. Some \LaTeX\ errors may be picked up
3128 by the LACHECK program, also found in the tools directory.}
3129
3130 \subsection{Macro not found}\label{macronotfound}\index{macro not found error}%
3131
3132 This error may indicate that Tex2RTF has not implemented a standard
3133 \rtfsp\LaTeX\ command, or that a local macro package is being used that
3134 Tex2RTF does not know about. It can cause spurious secondary
3135 errors, such as not recognising the end document command.
3136
3137 You can get round this by defining a macro file (default name {\tt tex2rtf.ini})
3138 containing command definitions, such as:
3139
3140 \begin{verbatim}
3141 \crazy [2]{{\bf #2} is crazy but #1 is not}
3142 \something [0]{}
3143 \julian [0]{Julian Smart}
3144 \end{verbatim}
3145
3146 New commands may be defined in \LaTeX\ files, but custom macro files
3147 will have to be defined when local style files are being used. See\rtfsp
3148 \helpref{Initialisation file syntax}{inifile} for further details.
3149
3150 The `Macro not found' error can also be caused by a syntax error such as
3151 an unbalanced brace or passing the wrong number of arguments to a command,
3152 so look in the vicinity of the reported error for the real cause.
3153
3154 Here is one obscure situation that causes this error:
3155
3156 \begin{verbatim}
3157 \begin{center}
3158 {\large{\underline{A}}}
3159 \end{center}
3160 \end{verbatim}
3161
3162 The problem is too many curly brackets. This should be rewritten as:
3163
3164 \begin{verbatim}
3165 \begin{center}
3166 {\large \underline{A}}
3167 \end{center}
3168 \end{verbatim}
3169
3170 Often you get a `Macro not found' error for \verb$\end{document}$. This
3171 is a spurious side-effect of an earlier error, usually an incorrect number
3172 of arguments to a command. The location of the true error is then anywhere
3173 in the document. To home in on the error, try putting a verbatim environment
3174 \rtfsp\verb$\begin{comment}...\end{comment}$ around much of the document,
3175 and then move the \verb$\begin{comment}$ line down until the error
3176 manifests itself.
3177
3178 \subsection{Unresolved reference}\index{references, unresolved}%
3179
3180 References and citations are usually resolved on a second pass of
3181 Tex2RTF. If this doesn't work, then a missing label or bibliographical
3182 entry is to blame.
3183
3184 \subsection{Output crashes the RTF reader}
3185
3186 This could be due to confusing table syntax. Set {\it compatibility} to\rtfsp
3187 {\it TRUE} in {\tt .ini} file; also check for end of row characters backslash characters
3188 on their own on a line, and insert correct number of ampersands for the number of
3189 columns. E.g.
3190
3191 \begin{verbatim}
3192 hello & world\\
3193 \\
3194 \end{verbatim}
3195
3196 becomes
3197
3198 \begin{verbatim}
3199 hello & world\\
3200 &\\
3201 \end{verbatim}
3202
3203 \subsection{Erratic list indentation}
3204
3205 Try increasing the value of the variable {\it listItemIndent} (default 40
3206 points) to give more space between label and following text. A global
3207 replacement of \verb$\item [$ with \verb$\item[$ may also be helpful to remove
3208 unnecessary space before the item label.
3209
3210 \subsection{Missing figure or section reference}
3211
3212 Ensure all labels {\it directly} follow captions or sections (no intervening
3213 white space).
3214
3215 \subsection{Linear RTF looks odd}
3216
3217 For viewing by programs other than MS Word, you should set the variable {\it useWord} to {\it false}. This
3218 will turn off some of the special RTF keywords recognised by Word (and possibly other advanced RTF readers).
3219
3220 \subsection{Paragraphs preceding lists are formatted weirdly.}
3221
3222 If a list has spurious spacing in it, e.g. before a \verb$\item$ command, the preceding
3223 paragraph can take on some of the list's indentation. This may be a WinHelp bug, or an aspect
3224 of RTF I don't fully understand. The solution is to remove unnecessary space.
3225
3226 \subsection{Unresolved references in Word for Windows}\index{Microsoft Word}%
3227
3228 If question marks appear instead of numbers for figures and tables,
3229 select all (e.g. CTRL-A), then press F9 {\it twice} to reformat the
3230 document twice. For the second format, respond with {\it Update Entire
3231 Table} to any prompts.
3232
3233 \subsection{The Windows 95 help file contents hierarchy looks wrong}\index{WinHelp files}%
3234
3235 WinHelp version 4 (or the WIN32 Help Compiler) does not allow a
3236 book in the contents list to be followed by a page at the same level.
3237 A book must be followed by a book, for some strange reason, otherwise
3238 the page will be tacked on to the pages of the book above it, i.e. placed
3239 at the wrong level.
3240
3241 To get around this, Tex2RTF inserts a book in some places, if there
3242 was a book preceding it on the same level. This results in more
3243 navigation than necessary, but is better than a wrong contents page.
3244
3245 \newpage
3246
3247 % Puts books in the bibliography without needing to cite them in the
3248 % text
3249 \nocite{smart93a}%
3250 \nocite{kopka}%
3251 \nocite{pfeiffer}%
3252
3253 \bibliography{refs}
3254 \addcontentsline{toc}{chapter}{Bibliography}
3255 \setheader{{\it REFERENCES}}{}{}{}{}{{\it REFERENCES}}%
3256 \setfooter{\thepage}{}{}{}{}{\thepage}%
3257
3258 \begin{helpglossary}
3259 \setheader{{\it GLOSSARY}}{}{}{}{}{{\it GLOSSARY}}%
3260 \setfooter{\thepage}{}{}{}{}{\thepage}%
3261
3262 \gloss{GUI}
3263
3264 Graphical User Interface, such as Windows 3 or X.
3265
3266 \gloss{HTML}\label{html}
3267
3268 Hypertext Markup Language; an SGML document type, used for providing
3269 hypertext information on the World Wide Web, a distributed hypertext
3270 system on the Internet.
3271
3272 \gloss{LaTeX}\label{latexgloss}
3273
3274 A typesetting language implemented as a set of \TeX\ macros. It is
3275 distinguished for allowing specification of the document structure,
3276 while taking care of most layout concerns. It represents the opposite
3277 end of the spectrum from WYSIWYG word processors.
3278
3279 \gloss{RTF}\label{rtf}
3280
3281 Rich Text Format: an interchange format for word processor files,
3282 used for importing and exporting formatted documents, and as the
3283 input to the Windows Help compiler.
3284
3285 \gloss{wxHelp}\label{wxhelp}
3286
3287 wxHelp is the hypertext help facility used to provide on-line
3288 documentation for UNIX-based wxWidgets applications. Under Windows 3.1,
3289 Windows Help is used instead.
3290
3291 \gloss{wxWidgets}\label{wxwidgets}
3292
3293 wxWidgets is a free C++ toolkit for writing applications that are
3294 portable across several platforms. Currently these are Motif, Open Look,
3295 Windows 3.1 and Windows NT. Tex2RTF is written using wxWidgets.
3296
3297 \end{helpglossary}
3298
3299 \addcontentsline{toc}{chapter}{Index}
3300 \setheader{{\it INDEX}}{}{}{}{}{{\it INDEX}}%
3301 \setfooter{\thepage}{}{}{}{}{\thepage}%
3302 \printindex%
3303
3304 \end{document}