We create our source documentation in Framemaker using the customized Framemaker template(s) and then convert these files to HTML via Webworks Publisher and create PDFs for printing purposes.

You can copy the templates in the Templates folder to your work folder. If you do this, periodically update your copy by recopying the original template because the template may have been revised.

You can copy the templates to your personal templates folder. Create a new folder for your templates in the Adobe Framemaker templates folder. To use the templates in this folder, select File menu-New-Document and select a template and click New. Save the file under a new name. If you reinstall or upgrade Framemaker, this folder is overwritten and your templates will be lost.

In each release folder, you will find the Online_Documentation folder. Each release folder contains a Templates folder which contains the Framemaker templates. For example, if you are working on the documentation for the 6.1 release, the directory path would be:

\root directory\documentation\project name\Online_Documentation\Templates

Important

It's okay to make a copy of the templates for your own use. But, make sure that you don't alter or move the templates in the Templates folder as these are the master templates and are shared by the Documentation Dept.

At the current time, we have the following different template versions:

Check that the Framemaker Preferences dialog box is set to Remember Missing Font Names is checked. If this is checked, FrameMaker preserves the names of unavailable fonts. When missing font names are remembered, the original fonts will reappear—even if you save a document with substitute fonts—when you open the document on a computer that has the fonts installed.

User preferences in the Framemaker Preferences dialog box should be set as follows:

Preferences dialog box

You may wish to copy the text_template file located in the Templates folder to your work folder.

The pathname of the document appears at the top of the document window.

If you made a copy of the template and placed it in your personal templates folder in Framemaker, do the following:

Importing contents from another file

If you have an existing Frame or Word document, you can import the Frame or Word file directly into the text_template file.

Writing the contents

To start writing contents in the new file:

File naming conventions

Create a descriptive file name using the following file naming convention:

bookabbreviation_uniquename.fm

For example, a file in the Concepts Guide would be named:

cpt_product_overview.fm

A book would be named:

cpt_concepts.book

Characters allowed in a file and book name:

The customized templates contain formatting tags which have been defined for creating Portal documentation. The Paragraph Catalog shows all the formatting tags available in a template.

Each paragraph tag consists of formatting characteristics such as spacing, indents, alignment, tab stops, and font properties. You apply the appropriate paragraph tag to each paragraph that you create in your document.

You must use the tags provided in these templates. The reason for this is because these tags are mapped in the Webworks template, which determines how the HTML documents will display.

Webworks Publisher made by Quadralay is a software tool that we use to convert Framemaker files to HTML and we convert all the files together to keep intact the links created between the files.

This section provides examples of the paragraph tags in this template. To apply a paragraph tag, do the following:

Paragraph catalog

You can apply paragraph tags from the Paragraph Catalog (¶):

Apply paragraph tags with keyboard shortcuts

You can apply paragraph tags using the keyboard shortcut so that you can work mouse-free.

If you apply formatting overrides to the paragraph tags to achieve different formatting, this formatting won't be carried over to the HTML files when the file is converted to HTML. Creating an override to a paragraph tag means when you change any of the tag's attributes.

Keyboard shortcuts

Some commonly used keyboard shortcuts:

Action	Shortcut key
Copy selected text	Ctrl c
Delete selected text	Ctrl x
Open character designer	Ctrl d
Open paragraph designer	Ctrl m
Paste last copied text or cut text	Ctrl v
Refresh screen	Ctrl l
Repeat previous formatting action	Esc j j
Select a word	Double-click
Select paragraph	Triple-click
Undo last action	Ctrl z

Use the following paragraph style tags to apply formatting to paragraphs:

Paragraph tags in the text template 

