A Guide To Using rtftohtml and rtftoweb
This guide describes rtftohtml version 2.7.5, written by Chris Hector (cjh@cray.com) and rtftoweb version 1.6, written by Christian Bolik (zzhibol@rrzn-user.uni-hannover.de), that's me. My email address will probably change during October `95, but I hope these pages may remain in place.
Read about the new features and bug fixes of rtftoweb 1.6, dated 31.08.95, in the ChangeLog.
Some parts of this guide have been copied from Chris' rtftohtml User's Guide. The main purpose of this document is to have all information regarding the conversion from RTF to HTML via rtftohtml/rtftoweb in one place. It also is an example of what you can expect from rtftohtml/rtftoweb, since it has been converted from a Microsoft Word 6.0 document (exported as RTF) to HTML by using the extended rtftohtml.
Christian Bolik (zzhibol@rrzn-user.uni-hannover.de), 04.09.95
rtftohtml is a tool to turn your, say, Word documents into documents which may be read from within the World Wide Web. The format of these documents is called HyperText Markup Language (HTML). rtftohtml is able to automatically convert documents stored in RTF (Rich Text Format) to HTML. Most word processors in use on UNIX, Macintosh, PC or NeXT systems can export their documents in RTF format (hint: have a look at the "Save as..." dialog box of your favorite word processor).
The author of rtftohtml is Chris Hector. Have a look at his Web pages at Cray.
In processing text, rtftohtml chooses HTML markup based on three characteristics. These are
The filter has built-in rules for dealing with destinations. For paragraph and text styles, the rules for translation are contained in a file called html-trans. By modifying this file, you can train rtftohtml to perform the correct translations for your documents. The most common change that you will need to make is to add your own paragraph styles to html-trans.
rtftohtml should produce reasonable HTML output for most documents. Here is what you can expect:
rtftoweb is an extension of Chris Hector's very excellent rtftohtml (see section What is rtftohtml), which converts RTF-Documents to HTML, which in turn is used within the World Wide Web Project. rtftohtml converts a linear RTF-Document to an also linear HTML-Document, with little support for hypertext and without any structuring (well, since version 2.7 this isn't quite true anymore, but that table of contents doesn't turn your documents into hypertext).
This is where rtftoweb comes in.
rtftoweb converts a linear RTF-Document (that may contain cross references, index entries and footnotes) into a fully hypertexted set of HTML-Documents.
This document, that you are reading right now, is an example of what you can expect from using an rtftohtml which has been extended by rtftoweb, since it was created from an RTF-source by rtftohtml 2.7.5 with applied rtftoweb 1.6 patches, with the command
rtftohtml -h1 -c -x guide.rtf
The rtftoweb-patch adds the following features to rtftohtml:
For information about where to get and how to install rtftoweb, see section Installing rtftohtml and rtftoweb.
When I released rtftoweb 1.5, I thought it would be the last version of rtftoweb since I agreed with Chris Hector, the author of the original rtftohtml, that rtftoweb should be integrated into rtftohtml. That was at the end of 1994, but no new version of rtftohtml was released since then.
Chris told me that he has currently (and during the last monts) too many other things to do, and that he will not be able to continue the development of rtftohtml within the next few months. Because of this, and because I keep getting bug reports and suggestions from rtftoweb users I decided to release another (intermediate) version of rtftoweb.
Among the new features are:
This version also fixes some bugs of earlier versions, with the more important being:
For a detailed description of all changes have a look at the file CHANGES.
rtftohtml is available for UNIX, Macintosh and PC systems. Binaries can be copied directly from Chris' ftp directory at Cray, but note that these binaries were not extended by rtftoweb.
rtftoweb is currently only available for UNIX, but you are more then welcome to try and port it to Macs or PCs. This should not be too hard, since rtftoweb does not use any UNIX-specific features, maybe apart from filenames longer then ridiculous 11 characters (concerning a port to PCs).
For directions on getting and installing rtftohtml and rtftoweb on UNIX systems, read the next section: Installing rtftohtml and rtftoweb.
This section describes the installation of rtftohtml and rtftoweb under UNIX. If you are running a different system, have a look at section Supported platforms.
Installing rtftohtml and extending it with rtftoweb is really simple. Just follow these steps:
That's it!
rtftohtml is invoked by a command like this:
rtftohtml [options] file
file is the name of the RTF-file to convert. By default the HTML-output will be written to a file with the same basename, but with the .rtf-extension replaced with .html.
The most common options are (see below for more detailed descriptions of these):
These should suffice in most cases. When invoking rtftohtml without any arguments, a list of all available options is printed. Following is a complete and detailed list of all available command line options, sorted alphabetically:
(Whenever speaking of rtftohtml in the following I mean rtftohtml extended by rtftoweb.)
To convert a document from RTF (Rich Text Format) to HTML, rtftohtml requires the contents of the RTF-file to be formatted with a certain set of paragraph styles. For example, headings at level 1 must be formatted with the paragraph style "heading 1" (which is the built-in default for headings anyway; german heading styles may be called "Überschrift xy", but they appear in the RTF file as "heading xy", too), lists must be formatted with a paragraph style such as "numered list" etc. The reason for this is that rtftohtml needs to know which paragraph styles it should map to which HTML tags. This mapping between styles and tags can be customized be editing the file html-trans in rtftohtml's library directory (see section html-trans for more), to create a mapping from your own individual paragraph styles to HTML-tags. Although this is not as complicated as it might seem, I personally prefer to adjust my Word-documents to use only (or at least mostly) the paragraph styles recognized by rtftohtml by default. In this chapter I will stick to this strategy. See section "Adding paragraph styles" for a few words on how to customize rtftohtml to correctly interpret your own paragraph style.
To make the creation and preparation of Word documents that are to be converted to HTML as easy as possible, I have included a style file for Microsoft Word 6.0, called rtftoweb.dot into the rtftoweb-tar-file. Section "A .dot file for WinWord" describes the usage of this file in more detail.
Another way to specify the document title is via the -T command line option. For example:
rtftohtml -T "My work of art" art.rtf
Note that this title will also be automatically inserted by rtftohtml 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) and use it as the document title. 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.
rtftohtml automatically recognizes and converts bold, italic and underlined text. If a certain range of text is written using a monospaced font such as Courier, it also automatically creates monospaced HTML-output for that range. What fonts are considered to be monospaced can be configured in the file html-trans in section .TMatch ("monospace fonts -> tt"). By default the fonts "Courier", "Courier New" and "Palatino" are expected to be monospaced.
If you get warning messages such as "no output translation for ..." when running rtftohtml you can either replace that character with a less exotic one in your RTF-file or add a translation to the end of rtftohtml's library file html-map, such as "character translation".
The newline character (created by Shift-Return) will be
automatically
converted to the corresponding
HTML-tag,
as will the unbreakable space (created by Control-Shift-Space).
Headings must be formatted with a paragraph style like "heading 1", "heading 2" etc. (resp. "Überschrift 1" etc.) to be automatically recognized by rtftohtml. rtftohtml uses these styles to determine when it should split the HTML-file. The heading level at which splitting should take place can be configured by the command line switch -hlevel (see section Command line options). If a heading contains no text (i.e. it is empty) it will be ignored by rtftohtml.
If the -h switch was present when rtftohtml was invoked, a navigation panel will be inserted at the top and at the bottom of every generated HTML file. This navigation panel will contain the following elements:
rtftohtml will try to use the language of the RTF-file for labelling the navigation panel. Currently there is support for english, spanish, french and german. However, if you would like a more fancy-looking panel, with buttons etc., you can tell rtftohtml (by writing a simple configuration file) what HTML-code it should use for the individual panel elements. The creation of such configuration files is described in detail in section Navigation panels.
rtftohtml knows about the following lists (in braces is the name of the respective paragraph style it expects such lists to be formatted with):
Nested lists can be created from an RTF document by using a different style for each level of indentation. The styles "bullet list 1" "numbered list 2" ... represent different levels of nesting, with "bullet list 1" being at nesting level 1. The only rule for use is that no levels of nesting are skipped. For example, a "numbered list 3" paragraph must not appear immediately after a "Normal" paragraph. It must follow a paragraph with a nesting level of 2 or higher.
An example sequence of paragraph styles to produce a nested list might look like this:
numbered list bullet list 1 bullet list 2 glossary 2 bullet list 1 numbered list 2
rtftohtml is able automatically convert tables to HTML by generating a range of preformatted text to keep the cells in their place. For this reason only plain text is allowed in tables. Bold and italic text in tables should be possible in the next release of the rtftoweb patches. Tables produced/converted by rtftohtml look something like this:
Column 1, Row 1 Column 2, Row 1 Column 3, Row 1 Column 1, Row 2 Column 2, Row 2 Column 3, Row 2 Column 1, Row 3 Column 2, Row 3 Column 3, Row 3
If sometimes I have really got a lot of time on my hands I am planning to add support for tables as realized by the upcoming HTML 3.0 specification. Of course this would require you to use a HTML 3.0 capable browser such as Arena or Netscape.
In addition, the filter produces a link to the file containing the graphic. Now, since the above graphic formats are not very portable, the filter assumes that you will convert these files to something more useful, like GIF. So the format of the link is:
<a href="basenameN.ext">Click here for a Picture</a>
where
Since most Web browser only support images in GIF-format, you will have to convert the generated PICT- and WMF-files to GIF. For PICT there is picttoppm/ppmtogif, but for WMF? I don't know of any WMF translators for Unix; for DOS there is wmf2bmp, whose output could then be converted to GIF via the pbmplus-tools. From what I understand, WMF is not a pixel- but a vector-graphic format, so maybe it would be easier to translate WMF to Postscript and then let Ghostscript do the job of converting to GIF. Any volunteers for writing a wmftops utility?
You can also change the link to an IMG form. If you specify the -I command line option, all links to graphics will be of the form:
<IMG src="basenameN.ext">
There is one other special case. If a graphic is encountered when the filter is in the process of generating a link, the IMG form of the link is used even without the -I command line option.
Anchors for internal cross references (such as "mark1", corresponding to the example above) must be formatted either with the attributes "hidden/outline" or "hidden/superscript". For example this link will bring you to the list of new features in rtftoweb 1.6.
If you just want to create a reference to a certain heading resp. section, it is sufficient to simply format the reference with the color red (when using rtftoweb.dot: mark the reference and press Control-Shift-r). The text of the reference must match the beginning n characters of the heading, so the references "Supplying" and "Supplying a title" point to the same section.
If an email address such as bolik@irb.uni-hannover.de is colored red, rtftohtml will automatically produce a cross reference of type "mailto". Not all Web browser support this type of references (Netscape does).
The same work for all other kinds of URLs, so if the URL ftp://ftp.rrzn.uni-hannover.de/pub/ is colored red, rtftohtml will automatically produce a reference pointing to that URL.
If you insert index entries into your RTF-document and give rtftohtml the -x-option, rtftohtml will generate a hypertext'ish index for the generated HTML-documents. Note that when using NCSA-Mosaic as your Web browser you should also tell rtftohtml to insert some text into the generated anchors by using the command line switch -X text (see section Command line options).
If you wish to modify the formatting that discards text, you need to change the entry in html-trans that specifies "_Discard".
When the rtftohtml filter produces HTML markup, it keeps track of the nesting level of tags to ensure that you don't get something like <b><cite>hello</b></cite> which would be incorrect markup. If you imbed HTML markup in your document, the filter will NOT be aware of it. You must ensure that your markup appears correctly nested.
If you wish to modify the formatting for imbedded HTML, you need to change the entry in html-trans that specifies "_Literal".
rtftoweb.dot adds all the paragraph styles which are understood by rtftohtml (without modifying html-trans) to your document. Additionally some keyboard shortcuts are now defined (or possibly redefined...):
To add a new paragraph style, simply go to the .PMatch table contained in the file html-trans and add an entry to the end. Put the name of the paragraph style (quoted), the nesting level (usually zero) and the name of the .PTag entry that should be used.
The file html-trans is needed by rtftohtml to map character and paragraph styles contained in the RTF-file to corresponding HTML-tags. It must be readable either from rtftohtml's library directory (as set in the file makefile.rtftoweb) or from the directory contained in the environment variable RTFLIBDIR.
In html-trans there are four tables. They are labelled .PTag, .TTag, .TMatch and .PMatch. These tables begin with the name (in column one) and continue until the next table starts. All blank lines and lines beginning with a '#' are discarded. '#' lines are typically used for comments. The tables themselves are composed of records containing a fixed number of fields which are separated by commas. The fields are either strings (which should be quoted) integers or bitmasks.
.PTag
#"name","starttag","endtag","col2mark","tabmark","parmark",allowtext,cannest,DeleteCol1,fold,TocStyl
Sample .PTag Entries
"h1","<h1>\n","</h1>\n","\t","\t","<br>\n",0,0,0,1This is a level 1 heading. The "\n" in the start and end-tag fields forcesa newline in the HTML markup. Since newlines are ignored in HTML (except in <pre>) it's only effect is to make the HTML output more readable. There is no difference between the first tab and any other. They both translate to a tab mark. Paragraph marks generate "<br>" followed by a newline (just for looks). Text markup (like <b>) is not allowed within <h1> text, because we leave that up to the HTML client. No nesting is allowed - (see the discussion on nested styles). No text is deleted. Every paragraph using this markup will also generate a level-1 table of contents entry.
"Normal","","\n","\t","\t","<p>\n",1,0,0,0This is the default for normal text. Regular text in HTML has no required start and end-tags. The "\n" in the end-tag field forces a newline in the HTML markup. Since newlines are ignored in HTML (except in <pre>) it's only effect is to make the HTML output more readable. There is no difference between the first tab and any other. They both translate to a tab mark. Paragraph marks generate "<p>" followed by a newline (just for looks). Text markup (like <b>) is allowed within Normal text. No nesting is allowed - (see the discussion on nested styles). No text is deleted.
"ul","<ul>\n<li>","</ul>","\t","\t","\n<li>",1,1,0,0This is the entry for unordered lists. This generates a "<ul>\n<li>" at the start of the list and "</ul>/n" at the end. There is no difference between the first tab and any other. They both translate to a tab mark. Paragraph marks generate "<li>" preceded by a newline (just for looks). Text markup (like <b>) is allowed, and this entry may be nested - and it allows others to be nested within it. This allows nested lists. No text is deleted.
"ul-d","<ul>\n<li>","</ul>","\t","\t","\n<li>",1,1,1,0This entry is identical to the previous except that the DeleteCol1 field is set to 1. This is used to remove bullets (which really appear in the RTF) because we don't want to see them in the HTML.
.TTag
"name","starttag","endtag"
.TMatch
"Font",FontSize,Match,Mask,"TextStyleName"
The order of bits in the Match and Mask bit-maps are: # v^bDWUHACSOTIB - Bold # v^bDWUHACSOTI - Italic # v^bDWUHACSOT - StrikeThrough # v^bDWUHACSO - Outline # v^bDWUHACS - Shadow # v^bDWUHAC - SmallCaps # v^bDWUHA - AllCaps # v^bDWUH - Hidden # v^bDWU - Underline # v^bDW - Word Underline # v^bD - Dotted Underline # v^b - Double Underline # v^ - SuperScript # v - SubScript
Sample .TMatch Entries
# double-underline/not hidden -> hot text # double-underline/hidden -> href # v^bDWUHACSOTIB,v^bDWUHACSOTIB "",0,00100000000000,00100010000000,"_Hot" "",0,00100010000000,00100010000000,"_HRef"The first entry will match any text formatted with double underline EXCEPT if it is hidden text. This is accomplished by using those two bits to compare (the MASK field) and having a 1 in the double underline bit and a zero for the hidden text bit. The second entry will match any text formatted with BOTH double underline and hidden text. Any text that matches the first will be treated as the hot text of a link. Any text that matches the second will be taken as the href itself. (The filter requires that the HRef text immediately precede the Hot text.)
# Regular matches - You can have multiple of these active # monospace fonts -> tt "Courier",0,00000000000000,00000000000000,"tt"This will match any text that uses the Courier font and mark it using the HTML text markup appearing in the .TTag table with the entry name "tt".
# bold -> bold # v^bDWUIACSOTIB,v^bDWUIACSOTIB "",0,00000000000001,00000000000001,"b"This will match any text that has bold attributes and will mark it using the HTML text markup appearing in the .TTag table with the entry name "b". Note that bold text using the Courier font would match both this entry and the previous. This will yeild markup of the form <b><tt>hi</tt><b>. Note that "b" is the name of an entry in the .TTag table, not the HTML markup that is used!
.PMatch
"Paragraph Style",nesting_level,"PTagName"
Sample .PMatch Entries
"heading 1",0,"h1"This is a level 1 heading. Any paragraphs with this paragraph style will be mapped to the entry in the .PTag table named "h1".
"numbered list",0,"ol-d"This is used for numbered lists. Any paragraphs with this paragraph style will be mapped to the entry in the .PTag table named "ol-d".
"numbered list 2",2,"ol-d"This is an entry for a nested paragraph style. The nesting level of two is used to indicate that this paragraph should appear in the HTML nested within two levels of paragraph markups. The paragraph marked with this style may only appear after a paragraph style that has a nesting level of 1 or greater.
If you want the navigation panels produced by rtftohtml (see section Headings) to look more spiffy, e.g. with images as panel buttons, or if you want the generated HTML documents to use images as their background or another text color, this section is for you.
By using the -N Command line option when invoking rtftohtml, it is possible to tell rtftohtml exactly how you want the created navigation panels to look like. The same configuration file can be used to add a few funny Netscapisms to the generated documents. If no -N-option was given, but rtftohtml finds a file named nav-panel in its library directory or the directory contained in the environment variable RTFLIBDIR it will use this file as the layout customization file. This way you can avoid having to add the -N command line options whenever you use rtftohtml.
An example for such a customization file is the file nav-panel, which has also been used when this guide was converted to HTML. By looking at this file you should easily see how the layout of your documents can be adjusted tou your taste.
Each line of such a customization file contains the definition of a layout element, as long as the first character is not the hash-character (#), which introduces comments. Everything that follows the first colon (:) in each line will be literally inserted into the HTML-files when needed.
The following elements may be configured:
I currently do not know what Chris Hector's plans concerning rtftohtml are (he hasn't answered yet), but I plan to do some of the following as soon as time allows:
If you can help me with any of the items in this lists, please contact me (zzhibol@rrzn-user.uni-hannover.de). And of course, if you happen to stumble over anything that might look like a bug or you have any ideas for future releases, contact me, too!