SBCWeb Network NMWeb Dev Network Management HTML Template

This document is a verbose explanation of the NMWeb styles. Information is available in the following areas: If you're new to web development, either The Beginner's Guide to HTML or the Mosaic Tutorial may be helpful.


Titles and the icon line

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.

The images are links. The first image should always be the SBC or SBC Warburg logo button, which is a link to the base SBCWeb. The next button for us is always going to be the Network Management logo, the three colored objects linked together, which should point back to the base page for NMWeb. Subsequent button images indicate the path back up the tree from where you are. For example, if you are in the Data, WAN, section, the icon path would be SBCWeb, Network, Data, WAN; this allows the user to see at a glance where s/he came from.

All but the last icon should contain an ALT= reference for those who do not have graphics-capable browsers (like lynx) or who have disabled inline images to speed up access. The last icon, which indicates the current page, is the only one that is not a link to another document.

All these buttons are on the 40x40 grid, based on the blank.gif button in /icons/buttons.

Some other information that may be handy is a text page on which 40x40 image buttons to use when and an HTML version with the buttons displayed for reference.


Paragraph style information

The Network Management Web Pages use the following styles.

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.

The last first-level (<H2>) header must be the Credits section with the wording as specified at the bottom of this page.

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.

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 does not have an 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.

Paragraphs

Typical <P> tag at the end of each body paragraph. Do not use the <P> tag or the <BR> tag for bullet lists or ordered lists, since the <LI> tag will do that for you.

Lists

There are two major kinds of lists: 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.

Notes, cautions, and warnings

These terms 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 <UL> tag block without using <LI> tags. Because of their importance, they must use the ALT= keyword to specify the type of notice. The terms are used as follows (examples shown):
Note 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.
Caution A caution highlights information necessary to avoid damage to the system
(software or hardware). Use the caution.gif button (alt="Caution") for
cautions.
Warning A warning highlights information necessary to avoid injury to personnel
(humans). Use the crossbones.gif button (alt="Warning") for warnings.
Note that previous icons of dynamite.gif and fire.gif are obsolete.
In documents-in-progress, especially those converted from the Chicago Network Management FrameMaker templates, 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 <UL> 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.)

Images

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

New text

A special image that indicates new text is available. New text should be flagged with the <IMG SRC="/icons/misc/new.gif" alt="New!"> tag, which gives the image below: It is strongly suggested that a comment be included, such as <!-- remove new tag, mmddyy-->, and the NMWeb New Tag Removal file (in references/newtag) be updated, so we know when to remove the tags.

Text flagged as new should only keep the New flag for two weeks. After two weeks or so, it's no longer new, is it?

Protected text

A special image that indicates that text is secured is available. password-protected or secured links should be flagged with the <IMG SRC="/icons/misc/secured.gif" alt="Secured"> tag. This gives the image below.

Technical details on Secured how NMWeb implements the Secured tag are available.

Forthcoming text

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 is <IMG SRC="/icons/misc/coming.gif" alt="Coming soon!"> and it looks like the image below.


Character style information

In the Network Management Web Pages, 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 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.


Sections

The HTML document, bounded by the <HTML> tag block, contains three sections:


Forms

Forms are set up to use the POST method:
<FORM METHOD="post" ACTION="http://nmweb/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 Network Management Web Team (<[...]>) for assistance.


Tables

Tables can be done in one of two ways. The first works in all browsers, the second works only in browsers that support the <TABLE> HTML tag.

<PRE>-format tables

The <PRE> tag instructs the user's browser that the text following is preformatted. Thus a preformatted table, with multiple spaces separating columns, is the easiest way to put tabular data on the Web.

An example <PRE>-format table is shown below.

<TABLE>-format tables

Only newer browsers support the <TABLE> tag. NMWeb styles do not use the <TABLE> tag yet because over a third of our users do not have access to <TABLE>-compliant browsers.

However, once Netscape 2.0e and OmniWeb 2.0 are rolled out into Production for SunOS, Windows and NEXTSTEP, the major browsers all support the <TABLE> tag and we will begin using it.

The same example as above in a <TABLE>-format table is shown below.

We strongly suggest that the following system be used:


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


Links

We should try to avoid the "Click here" type references; these are poor style. Rewrite the sentence instead. For example,
<A HREF="foo">Click here</A> for information on foo.
could be rewritten much better as
Additional <A HREF="foo">information on foo</A> is available.


Credits

Copyright © 2000 by Joshua S. Simon. All rights reserved.


Last update Apr24/02 by Josh Simon.