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

<head>
  <title>Master Style Guide: Appendix C</title>
  <liNK rev="made" href="mailto:jss@colltech.com">
  <META http-equiv="Content-Style-Type" content="text/css">
  <STYLE type="text/css">
    <!--#include virtual="guidestyle.css"-->
  </STYLE>
</head>

<body bgcolor="#FFFFFF" TEXT="#00287A" liNK="#0000FF" AliNK="#EAAF00"
      VliNK="#8000FF">

<h1>Appendix C<br>
Outreach &amp; PubGroup styles</h1>

<p>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:</p>

<ul>
  <li><a href="#PAGE">Using page titles</a></li>
  <li><a href="#STYL">Using paragraph styles</a></li>
  <li><a href="#CHAR">Using character styles</a></li>
  <li><a href="#SECT">Using sections</a></li>
  <li><a href="#FORM">Formatting forms</a></li>
  <li><a href="#TABL">Working with tables</a></li>
  <li><a href="#CROS">Using cross-references</a></li>
  <li><a href="#liNK">Using links</a></li>
</ul>

<p>These are explained in the following sections.</p>

<a name="PAGE"></a>
<h2><hr> Using page titles</h2>

<p>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.</p>

<a name="STYL"></a>
<h2><hr> Using paragraph styles</h2>

<p>The Outreach and PubGroup pages use the following styles.</p>

<a name="head"></a>
<H3>Using headers</H3>

<p>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.</p>

<p>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.</p>

<p>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.</p>

<a name="RulE"></a>
<H3>Using rules</H3>

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

<blockquote><PRE><tt>&lt;h2&gt;&lt;hr&gt;&lt;img src=...&gt; Text&lt;/h2&gt;</tt></PRE></blockquote>

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

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

<p>Forms may use the hr rule to separate sections of the form.</p>

<a name="PARA"></a>
<H3>Using paragraphs</H3>

<p>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.</p>

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

<a name="liST"></a>
<H3>Using lists</H3>

<p>There are two major kinds of lists:</p>

<ul>
  <li><b>Bullet</b>--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.<br><br></li>
  <li><b>Ordered</b>--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.<br><br></li>
</ul>

<p>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.</p>

<a name="NOTE"></a>
<H3>Using notes, cautions, and warnings</H3>

<p>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:</p>

<blockquote>
  <blockquote>
    <table border="0">
      <TR valign=top>
        <td><img src="/icons/buttons/lightbulb.gif" alt="[Note]"></td>
        <td><font FACE="Arial Black", "Arial", "Helvetica", "Geneva">
          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.</font></td>
      </tr>
    </table>
  </blockquote>
</blockquote>

<blockquote>
  <blockquote>
    <table border="0">
      <TR valign=top>
        <td><img src="/icons/buttons/caution.gif" alt="[Caution]"></td>
        <td><font FACE="Arial Black", "Arial", "Helvetica", "Geneva">
          A caution highlights information necessary to avoid damage to
          the system (software or hardware). Use the caution.gif button
          (alt="Caution") for cautions.</font></td>
      </tr>
    </table>
  </blockquote>
</blockquote>

<blockquote>
  <blockquote>
    <table border="0">
      <TR valign=top>
        <td><img src="/icons/buttons/crossbones.gif" alt="[Warning]"></td>
        <td><font FACE="Arial Black", "Arial", "Helvetica", "Geneva">
          A warning highlights information necessary to avoid injury to
          personnel  (humans). Use the crossbones.gif button (alt="Warning")
          for warnings.</font></td>
      </tr>
    </table>
  </blockquote>
</blockquote>

<p>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.</p>

<a name="IMAG"></a>
<H3>Using images</H3>

<p>Images should be used sparingly. There are two types of images to
consider:</p>

<ul>
  <li><b>In-line images</b>--In-line images, or icon buttons, should
    only be used in the following circumstances:
    <ul>
      <li>In menu tables, where each of the choices has an associated
        icon, in full size (40x40)</li>
      <li>In first-level headers (h2 tag blocks), in full size
        (40x40)</li>
      <li>In second-level headers (H3 tag blocks), in reduced size
        (20x20), in complex documents (if desired)</li>
      <li>In navigation footers, in reduced size (20x20)</li>
    </ul><br>
    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.<br><br></li>
  <li><b>Graphics</b>--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.<br><br></li>
</ul>

<p>All of the 40x40 buttons are in /icons/buttons.</p>

<p>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:</p>

<ul>
  <li><b>coming.gif</b>--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.<br><br></li>
  <li><b>new.gif</b>--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?<br><br></li>
  <li><b>secured.gif</b>--Information that is secured or protected,
    or information intended for a more limited audience, may be flagged
    with the secured.gif image.<br><br></li>
  <li><b>updated.gif</b>--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.<br><br></li>
</ul>

<p>These four flags live in /icons/misc.</p>

<a name="CHAR"></a>
<h2><hr> Using character styles</h2>

<p>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.</p>

<p>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.</p>

<a name="SECT"></a>
<h2><hr> Using sections</h2>

<p>The html document, bounded by the html tag block, contains three
sections:</p>

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

