rtfdtohtml - convert RTF and RTFD files to HTML pages
- rtfdtohtml
-
[-G] [-gif|-png] [-jpeg] [-head] [-href] [-blue] [-html2] [-index] [-no-li] [-tables] [-nav file] [-output dir] [-scale factor] [-version] file ...
The rtfdtohtml program may be used to translate existing documents from the Rich
Text
Format
to HTML. The program knows how to handle most of NeXT's extensions to the
RTF format, e.g. links and inline graphics. (See section Conversion Details for more information.)
All generated files are placed by default in the same directory as the
corresponding source file. A different directory may be specified with the -output
command line option as described in the next section. The output filename
will be created by appending the suffix .html to the source filename, except for RTFD files like file.rtfd (which really is a directory containing a TXT.rtf file). In this case the output will be written to the file file.rtfd/index.html.
File arguments given on the command line may be either RTF or RTFD files,
or C / C++ / Objective-C source files that contain RTF information. All
file arguments that are not RTF or RTFD files will be ignored.
Rtfdtohtml currently supports the following options:
- -G or --no-graphics
-
This option disables all image conversions. It is mainly useful if only the
text of a document has changed and you want to avoid recreating all the
images. This saves a lot of time on most files.
- -gif or --gif
-
All EPS images will be converted to interlaced GIF format. This is the default unless the
-jpeg
option has been given, in which case JPEG is the default format.
- -png or --png
-
All EPS images will be converted to PNG format.
Read http://www.w3.org/pub/WWW/Graphics/PNG/
for details on the
PNG format and why PNG is better than GIF.
- -jpeg or --jpeg
-
All TIFF images will be converted to progressive JPEG format. The default format for TIFF images is the format used for EPS
images (either GIF or PNG).
- -head or --heading
-
This option determines the type of tags to use for headings in HTML. By
default, <FONT> will be used. The <H1> ... <H6> tags of HTML-1.0
may be enabled with the
-head
or -html2
option.
- -href or --href
-
An alternate style for processing the links to other files or URL's can be
enabled by giving this option. See below for details.
- -blue or --blue
-
Convert text (which may include images) coloured in blue into a hypertext
link if it contains angle brackets (<...>). All text inside the first
pair of brackets is taken as the target of the link and will not appear in
the document text.
- -html2 or --html2
-
If you want to avoid the use of tables (HTML-3.2) in the generated files, you should set this option. Note however that
some documents will look strange without tables. The <CENTER> tag will still be used, as most HTML-2.0 browsers support it.
- -index or --index
-
Build an index file by collecting all headings and definitions from the
documents listed on the command line. The references will be sorted
alphabetically (ignoring case and special characters) and will be written
to the file index.rtf.html.
- -no-li or --no-lindent
-
Ignore all settings for first- and left-indent in the
RTF(D)
document. This may be useful if the output contains too many indented
lines.
- -tables or --tables
-
This option makes the converter use tables wherever it is possible, instead
of where they are considered appropriate. Documents may look better or
worse when this option is given, so you have to try for yourself.
- -nav file or --nav-file file
-
Add navigation panels to the top and bottom of each created document. This
requires a file argument describing the logical structure of the document
tree. Read the section Navigation Panels for more information.
- -output dir or --output dir
-
Use this option to select a different destination directory for the
converted HTML and image files. The program will automatically create the
complete target directory structure, if necessary. If the given
dir does not exist, it is created. However, its parent directory must already
exist.
- -scale factor or --scale factor
-
If the default font size mapping produces too large or too small fonts, all
font sizes may be scaled by the given factor. This option does
not affect the size of inline images.
- -version or --version
-
Print the version number of rtfdtohtml and the copyright information to standard output and exit immediately.
Normal text will be reproduced unchanged in the output, with a few
exceptions:
-
Non-ASCII characters or characters from the
Symbol
font will be mapped to the ISO-Latin-1
character set used in HTML. Where this is not possible, a textual
description of the character will appear in the HTML document.
-
The paragraph sign will be replaced by a horizontal rule (<HR>).
-
Text in the Tekton font will be copied unmodified to the output, so that you can insert HTML
tags directly into the text, if necessary. Any font can be used for this
purpose, simply set the environment variable RTFDQUOTEFONT to the desired font name.
-
Different font sizes produce text styles according to the following table:
>= 24 pt. Heading level 1
< 24 pt. and >= 19 pt. Heading level 2
< 19 pt. and >= 16 pt. Heading level 3
< 16 pt. and >= 14 pt. Heading level 4
< 14 pt. and >= 9 pt. Normal text
< 9 pt. and >= 7 pt. Heading level 5
< 7 pt. Heading level 6
The font size may be further adjusted with the command line option
-scale
. It will scale all font sizes by the given amount before the table shown
above is applied. For instance, -scale
0.8
will reduce all font sizes by 20%.
Note that bold, italic or underline is allowed within headings.
-
Inline TIFF and EPS images are automatically converted to JPEG,
GIF or PNG format (depending on the command line options), other image formats like GIF or JPEG remain unchanged. Non-graphic objects embedded in an RTFD document (e.g.
files, sounds or directories) are translated into links to these objects.
-
Markers and links to other files (possibly RTF) or URL's will be fully
functional in the generated HTML, unless the target of the link has been
removed or is an unconverted
RTF(D)
file. A warning message
will be printed if the target file does not exist.
Normally, links will be small images, but if the -href
option has been given and the link has the Open File in Edit
flag set (see the
Link Inspector in Edit), the text up to the next marker will become
hot
text (inside the <A> ... </A> tags). In this case the marker is
ignored and may even be unnamed.
-
A sequence of lines that contains at least one tab on every line will be
rendered as a table if any line contains a non-initial tab. A special rule
will be applied if all lines start in bold print. This may sound very complicated, but in practice normally behaves as
expected. The use of tables may be disabled by giving the
-html2
option on the command line.
-
All lines that only contain text in a fixed-width font (like Courier
or Ohlfs) will be converted into blocks of pre-formatted text.
Note that inline graphics or changes in font size are not allowed inside a
<PRE> context.
Rtfdtohtml can automatically add navigation panels to the top and bottom of each
created document. This feature requires a file defining the relationships
with other documents; it must follow the -nav
option on the command line.
This structure file may contain zero or more lines of the form:
# comment
<tag>: <value>
<document> [title="<some text>"]
Empty lines and lines starting with `#
' will be ignored. The following
tags are currently defined (the colon must immediately follow the tag name):
- mailto
-
email address for the Feedback button
- index
-
name or URL of an index file
- prev-string
-
string to use on the Previous button
- next-string
-
string to use on the Next button
- up-string
-
string to use on the Up button
- cont-string
-
string to use on the Contents button
- index-string
-
string to use on the Index button
- mail-string
-
string to use on the Feedback button
These strings are inserted verbatim into the document and may contain
arbitrary HTML markup, including images and animations. Remember this when
you try to insert a literal &
, <
or >
.
A document can be a simple filename or a URL, optionally followed by blocks defining
subsections of the document:
{
<document1> [title="<some text>"]
<document2> [title="<some text>"]
...
}
If a value for the title attribute has been given, it will be used as the document title instead of
the default value (the basename of the input file).
Filenames or URL's may have to be surrounded by double quotes to preserve special characters
or whitespace, use \\
and \"
to insert a literal
\
and "
into a quoted string. Relative pathnames must be specified relative to the
top level directory of the document tree. The first filename given should
contain the table of contents. For example:
mailto: user@foo.bar
Contents.rtf
Chapter_1.rtfd title="Introduction"
{
dir/Chapter_1a.rtf
dir/Chapter_1b.rtf
"http://www.foo.bar/more_info.html"
}
"Chapter 2.rtfd" title="New Features"
"Chapter 3.rtf" title="Examples"
Rtfdtohtml recognizes these environment variables, if set:
- RTFDBODYATTR
-
attributes of the <BODY> tag (default
"bgcolor=White"
)
- RTFDGAMMA
-
level of gamma correction for the converted images (default 1.0)
- RTFDLEFTINDENT
-
threshold up to which changes in left-indent are ignored (in points,
default 75)
- RTFDLIBDIR
-
directory containing the configuration files
- RTFDQUOTEFONT
-
text in this font is sent through without any translation (default Tekton)
- /usr/local/lib/rtfdtohtml/*
-
various configuration files and scripts
rtftohtml.1, the rmhtml.1 manpage, the rmrtfd.1 manpage, the compress_gifs.1 manpage
Elmar Ludwig < feludwig@informatik.Uni-Osnabrueck.DE
>