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:
- 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, taking the
place of the StepNum and StepNum+ paragraph tags from
the FrameMaker document template. You must be very careful when
converting FrameMaker step lists into html ordered lists because every
time you use the <ol> tag you restart the numbering at 1.
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):
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.
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:
- In-line images--In-line images, or the buttons, should
only be used (a) in the icon bar at the top of the html page, and
(b) in first-level headers (<h2> tag blocks). These should
always be 40x40 buttons as discussed above. 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
(as the [...] page does). 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.
- Graphics--These should be used for screen images or examples,
and should be used sparingly. Remember that not all WWW browsers are
graphics-compliant or have graphics enabled, so all graphics-type images
should include the alt= keyword.
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
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:
- <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.
The last major section (<h2> tags) should be the Credits section.
- <address>--The address or contact information, using
an <hr> rule, the last modification date, and an <A
href="mailto:"> link to the author (typically nmweb).
SBCWeb uses the Address field last update information on searches, so
please include it on all NMWeb pages.
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.
-----------------
# of
Month tickets
-----------------
January 95
February 68
March 117
-----------------
<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.
| Month |
# of
tickets
|
| January |
95
|
| February |
68
|
| March |
117
|
We strongly suggest that the following system be used:
- Use <table> and </table> as left-aligned tags.
- The <table> tag should include the border="2" option.
- Indent the row delimiters--<TR> and </TR>--two spaces.
- Within each row, indent the cell delimiters--<TH> and </TH>
for header rows, <td> and </td> for data rows--two spaces.
- Inside the last cell of each row, include a line break (<BR>) tag
in case non-<table>-compliant browsers are still 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.
