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