Paragraph tag	Usage
Body	Regular paragraph text
BodyBullet	First-level bulleted list
BodyBullet2	Second-level bulleted list
BodyIndent	Indented tag when a paragraph follows a Numbered1 tag. The BodyIndent tag is intended for use within non-numbered paragraphs within a numbered list. In HTML conversion, this tag will not be indented.
BodyIndent2	Indented tag when a paragraph is in a second-level list
BodyIndent3	Indented tag when a paragraph is in a third-level list
BodyLineUp	Only used after the chapter table of contents. Use a body tag or Head1 after it. Don't use it to create a line within a chapter. Do not use for formatting text
bullet+Table	Bulleted list inside of table
Caution	Cautionary message
Caution indent	Cautionary message within a numbered or bulleted list
CellBody	Text inside of table cell
CellBody Indent	Indented text inside of table cell
CellHeading	Heading inside of table cell
ChapterNumber	Chapter autonumber used with Title tag to create numbered chapter. Number appears automatically. Don't type text in this paragraph.
code	Text that is to be displayed as code sample
codeIndent	Code sample that is indented from the left margin
codeWide	Code sample that spans the width of page
Comment	Text that is used for writer's or reviewer's comments.
FigureCaption	Title caption for graphics
graphic	Used as anchor for tables and graphics This anchor appears magenta when text symbols are turned on.
Head1G	Used for headings in Glossary. Use in Glossary only
Head1	First-level heading. Note that this tag is used with the ChapterNumber tag and always begins on a new page.
Head2	Second-level head
Head3	Third-level head
Head4	Forth-level head
Head1TOC	Table of contents first-level head. Used in top-of-page table of contents
Head2TOC	Table of contents second-level head. Used in top-of-page table of contents
Head3TOC	Table of contents third-level head. Used in top-of-page table of contents
Hier	Used at the top of a chapter page as a placeholder. Do not use to format.
Important	Important information to bring to the reader's attention
Important indent	Important message in a list
Note	To bring a message to the reader's attention.
Note indent	Note message within a list
Numbered1	Numbered procedures or steps
Numbered1+	Additional numbered procedures or steps
Numbered1+Table	Numbered procedures or steps in a table cell
Numbered1Table	Numbered procedures or steps in a table cell
Numbered2	Second-level numbered item in a list and is the first item. Numbered alphabetically.
Numbered2+	Second-level numbered item that follows
Numbered2_indented	Third-level numbered item in a list that is numbered alphabetically.
Numbered2_indented+	Third-level numbered item that follows
TableCaption	Title caption of a table
TableFootnote	Footnote in a table cell
Term	Indicates terminology
Tip	Hint or useful tip to the reader
Tip indent	Hint or useful tip within a list
Title	Title of a document appearing at the beginning of a document.
TitleNoNavLinks	Not for writers to use. This tag is used in documents that are not to have navigation links in the HTML version. Do not use to format.
TitleNoNumber	Title that has no autonumber. Used for Index template only.
UltraCaution	To be used for rare instances in documentation when the user must follow steps in exact order or the procedure will fail. Future addition to template
Caution+Table	Caution message inside of table cell
Important+Table	Important message inside of table cell
Note+Table	Note inside of table cell
Tip+Table	Tip inside of table cell

This section provides examples of the paragraph tags in this template and instructions on how the tags should be used.

Title

Use for the title of a chapter at the beginning of a document. The general rule for capitalization of titles and headings is to initial cap the first word in a title or heading, unless it is an opcode, utility, or command.

Chapter Number

The ChapterNumber comes with the Title tag when you insert the Title tag and is the chapter number. The ChapterNumber tag uses an autonumber (building block) so that the chapter number changes automatically.

Head1

Use the Head1 paragraph tag for level 1 headings for the main topic in a chapter. It is customary to separate different level headings with transitional text. Write an introductory sentence to introduce a bulleted list or instructions.

Head2

Use the Head2 paragraph tag for level 2 headings that pertain to a main topic in a chapter. It is customary to separate different level headings with transitional text. Write an introductory sentence to introduce a bulleted list or instructions.

Head3

Use the Head3 paragraph tag for level 3 headings that pertain to a second level topic in a chapter. It is customary to separate different level headings with transitional text. Write an introductory sentence to introduce a bulleted list or instructions.

Head4

Use the Head4 paragraph tag for level 4 headings that pertain to a third level topic in a chapter. It is customary to separate different level headings with transitional text. Write an introductory sentence to introduce a bulleted list or instructions.

