NAME

SYNOPSIS

rtfdtohtml

[-G] [-gif|-png] [-jpeg] [-head] [-href] [-blue] [-html2] [-index] [-no-li] [-tables] [-nav file] [-output dir] [-scale factor] [-version] file ...

DESCRIPTION

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.

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.

Conversion Details

• 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.

Navigation Panels and Titles

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

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"

ENVIRONMENT

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)

FILES

/usr/local/lib/rtfdtohtml/*

various configuration files and scripts

SEE ALSO

AUTHOR