3. Usage of rtftoweb

• 3.1. Command line options
• 3.2. The HTML-Title of the output files
• 3.3. The language of the output file
• 3.4. Cross references to headings
• 3.5. Index entries

Please also read the documentation that comes with rtftohtml!
Note: When talking of rtftoweb in the following, I mean rtftohtml extended with rtftoweb.

3.1. Command line options

By applying the rtftoweb patches to rtftohtml, you get quite a lot of new command line options (try, e.g., "rtftohtml -?" or simply "rtftohtml").

The new options have the following meaning:

-h[n]

Enable the hypertext-capabilities of rtftoweb. This option is also required for the -c and -x options.
The optional n-parameter specifies the heading level at which the splitting
should take place. For example, -h1 only splits the HTML-File when a level-1-heading is encountered. All lower level headings will be internally referenced from the top of the respective HTML-File. If the parameter is omitted (i.e. -h), splitting will take place whenever any headline is encountered.

-c

Generate a table of contents
on a separate page (the title page itself normally only contains the level-1-headings).

-x

Generate an index
. This works by gathering all the index entries of the RTF-File and inserting an (almost) invisible anchor at that place. (Unfortunately this anchor cannot be completely invisible due to NCSA Mosaic's requirement to have non-blank text between anchor tags.)

-t

Place external references to headlines near the top of the page. (Default is that they occur at the and of the page.)

-T title

Use "title" as the document title
. This overrides any title supplied within the RTF-file.
(Note: Stock rtftohtml uses this switch to prevent the generation of a table of contents. Since this conflicts with rtftoweb's ToC-handling anyway, I have redefined this command line switch.)

The remaining options are inherited directly from rtftohtml; I have copied their descriptions for your convenience from the rtftohtml User's Guide:

-i

Indicates that imbedded graphics
should be linked into the main document using an IMG tag. The default is to use an HREF style link.

-o filename

Indicates that the output file name
should be "filename". If any other files are created (such as for graphics), the basename of the other files will be "filename" without ".rtf" if it is present in the name.

-P extension

Use "extension" as the extension for any links to graphics files. The default for this is "gif".

-G

Indicates that no graphics files should be written. The hypertext links to the graphics files will still be generated. This is a performance feature for when you are re-translating a document and the graphics have not changed.

file

The file name to be processed. The output is written to "file" with ".html" as an extension[1]. (If ".rtf" appears as an extension on the original input file, it is stripped before appending the ".html")

3.2. The HTML-Title of the output files

To determine the HTML-Title
for the created HTML-Files (the text between the <title> and </title> tags), rtftoweb looks for the \title-token inside the \info-group of the RTF-File. Thus you should give your RTF-Documents a short, descriptive title in the respective dialog box of your word processor (should be called something like "File information").

Note that this title will also be automatically inserted by rtftoweb into the first created HTML-File as a level-1-heading. That's why you should usually delete the very first heading from your RTF-Document (or at least assign a different paragraph format to that line). The reason for this is to prevent rtftoweb from interpreting the headline of your RTF-Document as a level 1 heading, where it should split.

Note: Since version 1.3 of rtftoweb it is possible to provide the title via a command line option (-T), see 3.1. for details.

3.3. The language of the output file

rtftoweb looks for the \lang-token in the RTF-File to determine the language for the navigation panels etc. Currently English, French, German and Italian are supported. You can extend rtftoweb's knowledge by adding other languages to hier.h (and editing hier.c: in function "static void setNavTexts (lang)"). The default language is a compile-time option that can be set in makefile.rtftoweb.

3.4. Cross references to headings

To mark a cross reference
as such, format its text with the color red. The text of the cross references must be the beginning n characters of the references heading. For example: "see Section 3.2" will match the heading "3.2 This is a heading" if 3.2 is marked as a crossref.

3.5. Index entries

Try not to place index entries immediately after a paragraph break, but immediately after the word or passage that you would like to reference. The reason for this is that Mosaic, when going to an anchor inside a page, places the line that contains the anchor on the very top of the page. So, if the anchor is preceded by a paragraph break, the word that you were adressing from the Index is just above the visible area, which is certainly not what you wanted.