Use the Body tag for all regular paragraph text. The Body tag is designed to following the Heading paragraph tags and is included as the next Para Tag in the Heading tags. The Heading tags are designed to keep with the Body tag so that you don't create widow/orphan lines.

The template has two types of list formats: bulleted or numbered. The bulleted tag is used for items that are related, but nonsequential. The numbered tag is used for items that follow a sequence. For example, you would use the numbered tag to provide instructions to the reader and the reader must follow the numbered instructions in the sequence presented.

BodyIndent

Use the BodyIndent paragraph tag when you want to write a new paragraph under a Numbered1 style or BodyBullet style. For example:

BodyIndent2 and BodyIndent3 paragraph tags are used in paragraphs following second-level and third-level lists.

Bulleted Lists

Use the BodyBullet paragraph tag to organize related, nonsequential information. Use the BodyBullet2 paragraph tag to organize related, nonsequential information within a BodyBullet list.

For additional paragraphs under the same bullet item, use the BodyIndent tag.

BodyBullet, BodyBullet2 examples

Use the BodyBullet2 as a second-level bulleted list.

Series within a bulleted item

Using this series scheme within a bulleted list reduces the need for deeper levels of bullets.

Bulleted list without punctuation

If listed items are not complete sentences (sentence fragments), do not use periods.

Numbered Lists

Use the Numbered list paragraph tags for numbered procedures. Use the Numbered1 tag for the first item in the list to restart the numbering. Use the Numbered1+ for the following items in the list. To start a subcategory, use the Numbered2 and Numbered2+ tags.

If a numbered item requires another level of sequential information, the subset must use a different identification scheme to distinguish it from the numbered items in the first sequence.

Use the code tags for text that should display as code information. If the code contains multiple lines, use the Shift-Enter keys to create a soft return. This paragraph has a top and bottom border, but in the HTML it displays without the borders. To create indentions or a tabbed effect in the code sample, use the Shift space-bar to create hard spaces.

code paragraph tag for bits of code
    To create indentions or a tabbed effect in the code sample,     use the Shift space-bar to create hard spaces.

codeWide paragraph tag when you have very long lines of code. For example, screens of code.

The following section from the Adminmgr.ini file shows where you add the new DLL information:

; Extensions DLLs to deal with custom object types
[Extension DLLs 60]
ExtensionDLL1=emailserv.dll
ExtensionDLL2=provider.dll
ExtensionDLL3=ddebitpay.dll
ExtensionDLL4=your_dll_name.dll

Use the codeIndent tag for code sample in numbered or bulleted lists.

CodeWide sample

Building POID for the input flist in Java

void FindBillItemsForAnAccount(PortalContext connection, Poid acctPoid)
{
// Start building the search input FList.

// Obsolete way:
Poid searchPoid = new Poid( connection.getCurrentDB(), 0, "/search" ); 

// Right way:
Poid searchPoid = new Poid( acctPoid.getDb(), 0, "/search" );	 	 	 	 	  
.
.
}

term

This is a term definition using Body paragraph tag.

The Character Catalog contains defined character tags or styles that you can apply to words and characters in your Frame document. The character tags are applied to text or paragraphs that already have been assigned a paragraph tag.

These character tags have specific uses and you should know what these are before using these tags.

Character catalog

Apply character tags from the Character catalog:

Character catalog

If you apply formatting overrides to the character tags to achieve different formatting, this formatting won't be carried over to the HTML files after the file is converted using Webworks Publisher.

Apply character tags with keyboard shortcuts

You can apply character tags using the keyboard shortcut so that you can work mouse-free.

Applying Bold character tag versus using Quick Access bar

Applying B(old) from the Quick Access bar is not the same as applying the Bold character tag. In our documentation, please use the Bold character tag to bold text as this formatting carries over to HTML.

Use the following character tags to apply formats to individual words or phrase.

Character tags & usage

