Last update Dec29/19W3C//Dtd html 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> Master Style Guide: Appendix C

Appendix C
Outreach & PubGroup styles

This appendix is an explanation of the styles used on the Outreach and PubGroup intranet web sites, among other places. Information is available in the following areas:

Using page titles
Using paragraph styles
Using character styles
Using sections
Formatting forms
Working with tables
Using cross-references
Using links

These are explained in the following sections.

Using page titles

The page title goes both in the title tag block in the header and in the h1 tag block in the body. The page title in the title block capitalizes all the words (except prepositions and articles, except where they start the title). The page title in the h1 block uses down-style capitalization: the first word and proper nouns are the only ones capitalized.

Using paragraph styles

The Outreach and PubGroup pages use the following styles.

Using headers

h2 tags for first-level headers, since h1 tags are reserved for the page title in the body section; H3 tags for second-level headers, and so on. You should rarely need an H4 header, and almost never need H5 or H6 headers.

Headers should always use down-style capitalization, where only the first word (and any proper nouns) is capitalized. For example, since "Network Management" is a proper noun, both words are always capitalized. "FrameMaker" is a proper noun, so the mixed caps is required. But a header like "Using HP OpenView to manage the network" uses capitalization as shown.

Never use a lower-level header (such as H3) unless you need more than one of them. There should always be at least two headers at any level.

Using rules

The only time you see an hr rule is at an h2 tag. The format of every first-level header is:

<h2><hr><img src=...> Text</h2>

Note that the hr tag is inside the h2 tag block. Note also that the image should have an empty alt= keyword attached.

The hr rule is also used as the first tag inside the address section of the html document.

Forms may use the hr rule to separate sections of the form.

Using paragraphs

Use the P tag block around each body paragraph. Do not use P or BR for bullet lists or ordered lists, since the li block will do that for you. You may use two line breaks at the end of a bullet paragraph to make the next paragraph be the equivalent of Bullet 1 Para.

A pair of line breaks (2 consecutive BR tags) may be used to separate subsequent terms in a glossary.

Using lists

There are two major kinds of lists:

Bullet--Bullet lists are the standard ul lists. In the case of a complex bullet list like this one, the left hand side is in boldface, followed by an em-dash (two hyphens) with no space on either side, followed by the description. You can safely use 2- and 3-level bullet lists, but using third-level bullets should be generally discouraged (on the same principle as fourth-level headers, H5). You should always try to make the elements in a bullet list parallel; use the same form of the word (either all nouns, or all -ing verbs) to start each section.
Ordered--Ordered lists are used in procedures. You must be very careful when converting step lists into html ordered lists because every time you use the ol tag you restart the numbering at 1. Remember to use the START="n" attribute where needed.

Never use a lower-level list unless you need more than one entry in it. There should always be at least two bullet items at any level.

Using notes, cautions, and warnings

The terms note, caution, and warning have special meanings. Because of their importance, they are offset one indentation level from the current level of text; this is done by placing the entire text of the note, caution, or warning in a blockquote tag block. Because of their importance, they must use the alt= keyword to specify the type of notice. The terms are used as follows:

A note is used to highlight information that is important and which needs to stand out from the body text. Use the lightbulb.gif button (alt="Note") for notes.

A caution highlights information necessary to avoid damage to the system (software or hardware). Use the caution.gif button (alt="Caution") for cautions.

A warning highlights information necessary to avoid injury to personnel (humans). Use the crossbones.gif button (alt="Warning") for warnings.

In documents-in-progress there may be another notice format called a Writer's Note. Writer's Notes are used to indicate work that needs to be done or information that needs to be added. If an html document needs a Writer's Note, use the blockquote tag to indent it one level (as above) and the construction.gif button (alt="Writer's note") as the graphic image. Writer's Notes should almost never be used in released documentation.

Using images

Images should be used sparingly. There are two types of images to consider:

In-line images--In-line images, or icon buttons, should only be used in the following circumstances:
- In menu tables, where each of the choices has an associated icon, in full size (40x40)
- In first-level headers (h2 tag blocks), in full size (40x40)
- In second-level headers (H3 tag blocks), in reduced size (20x20), in complex documents (if desired)
- In navigation footers, in reduced size (20x20)
These should always be either 40x40 or 20x20 buttons. You should not use the alt= keyword with the buttons unless the button is a link. Do not use images in bullet lists unless the bullet list doubles as a menu.
Graphics--These should be used for screen images or examples, and should be used sparingly. Remember that not all web browsers are graphics-compliant or have graphics enabled, so all graphics-type images should include the alt= keyword.

All of the 40x40 buttons are in /icons/buttons.

In addition to the special icons used for notes, cautions, warnings, and writer's notes, there are also some special flag graphics that can be used as well:

coming.gif--Occasionally you may have to write a section or a page that does not yet exist, and yet it is easier to set up a template or a placeholder section or page. The special image tag coming.gif is used to flag text that is coming soon.
new.gif--Information that has been added to the page since its initial release may be flagged with the new.gif image for up to two weeks. After two weeks or so, it's no longer new, is it?
secured.gif--Information that is secured or protected, or information intended for a more limited audience, may be flagged with the secured.gif image.
updated.gif--Information that has been changed on the page since its initial release may be flagged with the updated.gif image for up to two weeks.

These four flags live in /icons/misc.

