Narrabri HTML Documentation - Style Conventions

Document template

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>

<HEAD>
  <META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <TITLE>Title of document</TITLE>
  <LINK rel="stylesheet" type="text/css" href="/stylesheets/ca_style.css">
</HEAD>

<BODY>
  <!--#include virtual="/includefiles/ca_header.html" -->

  <CENTER>
    <H1>Title of document</H1>
  </CENTER>

    Text that goes into document...

  <P>
  <HR>
  <ADDRESS>
    Original: Firstname Lastname (20-Jan-2004)<BR>
    Modified: Firstname Lastname (23-Jan-2004)
  </ADDRESS>

  <!--#include virtual="/includefiles/ca_footer.html" -->
</BODY>

</HTML>

Title

The title should preferably be less than 64 characters long and be meaningful in the absence of the rest of the document (as these must stand alone when placed in history lists etc.).

Example:: <TITLE> Introduction </TITLE> would not be appropriate, as it gives little indication of what the document is about.; <TITLE> ATCA Application Software - Introduction <TITLE> would be useful if found on its own.

Address

This section contains the name of the author of the original document and that of the last person to modify the file, together with creation and modification dates.

Include-files and stylesheets

The  and  statements include the proper header and footer as the page is displayed in a browser. If the header and footer are not displayed properly, reset the file permisssions by typing chmod u+x filename.html.

Please note that the Narrabri and Mopra webpages use different headers, footers, and stylesheets (replace 'ca' with 'mopra').

HTML tags - case convention

Tags should be in upper case, for ease of identification.

Line format

Indentation

Indentation of two spaces should be used wherever nesting of tags is required.

An exception to this is in the use of the preformatting element (<PRE> and </PRE>) where indentation should reflect the format of the desired screen output.

A general formula for indentation is as follows:

     <TAG_1> Some text here
       <TAG_2> More text
       <LIST_1>
         <ELMT_1> Element 1 of list 1
         <ELMT_2> Element 2 of list 1
       </LIST_1>
       </TAG_2>
     </TAG_1>

Example 1:

<A HREF="/observing/observing.html"> 
  <IMG align=middle SRC="/icons/ca_ant.gif">
  Observing with the ATCA
</A>

This is displayed as:

Observing with the ATCA

Example 2:

<UL>
  <LI> A MAPS alarm will autodial a set list until a response is made.
  <LI> The responding party will enter a 5 digit code number, which
    will halt the auto dialler. The responding party must then deal
    with the alarm.
  <LI> The list sequence is as follows:
  <UL>
    <LI> <STRONG> John Whiteoak </STRONG> - (home no)
      - this number is dialled as an information alert only and 
      usually no response is made;
    <LI> <STRONG>Mobile telephone</STRONG> - will be located 
      with the Rostered On-call staff member. During normal 
      working hours the mobile telephone won't respond. Between
      4.00pm and arriving home and likewise in the morning coming
      to work, the mobile telephone should be activated and in
      standby mode;
    <LI> <STRONG> 4031 </STRONG> - Dedicated Extension No. <BR>
      <STRONG> Business Hours - 8.00am - 4.00pm </STRONG> - 
      diverted to Narrabri switchboard; <BR>
      <STRONG> After Hours - 4.00pm - 8.00am  </STRONG> -
      diverted to On-call staff member's home phone no.;
    <LI> <STRONG> Ron Beresford </STRONG> - (home no);
    <LI> <STRONG> Antenna Lab </STRONG>.
    <LI> (Dave McConnell  may be added to the list at a later date.)
  </UL>
</UL>

This is displayed as follows:

A MAPS alarm will autodial a set list until a response is made.
The responding party will enter a 5 digit code number, which will halt the auto dialler. The responding party must then deal with the alarm.
The list sequence is as follows:
- John Whiteoak - (home no) - this number is dialled as an information alert only and usually no response is made;
- Mobile telephone - will be located with the Rostered On-call staff member. During normal working hours the mobile telephone won't respond. Between 4.00pm and arriving home and likewise in the morning coming to work, the mobile telephone should be activated and in standby mode;
- 4031 - Dedicated Extension No.
  Business Hours - 8.00am - 4.00pm - diverted to Narrabri switchboard;
  After Hours - 4.00pm - 8.00am - diverted to On-call staff member's home phone no.;