Character tag	Usage	Example
Default ¶ Font	Restores the default paragraph font to the selected characters and removes all character tags.
Bold	Add format to names of opcodes, utilities, applications, programs, etc. Required: Applying B(old) from the Quick Access bar is not the same as applying the Bold character tag. In our documentation, please use the Bold character to bold text as this formatting carries over to HTML.	Bold selected terms to make them stand out.
copyright	Copyright logo
CodeVariable	Apply to variables that appear in code text.	CodeVariable 10 pt Italic Palatino
Emphasis	Use to stress certain words	Emphasis is italic, but the size and font family are determined by the paragraph tag it's used in.
Subscript	Use to create subscripted characters	Subscript why would we ever use this???regular word
Superscript	Use to create superscripted characters	Put TM and ® symbols in superscript. (The trademark tag does this for you.)
Title	Italic and underlined and can be used to identify title of something.	Title is 10 pt italic underlined Palatino
Trademark	Trademark logo	For trademarking apply the trademark tag to ® or TM
URL	Apply to text that is to be an external hypertext link when the document is converted to HTML via Webworks.	Future addition

Some text is repeated in the sample tags so that you can see the left indent.

Note	Some writers find the distinctions between, notes, importants, and tips confusing.

Important

Even more noteworthy. Even more noteworthy. Even more noteworthy.

Tip	Save them time; show an alternative. Save them time; show an alternative. Save them time;

Save them from doing bad things, like corrupting their data. Save them from doing bad things.

Another version of the same tags for use in a list or procedure. Use the indented version so that numbered lists do not break in the HTML.

Note	Note indent. For a note in a list or procedure. For a note in a list or procedure.

Important

Important indent. For an important note in a list or procedure. For an Important note in a list or procedure.

Tip	Tip indent. For a tip in a list or procedure. Tip indent. For a tip in a list or procedure.

table border="0" cellpadding="0" cellspacing="0"> Caution! Caution indent. For a caution in a list or a procedure. Save them from doing bad things, like corrupting their data.

Use a noborders table for notes and related formats that have multiple paragraphs. For example:

Important

The TeraComm DM database number must match the number in these entries: The dm_db_no entry in the TeraComm pin.conf file The DB entry of the TeraComm Manager Publisher definition in the payloadconfig.xml file The TeraComm DM port number must match the number in the dm_port entry in the TeraComm DM pin.conf file.

An example not using a table:

Note

1. mmm

2. mmmm

Table caution, important, note, and tip tags used in table

	Sample new tags
Caution paragraph tag is used to warn the user about doing certain things.	Caution! Save them from doing bad things, like corrupting their data. Save them from doing bad things.
Important paragraph tag is used to call the user's attention to something that they should know about.	Important Even more noteworthy. Even more noteworthy. Even more noteworthy. Even more noteworthy. Even more noteworthy. Even more noteworthy.
Note paragraph tag is used to call the user's attention to something noteworthy, but is not urgent.	Note Some writers find the distinctions between, notes, importants, and tips confusing.
Tip paragraph tag is used to give the user a helpful tip or alternative.	Tip Save them time; show an alternative. Save them time; show an alternative. Save them time; show an alternative. Save them time; show an alternative. Save them time; show an alternative.

Use the Comment paragraph tag to insert a paragraph with review questions, comments, or reminder notes to yourself during the composition and review cycles. If you need to write more than one paragraph in the same Comment, press [Shift][Enter] to add a soft return.

If your document is also produced in PDF, apply the Comment condition tag to the entire paragraph (if the text disappears, change the Show/Hide Conditional Text setting to Show All). Remember to reselect Show (hide conditions not on the Show list) before you regenerate your TOC.

The WebWorks template maps the Comment paragraph tag to "No Output" to ensure that comments do not appear in the converted HTML files.

There are several types of links you can create in our documentation and the URL character tag link is one of them.

Use the URL character tag for applying to text that is a reference to an external URL address, that is, outside of pin.com.

This character tag is not to be used in place of the gotoURL hypertext markers that are used for linked references to flist specs, pol.c files, and object specs.

The following paragraph tags should not be used for formatting. Some of these tags have special meanings in their HTML mappings.

This paragraph tag was created for the Index template. This title is not carried in the document header.

This is the same as TitleNoNumber used for special cases where the HTML should not include navigation links and Next/Previous buttons. The Index is an example of a file that uses this format.