html Style Guide
html Style GuideThis document is a verbose explanation of the styles used in these web pages. 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 lineThe 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 that indicate the path back up the tree from where you are.
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.
Paragraph style informationThese pages use the following styles.
<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.
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.
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.
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.
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 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 should be used sparingly. There are two types of images to consider:
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-->.
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?
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 we implement the Secured tag are available.
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 informationIn 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.
SectionsThe html document, bounded by the <html> tag block, contains three sections:
FormsForms 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 IT department for assistance.
TablesTables 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.
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 simple tabular data on the Web.
An example <PRE>-format table is shown below.
-----------------
# of
Month tickets
-----------------
January 95
February 68
March 117
-----------------
For complex data and more controlled formatting, use the <table> tag. The same example as above in a <table>-format table is shown below.
Month # of
ticketsJanuary 95 February 68 March 117
We strongly suggest that the following system be used:
Cross-referencesCross-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).
LinksWe 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.