Guidelines for writing ServerAtSchool-documentation
Prev		Next

IV. Elements

1. Introduction

2. Allowed HTML elements

3. More constructs
3.1 How to identify special keys on the keyboard
3.2 How to emphasise large pieces of code

4. Other resources

1. Introduction

This chapter defines the list of allowable HTML-tags in ServerAtSchool documentation. Furtermore a few common constructs are discussed, such as the way to represent keys on a computer keyboard. There is also a section with links to additional resources.

(top)

2. Allowed HTML elements

Below is a list of allowable HTML elements.

A
ADDRESS
BIG
BLOCKQUOTE
BODY
BR
CAPTION
CITE
CODE
DD
DL
DT
EM
H1
H2
H3
H4
H5
H6
H7
HEAD
HR
HTML
IMG
LI
META
OL
P
PRE
SMALL
STRONG
SUB
SUP
TABLE
TD
TH
TITLE
TR
TT
UL

(top)

3. More constructs

3.1 How to identify special keys on the keyboard

Most of the time it is easy to instruct the reader to enter data into a data entry field, e.g.:

Enter the name 'John Doe' (without the single quotes) into the field.

However, when the user needs to submit the data by pressing the key on the keyboard labeled "Enter", it becomes complicated. The advice is to use the (English) name of the key between brackets [ and ]. You should use this markup to identify all keys on the keyboard that are not letters, digits or punctuation. This is an (incomplete) list:

[Esc]
[F1] ... [F12]
[PrintScreen]
[Scroll Lock]
[Pause]
[Backspace]
[Insert]
[Delete]
[Home]
[End]
[Page Up]
[Page Down]
[Num Lock]
[Tab]
[Caps Lock]
[Enter]
[Cursor Up]
[Cursor Left]
[Cursor Right]
[Cursor Down]
[Spacebar]
[Ctrl]
[Alt]
[Shift]

Another problem with keyboards is that sometimes a combination of keys is necessary. In these cases you should use the names of the keys in the combination, delimited with dashes and surrounded by the brackets. Here is a list of examples:

[Ctrl-Alt-Del]
[Shift-Tab]
[Alt-Pause]
[Alt-Print Screen]
[Ctrl-Cursor Left]
[Shift-Page Up]

If you really need to spell out specific sequences of keystrokes, you might want to wrap simple keys (letters, digits, punctuation) in brackets, too. Example:

[C] [D] [Spacebar] [/] [H] [O] [M] [E]

Note that this kind of identification might confuse the reader, especially when you use the construct [C] (i.e. the key labeled with the capital letter 'C') where you actually want the user to enter a lowercase letter 'C'. The user might think that she is supposed to enter the upper case letter 'C' (which would be identified with [Shift-C] if you think about it). In other words: don't overdo it with spelling out keystrokes.

3.2 How to emphasise large pieces of code

Sometimes it is necessary to emphasise large chunks of code. The advice is to use a gray'ish background for that purpose. The recommended way to do so is to have a 1 x 1 table with the BGCOLOR attribute in the TD element.

The code chunk begins with these HTML-codes.


<p>
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td bgcolor="#E0E0E0">
<code>
<pre>

After that, the code of interest follows, subsequently followed by the code below.


</pre>
</code>
</td>
</tr>
</table>
<p>

Note that the code chunk begins and ends with a P-tag. This is to separate the chunk from the running text.

(top)

4. Other resources

template.txt: This is the 'raw' template that can be used to create a new document according to the documentation guidelines.
http://www.december.com/html/4/element: This is a very handy overview of various HTML 4 elements, including useful examples. Recommended.
http://validator.w3c.org: This is the W3C Validator, a tool for on-line validation of HTML-code.

(top)

Prev	Home	Next
III. Template explanation		Appendix A. GNU Free Documentation License

Author: Peter Fokker <peter (at) berestijn.nl>

$Id: elements.html,v 1.6 2006/04/05 14:36:15 peter Exp $

IV. Elements

Contents

1. Introduction

2. Allowed HTML elements

3. More constructs

3.1 How to identify special keys on the keyboard

3.2 How to emphasise large pieces of code

4. Other resources