Isis 3 Documentation

Style Guide

Object source code styles and conventions

Home

Rules of Thumb

All tags must have an ending tag, even if it is not normally required. Eg. Text in a bullet, <li>, must end with an ending bullet tag, </li>
Empty tags (meaning tags that do not contain text and normally do not have an ending tag) such as img must have a slash before the ending angle bracket of the tag. Eg. <img src="bob.gif" width="150" height="75" alt="Bob"/>
Attribute (name-value pairs inside an HTML tag) values must be quoted. Eg. <table width="600">
Only use body level tags (tags allowed in the body of an HTML document).
Do not use document structure elements, such as headings (h1, h2, etc.) and hr. Such elements are intended to structure the document, not serve as pretty formatting. Your documentation is transformed into HTML which already contains document structure elements.
Use lower case for tag tag and attribute names. <img src="bob.gif" width="150" height="75" alt="Bob"/> not <IMG SRC="bob.gif" WIDTH="150" HEIGHT="75" ALT="Bob"/>
Avoid elements deprecated in HTML 4.01 and higher. Favorites include U, CENTER, and FONT.

These rules are not a matter of taste, style, or preference... they're a matter of conformance to standards.

Reference

HTML Tags

b Bold. Renders current font as boldface. This is bolded appears as This is bolded

i Italic. Renders current font in italics. This is italicized appears as This is italicized

em Phrase element meaning "emphasis". Generally rendered by browsers in italics. This is emphasized appears as This is emphasized

strong Phrase element meaning "strong emphasis". Generally rendered by browsers in boldface. This is strongly emphasized appears as This is strongly emphasized

sup Superscript Bob1 appears as Bob¹

sub Subscript Bob1 appears as Bob₁

tt Teletype font. Rendered in browser's default fixed-width font. <tt>This is teletype</tt> appears as This is teletype

pre

Preformatted text. Generally rendered in browser's default fixed-width font, with whitespace intact, and automatic word wrap disabled. Generally browsers render all whitespace within this tag, and add padding before and after the tagged text. This is not a quick and dirty alternative to tables! Use if for code snippets, data file snippets, etc.

            <pre>
              This is preformatted text.
              53.6    82.1    536.3
               8.53  137.6     66.3
            </pre>

appears as

              This is preformatted text.
              53.6    82.1    536.3
               8.53  137.6     66.3

Whereas without the PRE tag, you'd get this:

This is preformatted text. 53.6 82.1 536.3 8.53 137.6 66.3

table

Table start/end

Contains "tr" and "caption" tags. See more table tags below. Eg.

            <table>
              <caption>My table caption</caption>
              <tr>
                <th>
                Row 1, Column 1 Header
                </th>
                <th>
                Row 1, Column 2 Header
                </th>
                <th>
                Row 1, Column 3 Header
                </th>
              </tr>

              <tr>
                <td>
                Row 2, Column 1
                </td>
                <td>
                Row 2, Column 2
                </td>
                <td>
                Row 2, Column 3
                </td>
              </tr>

              <tr>
                <td>
                Row 3, Column 1
                </td>
                <td>
                Row 3, Column 2
                </td>
                <td>
                Row 4, Column 3
                </td>
              </tr>
            </table>

Looks like:

My table caption
Row 1, Column 1 Header	Row 1, Column 2 Header	Row 1, Column 3 Header
Row 2, Column 1	Row 2, Column 2	Row 2, Column 3
Row 3, Column 1	Row 3, Column 2	Row 4, Column 3

caption Adds a caption to this table

tr Table row start/end Contains TH and TD tags

th Table row or column header cell Usually rendered with highlighting, bolding, or other special formatting to make the cell stand out. Some accessibility readers will audibly repeat the contents of the TH before each cell in the column/row.

td Table cell Stardard table cell in a row

Special Characters

Some keyboard characters are reserved for special use. Some characters you may wish to use are not accessible from the keyboard. Use the special character sequences below.

&	&	Ampersand
<	<	Less than
≤	≤	Less than or equal
>	>	Greater than
≥	≥	Greater than or equal
°	°	Degree
±	±	Plus or minus
÷	÷	Division symbol
×	×	Multiplication symbol

Document History

Deborah Lee Soltesz	2005-10-31	Fixed format instructions for @history (date and author were inverted)
Deborah Lee Soltesz	2006-06-05	Updated @image use instructions and conventions
Deborah Lee Soltesz	2006-07-29	Update CVS tags described in the guide so that CVS wouldn't automatically replace the tag with actual information when this document is checked in. (Replaced $ signs with ISO8859-1 entity, treating the $s as special characters).

Isis 3

Isis 2