- Ron Beresford - (home no);
- Antenna Lab .
- (Dave McConnell may be added to the list at a later date.)

Comments

Comments are created by surrounding every line of the text in question with the tags .

Unfortunately, some browsers (namely Mosaic) will process tags found within comments, hence terminating the comment early, so these may not be used for commenting out HTML code.

A second restriction when commenting is that the sequence "--" may not appear inside a comment, except as part of the closing tag.

Example:: The following line is a comment, hence invisible via a browser.

Tabs

These should be avoided, especially in preformatted text (<PRE> and </PRE>). Use spaces instead.

Images

Inlined images may only be in GIF or Xbitmap format, that is, with extension .gif, .xbm, or .xpm.

If using inlined images, always include alternative text, by means of the ALT argument of the IMG element. This is useful for character cell browsers which have no means of displaying the image and situations where the Delay Image Loading capability of an X-Windows browser is enabled.

Example:

<IMG SRC="earth.gif" ALIGN=TOP 
    ALT="Terrestrial Globe - View of Oceania">

This is displayed as

Terrestrial Globe - View of Oceania

If you need icons for your page, please look for examples in the icons directory and feel free to place your icons there.

Links To Other Documents

When referring to something which is documented elsewhere, it's a good idea to create a link to it, as this will unite our documentation in a logical way, and make the task of finding a particular piece of information easier for our users.

If possible, this link should be via a relative URL, rather than one specifying the full path. These are more convenient, and decrease the chance of an error if directory trees are relocated.

Multipage Documents

In the case of multipage documents with a logical sequence, a Table of Contents/Next/Previous link at the top & bottom of each document will create a smooth transition between one file and the next.

Example:: [Up] [Previous] [Next]

Emphasized Text

Characters may be emphasized (italic, bold, etc.) in two ways:

Logically: By a description of the text that is to be highlighted, for example, code or keyboard entry.
Physically: By specifying the style in which to display the text, such as bold, underline, etc.

It is strongly recommended that we use logical styles, as the way in which a physical style is represented is locally defined, and hence is liable to change between one site and the next.
More importantly, some browsers are not capable of displaying all of the physical styles (NCSA Mosaic does not support underlined text, for example.) The currently used logical styles and their use are as follows:

<DFN>: For a word being defined.
Typically displayed in italics.
: For emphasis.
Typically displayed in italics.
<CITE>: For titles of books, journals, etc.
Typically displayed in italics.
<CODE>: For snippets of computer code. The "programmer's voice". Displayed in a fixed-width font.
<KBD>: For user keyboard entry, filenames, shell commands, etc. The "user's voice". Should be displayed in a bold fixed-width font, but many browsers render it in the plain fixed-width font.
<SAMP>: For computer response (status messages, etc.). The "computer's voice" Displayed in a fixed-width font.
: For strong emphasis.
Typically displayed in bold.
<VAR>: For a ``metasyntactic'' variable, where the user is to replace the variable with a specific instance. Typically displayed in italics.

Reserved Characters

The following symbols should not be used as text in an HTML document, as they will be processed by the browser. To include these use the form &code; below:

&code;	Wanted symbol
<	< (less than sign)
>	> (greater than sign)
&	& (The ampersand sign itself)
"	" (double quote)
	(A non-breaking space)

New Line Tags

Explicit elements to indicate a new line are not generally needed, as the browser will line wrap and format the text to suit the width of the window to which it is plotting. Nevertheless, these are sometimes necessary, and HTML has provided three text separators for this purpose.

- The paragraph separator will insert a blank line in the text.
- Paragraph marks are not generally needed around headings, lists, address or blockquote elements, as these have spacings already defined.
- Paragraph markers should be placed, on their own, at the beginning of the line. This will help to break the source up in a similar way to the output.
- The line break separator.
- These should be used singly. If more than one are required, use instead.
<HR>
- The hard rule plots a horizontal line across the page.
- These should also be placed, on their own, at the beginning of the line.

Original: Nuria McKay (21-Mar-1995)
Modified: Eva Boralv (13-Jan-2004)