Using character styles

In the Outreach and PubGroup web sites, we never use the EM or STRONG tags, if only because different browsers can interpret them differently. Rather, we use boldface (B) tags for emphasis (and for the left hand side in complex bullet lists) and italic (I) tags to highlight new and important terms.

Use either the typewriter font (Courier, TT tags) or the preformatted or preserve (PRE) tags to indicate command text. Commands should be in monospaced font. In mixed input/output cases, input should be in bold monospaced and output in normal monospaced fonts.

Using sections

The html document, bounded by the html tag block, contains three sections:

head--The header information, containing the title.
body--The body information, containing a header block (in h1 tags) with the icon bar and then the body text.
address--The address or contact information, using an hr rule, the last modification date, and an a href="mailto:" link to the author.

Formatting forms

Forms should be set up to use the POST method:

<FORM METHOD="POST" ACTION="/cgi-bin/script.cgi">

where script is the name of the script.

Once the form is designed, use the existing Perl CGI scripts to build the form processing back-end. Note that we require the two Perl (.pl) files, then define all the variables from the submitted form via the form{} commands, then set up any local variables. We then do any local processing (if statements, system calls, and so on), build a $message variable to send to the appropriate party, and finally send it by calling sendmail directly.

Other forms may take other actions. Contact the Technical Writers (ct-techwriters@colltech.com) for assistance in formatting forms.

Working with tables

Tables are used to provide formatted data and to show menus or lists.

Formatting tables in html

We strongly recommend that the following system be used:

Align the table and /table tags with each other, indented 2 spaces from the blockquote
The table tag should include the border=2 option when borders are desired
Indent the row delimiters-TR and /TR-two spaces from the table block.
Within each row, indent the cell delimiters-TH and /TH for header rows, td and /td for data rows-two spaces from the TR block.
Each cell should be on its own line in the html source.
Inside the last cell of each row, include a line break (BR) in case non-table-compliant browsers, such as lynx, are used.

Aligning tables

The left edge of the table should be either aligned with the left edge of the text or indented one level using the blockquote tag block. The choice between these is dependent on the page author. However, tables used as menus should always be indented one level to highlight the fact that it replaces a bullet list.

Using white space

The use of white space in tables helps illustrate the data and allows the human eye to better perceive the data.

Using white space by cells

In certain circumstances, it may be necessary or wise to adjust the spacing between the cells (cellspacing), within the cells (cellpadding), or both. The default values for each is 2 pixels. Table 9 provides the rules for adjusting the spacing within the table.

Table 9
Table cell spacing rules

Table used for cellpadding cellspacing
List, annotated 3 5
List, non-annotated 3 3
Menu 2 2
Tabular data 2 2

Table used for	cellpadding	cellspacing
List, annotated	3	5
List, non-annotated	3	3
Menu	2	2
Tabular data	2	2

Using white space by rows

In tables used for lists there should be no border. However, an additional blank row (using the non-breaking space in the data cell spanning all columns) may be included above all but the first header row. Examples of this format include chronological lists.

Formatting header cells

The header cells in tables, whether used as TH or td blocks, should always have the following attributes:

The text should be in boldface. TH enables boldface by default.
The text should be aligned with the data cell text. TH is centered by default; td is left-aligned by default.
The text color should be different; the typical header text should be white (#ffffff).
The background color should be different; the typical header background color is navy blue (#00287a).

In simple tables, using white-on-blue for the single header row is proper. In more complex tables, the colors of text and background of the header rows may be tweaked as necessary. For example, in a 2-tiered header scheme, the top-level could be white on blue and the bottom-level could be black (#000000) on gold (#eaaf00). If multiple levels of heading are required, use your best judgement for subsequent heading color levels.

Formatting data cells

Data cells should be formatted normally. They can be aligned to the left, right, or center at the author's discretion.

Data cells should not change the background or font colors in normal operation. Some applications, however, such as the manager's Review Status Christmas Tree page, specifically use colors to provide information; similar use is allowed under the Outreach and PubGroup sites, if the need arises.

Using borders

Tables should use borders when the information is truly tabular, such as cost comparison numbers or other numeric data.

In tables used for simple menus or lists, there should be no border.

In some tables used for complex menus, special bordering is allowed. An example of this can be found on the PubGroup Library home page, where nested tables are used to create borders of solid blue without shading.

In some cases, tables are used for navigation links to put several links into multiple columns instead of a long list. An example of this can be found on the individual PubGroup Library content pages, where a 5-column complex table without borders is used (icon, text, empty, icon, and text, respectively) to provide the intersectional jump links at the page bottoms.

Using captions

Tables that are used for tabular data should use captions. A table caption is the word Table with leading capital letter followed by the unique table number in Arabic format (1, 2, 3), an em space, and the text of the caption. For web sites, the em space can be either a double space (two characters) or a line break (BR tag). The table number, including the word Table, should be in boldface and the caption text should be in normal text.

An example can be found in Table 9.

Using cross-references

Cross-references, both internal and external, use the standard html a href="URL" tag block to go to a reference and the a name="reference" tag block to define a reference.

Typically, we do something like the following to define a reference:

<a name="reference"></A>
<h2><hr><img src=...> Heading</h2>

This has the welcome side effect of hiding the destination from the user (who won't see the underlining or other browser hint that something points to it since we hide the a name=... tags).