HTML output

HTML is an online format optimized only for certain kinds of presentation. For example, you cannot easily create a two-column layout in HTML. For this reason, do not expect your HTML documents to look identical to the FrameMaker originals. If design items in your documents have no acceptable equivalents in HTML, consider converting to PDF instead of HTML. For information, see Save as PDF.

Using templates that map well to HTML

To minimize fine-tuning when you save documents as HTML, create your documents from one of the supplied FrameMaker templates. The formats of these templates map easily to HTML equivalents.

Sample chapter template before and after HTML conversion

HTML was designed not as a formatting language but as a way of presenting the structure of a document (its semantics). In some cases, however, you may be concerned with the format of a document as well as its semantics. You may want to preserve the look of your FrameMaker document more than is possible with regular HTML elements alone.

For example, suppose you have a document that uses blue 20-point type for the first letter of a chapter. An HTML style sheet can preserve unique formatting of this kind.

An HTML cascading style sheet is created for you with the same name as the main HTML file but with an extension of .css. It is a standardized file format that many Web browsers can use and interpret. A .css style sheet contains formatting specifications that can duplicate the font, style, size, indents, spacing, and margins of the original document.

The HTML file contains a reference to a .css style sheet. If the browser finds the style sheet, it uses the information to format the Web page. If the browser does not support style sheets, it uses only the built-in formatting defined for each HTML element.

1. Save your document as HTML. A .css file is automatically created in the same folder as the HTML file.

2. Copy the HTML style sheet (.css file) to the web server in the same folder as your HTML files.

A uniform resource locator (URL) is the location of a document anywhere on the Internet or on an intranet. You can embed a special marker in a FrameMaker document that becomes a link to a URL when the document is saved as HTML or PDF.

1. Select the text you want to be linked to a URL and apply a character format to it. For example, you might apply an underline format to the words Click here for more information.

2. Click in the formatted area, and choose Insert > Hypertext.

3. Choose Message Client from the Command pop-up menu and enter the following in the Syntax text box:

    message URL url_name 

   Replace url_name with the URL you want to link to. For example, to link to the Adobe Systems home page, you would enter the following:

    message URL http://www.adobe.com 

4. Click New Hypertext Marker. When the document is converted to HTML, XML, or PDF, clicking the formatted text displays the location specified by the URL.

You can convert a large file into a series of small HTML subdocuments that are linked to one parent document. The parent document can then function as a linked table of contents for the subdocuments.

FrameMaker document and the simulated TOC in a Web page

Subdocuments are automatically named sequentially. For example, when you save MyDoc to HTML, the parent document is called MyDoc.html, the first subdocument is MyDoc.1.html, the second one is MyDoc.2.html, and so on. Do not rename the files; otherwise, the links will become invalid.

The hierarchy of heading levels in the subdocuments is controlled by the Headings table.

1. Adjust your document mappings so that a heading starts a new file. Do this by using the Start New, Linked Web Page option in the HTML Setup dialog box.

   Note: Look for a heading whose contents are neither too large nor too small. (Readers might get lost if they have to do too much scrolling or might be frustrated if the page they jump to has only one paragraph.) Also, you may want to make sure some text appears before the first instance of the heading you choose so that there is an introduction to the list of links.

2. Give readers an easy way to return from the linked subdocuments to the parent document by defining the EndOfSubDoc or StartOfSubDoc system macro. The text or graphics defined by this macro will appear at the end or the start of each linked Web page as in the following example.

   Macro Name	Replace With
   EndOfSubDoc	<div> <p><a href="<$parentdoc>">Return to main page</a></p> <p><a href="<$prevsubdoc>">Go to previous page</a></p> <p><a href="<$nextsubdoc>">Go to next page</a></p> </div>

3. Save the file or book as HTML. The parent document will contain the linked table of contents.

Image maps on a web page are graphics with areas defined as links. Image maps can add visual interest to otherwise plain text-only links to web pages.

When you convert a FrameMaker document to HTML or XML, graphics in the main text flow are automatically converted to image maps if you have set them up correctly. They convert in these cases:

• When a graphic in an anchored frame has one or more text frames on top of the graphic, and these text frames have valid hypertext markers in them.

• When a graphic in an anchored frame has a rectangular matrix of links over it.

When you save documents as HTML, all graphic files imported by copying into anchored frames are converted to GIF format unless you specify that all the graphics be saved to another format. Each graphic is saved to a separate file. Text in anchored frames is also converted to GIF.

Graphic files imported by reference are left in their original locations unless you specify that copies should be made. In that case, the formats are inspected and converted as needed (preserving the dpi scaling of a graphic). The new files are created in the same folder as the HTML document.

1. Choose File > Utilities > HTML Setup. The HTML Setup dialog is displayed.

   

   FrameMaker either loads the current mappings into the HTML Setup dialog box or, if no mappings have been created yet, creates default mappings.