<a name="FORM"></a>
<h2><hr> Formatting forms</h2>

<p>Forms should be set up to use the POST method:</p>

<blockquote>
  <tt>&lt;FORM METHOD="POST" ACTION="/cgi-bin/script.cgi"&gt;</tt>
</blockquote>

<p>where script is the name of the script.</p>

<p>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.</p>

<p>Other forms may take other actions. Contact the Technical Writers (<A
href="mailto:ct-techwriters@colltech.com">ct-techwriters@colltech.com</a>)
for assistance in formatting forms.</p>

<a name="TABL"></a>
<h2><hr> Working with tables</h2>

<p>Tables are used to provide formatted data and to show menus or
lists.</p>

<a name="FMTG"></a>
<H3>Formatting tables in html</H3>

<p>We strongly recommend that the following system be used:</p>

<ul>
  <li>Align the table and /table tags with each other, indented 2 spaces
    from the blockquote<br><br></li>
  <li>The table tag should include the border=2 option when borders
    are desired<br><br></li>
  <li>Indent the row delimiters-TR and /TR-two spaces from the table
    block.<br><br></li>
  <li>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.<br><br></li>
  <li>Each cell should be on its own line in the html source.<br><br></li>
  <li>Inside the last cell of each row, include a line break (BR) in
    case non-table-compliant browsers, such as lynx, are used.<br><br></li>
</ul>

<a name="AliG"></a>
<H3>Aligning tables</H3>

<p>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.</p>

<a name="WHIT"></a>
<H3>Using white space</H3>

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

<a name="CELL"></a>
<H4>Using white space by cells</H4>

<p>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.</p>

<a name="TBL9"></a>
<p><b>Table 9</b><br>
Table cell spacing rules</p>

<blockquote>
  <table border="2">
    <TR valign=top>
      <th>Table used for</th>
      <th AliGN=CENTER>cellpadding</th>
      <th AliGN=CENTER>cellspacing</th>
    </tr><TR valign=top>
      <td>List, annotated</td>
      <td AliGN=CENTER>3</td>
      <td AliGN=CENTER>5</td>
    </tr><TR valign=top>
      <td>List, non-annotated</td>
      <td AliGN=CENTER>3</td>
      <td AliGN=CENTER>3</td>
    </tr><TR valign=top>
      <td>Menu</td>
      <td AliGN=CENTER>2</td>
      <td AliGN=CENTER>2</td>
    </tr><TR valign=top>
      <td>Tabular data</td>
      <td AliGN=CENTER>2</td>
      <td AliGN=CENTER>2</td>
    </tr>
  </table>
</blockquote>

<a name="ROWS"></a>
<H4>Using white space by rows</H4>

<p>In tables used for lists there should be no border.  However, an
additional blank row (using the &nbsp; 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.</p>

<a name="HDRC"></a>
<H3>Formatting header cells</H3>

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

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

<p>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 (<tt>#000000</tt>) on gold (<TT>#eaaf00</TT>).  If multiple
levels of heading are required, use your best judgement for subsequent
heading color levels.</p>

<a name="DATA"></a>
<H3>Formatting data cells</H3>

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

<p>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.</p>

<a name="BORD"></a>
<H3>Using borders</H3>

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

<p>In tables used for simple menus or lists, there should be no
border.</p>

<p>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.</p>

<p>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.</p>

<a name="CAPT"></a>
<H3>Using captions</H3>

<p>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 &nbsp; 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.</p>

<p>An example can be found in <a href="#TBL9">Table 9</a>.</p>

<a name="CROS"></a>
<h2><hr> Using cross-references</h2>

<p>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.</p>

<p>Typically, we do something like the following to define a
reference:</p>

<blockquote><PRE>&lt;a name="reference"&gt;&lt;/A&gt;
&lt;h2&gt;&lt;hr&gt;&lt;img src=...&gt; Heading&lt;/h2&gt;</PRE></blockquote>

<p>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).</p>

<a name="liNK"></a>
<h2><hr> Using links</h2>

<p>We try to avoid the "Click here" type references; these are poor style. Rewrite the sentence instead. For example,</p>

<blockquote>
  <tt>&lt;a href="foo"&gt;Click here&lt;/A&gt; for information on foo.</tt>
</blockquote>

<p>could be rewritten much better as</p>

<blockquote>
  <tt>Additional &lt;a href="foo"&gt;information on foo&lt;/A&gt;
  is available.</tt>
</blockquote>

<hr>
<br><a href="index.shtml">
  <img src="/icons/buttons/toc.gif" alt="[Contents]" height="20" width="20">
  Jump to table of contents</a>

<br><a href="B.shtml">
  <img src="/icons/buttons/previous.gif" alt="[Back]" height="20" width="20">
  Back to Appendix B, "Corporate logo definition"</a>

<br><a href="D.shtml">
  <img src="/icons/buttons/next.gif" alt="[Next]" height="20" width="20">
  Onward to Appendix D, "Internet web site styles"</a>

<hr>
Copyright &copy; 2001 Joshua S. Simon.<br>
</body>
</html>