2. From the Map pop-up menu, choose the type of formats to map (Character Formats, Paragraph Formats, or Cross-Reference Formats).

3. Specify a mapping by choosing a FrameMaker format from the From: pop-up menu and an HTML element or macro from the To: pop-up menu.

   Tip: You can click in the document to select a format to adjust. The HTML Setup dialog box immediately shows the current mapping for the format you click.

4. Choose from the following options:

   • If you are mapping paragraph formats and want to include the paragraph autonumber in the converted text, click Include Autonumber. (You do not have to include an autonumber for items in a list.)

   • If you are mapping to Heading (AutoLevel) and want to start a new Web page whenever this format is found, click Start New, Linked Web Page.

     Use this option to break up a long FrameMaker document into several HTML files, each linked to a single file. Whenever the specified format is found, FrameMaker leaves the heading in the original file (the parent file) and makes it a link to a subdocument whose content starts at the heading format and continues until the next instance of the format. For information on using this setting to simulate a table of contents, see Create links that simulate a TOC.

   • If you are mapping to the List Item element for either a bulleted or numbered list, and want to specify how many levels deep the item is (which usually translates as how much the item should be indented), enter a Nest List at Depth value.

5. Click Change to accept the mapping.

6. Repeat steps 2 through 5 as needed.

7. When you finish specifying mappings, close the dialog box and save the document as HTML.

If you want to edit the mapping tables on the HTML reference page, be sure to close the HTML Setup dialog box first. Keeping the dialog box open results in an error when you try to edit the tables on that page.

HTML supports six levels of headings. You can convert any FrameMaker paragraph format to a heading by mapping it to Heading (Autolevel). With this special mapping, headings in the document are mapped to H1, H2, and so on, according to their relative levels and based on the highest-level mapping in that file. The advantage of this method is that if the document is broken into separate HTML files, each will always have an H1 mapping and an appropriate hierarchy of headings under that H1.

For example, suppose your document uses Title1, Title2, and Title3 formats. When you convert to HTML, you might want to break up the document into two files, and the second file might contain only instances of Title2 and Title3. The autolevel feature ensures that Title2 maps to H2 in the first file but maps to H1 in the second file.

For more information on how the autolevel headings work, when you choose to split a document into separate HTML files, see Use the Headings reference page.

If you want to fine-tune the autolevel mechanism or override the autolevel function and make mappings to specific heading levels, you must edit special tables on reference pages of the FrameMaker document. For more information, see Edit the HTML Mapping table.

FrameMaker automatically maps bulleted lists to HTML unordered lists and numbered lists to HTML ordered lists. If you want to override the automatic mapping, you must edit a table on the HTML reference page of the FrameMaker document. (See Edit the HTML Mapping table.)

In the HTML Setup dialog box, you can define the level of a list by specifying a value for Nest List at Depth. Typically, a browser displays different levels with different amounts of indentation.

You can include a FrameMaker autonumber in the converted text by choosing Include Autonumber. However, most browsers provide their own bullet characters and numbers with lists, so you are unlikely to use this option when converting lists.

The following table shows paragraph-based HTML elements.

The following table shows character-based HTML elements.

A typical cross-reference in a printed document such as “See Syntax on page 8 for more information” loses its meaning in HTML documents, which do not use page numbers. For this reason, cross-references are mapped by default to a predefined cross-reference conversion macro called See Also. The See Also macro changes the cross-reference so that it refers to the text of the paragraph but not to the page number (for example, “See Syntax for more information”). The cross-reference text in the original document becomes an HTML link in the converted document regardless of what format is used.

You can modify the See Also macro, or you can create your own macros and then map cross-reference formats to them.

When you first map a cross-reference, the See Also macro is the only macro in the To pop-up menu in the HTML Setup dialog box. If you create other conversion macros, they will appear in this menu as well. For information on how to create and edit cross-reference macros, see Use HTML conversion macros.

Two other choices in the To: pop-up menu let you map a cross-reference in other ways:

• Choose Original Cross-Reference Format to leave the text of the cross-reference unchanged.

• Choose Throw Away to delete the text of the cross-reference.

You can fine-tune the HTML conversion by editing tables on two special FrameMaker reference pages: the Headings page and the HTML page. If you are converting a book, the reference pages are BookHeadings and BookHTML. (See Convert books to HTML files.) For general information on reference pages, see Reference pages.

The reference-page tables are set up automatically the first time you save as HTML or the first time you choose File > Utilities > HTML Setup. The Headings reference page contains one table, the Headings table. The HTML reference page contains the following tables:

• The HTML Mapping table. (See Edit the HTML Mapping table.)

• The HTML Options table, which contains the settings you make in the Options dialog box. (See Specifying graphics conversion.)

• The HTML System Macros table, the HTML Cross-Reference Macros table, and the HTML General Macros table. (See Use HTML conversion macros.)

• The HTML Character Macros table. (See Convert special characters.)

If the tables are large, the HTML reference page will continue on for as many pages as needed.

The Headings table on the Headings reference page identifies which tags should be used for headings and what their hierarchy is.

The Headings Table sets up the relative hierarchy of the headings.

Using this table, you can modify the mappings for headings and the relative levels of those headings.

To Help you identify heading formats, text appears in the same font and point size as the headings do on the body pages of the document.

The HTML Mapping table on the HTML reference page contains the mappings you assign using the HTML Setup dialog box. (Mappings for headings appear here too, as well as in the Headings table.) You usually do not need to edit this table directly, but you might want to edit it in the following situations:

• To bypass the autolevel mapping of headings and instead map a format explicitly to a heading level such as H1 or H2. (See Autolevel mappings for headings.)

• To change many mappings quickly or globally by using Edit > Find/Change.

• To change a bulleted list to a numbered list, or the reverse.

• To use an HTML element that is not available through the HTML Setup dialog box.

• To document the mappings in the Comments column of the table.

The first column of the Mapping table contains a FrameMaker source item prefixed with a letter that indicates the type of item: P for paragraph format, C for character format, or X for cross-reference format. The second column can contain the name of an HTML element or an HTML conversion macro name.

The HTML Mapping table on the HTML reference page

For information on defining macros, see Use HTML conversion macros.

1. Choose View > Reference Pages and display the HTML page.

2. Locate the Mapping table on that page, and find the format whose mapping you want to change.

3. Make the following changes as needed:

   • In the Element column, enter the name of the HTML element or conversion macro that the format is to be mapped to. If you are not sure of the correct HTML element name, see the tables in Mappings for lists. Enter H* to map to an autolevel heading.

   • In the New Web Page column, enter Y for Yes to create a separate HTML document whenever this format is found. Otherwise, enter N for No.

   • In the Include Auto# column, enter Y or Yes to include the full autonumber text of this format in the conversion. Otherwise, enter N or No.

   • In the Comments column, enter any text to document the purpose of the mapping, special cases, and so on. You can leave this column blank.

   An edited row might look like this.

   FrameMaker Source Item	HTML Element	New Web Page?	Include Auto#?	Comments
   P:Fnote	FOOTNOTE	N	N	Will not work in all browsers

The FrameMaker character set and the character set used by HTML and the Web are not identical. Because of this, some characters are mapped to substitutions when converted to HTML. Some mappings are internal and rely on special HTML codes called entities. (For example, curved quotation marks are changed to the entity for straight ones.) Other substitutions are defined in the Character Macros table. For example, an em dash is defined as two hyphens. If no mapping exists, the character is ignored.

The following characters either have special predefined mappings or are treated specially.

You can add or change mappings for characters by adding or editing entries in the Character Macros table. As the previous table illustrates, you can map characters to text or to HTML character and entity references (which begin with an ampersand and end with a semicolon).

1. Choose View > Reference Pages and display the Character Macros table on the HTML page.

2. Edit a mapping, or create a new row (by pressing Control+Return) and enter a new mapping.

If you are unsure how to type a special character in the first column, look up its keystroke.

For example, to set up mappings for the dagger character, the trademark symbol, and the ae ligature, you could add the following rows.

1. Choose View > Reference Pages and display the HTML page.

2. Edit a macro in a table, or create a row (by pressing Control+Return) and enter a new macro starting with a macro name. (You cannot add macros to the HTML System Macros table; you can only edit their replacement text.)

Replacement text can contain any mixture of text, HTML codes, and FrameMaker building blocks. Be sure that you enter valid HTML code; FrameMaker does not check the HTML syntax.

You can use the following building blocks in HTML conversion macros to include special types of text.

Building blocks are enclosed in angle brackets (< >) and begin with a dollar sign ($). Enter these building blocks in all lowercase letters.

HTML system macros are a special case because you can redefine them, but you cannot add new ones.

These macros are especially useful when splitting up documents into separate HTML files. For example, you can define the StartOfSubDoc macro so that your company logo appears at the top of every new Web page.

In these descriptions, the parent document refers to the first Web page and subdocument refers to a document linked to the parent document.

The title of an HTML document appears in the window’s title bar. When you add a bookmark to that page, it also appears in the bookmark list. Initially, the <$defaulttitle> building block is used for the title, which uses the first heading in an HTML file as the title for that file. Usually, the default titles are satisfactory. However, you can specify a different title by editing macro tables on the HTML reference page.

System macros and general macros can define two sets of replacement text: one that appears in the body of the code and one that is inserted in the head area.

You can modify the default title, or you can remove the default title and set up your own titles.