7. The format of the the document body
7.1 The table of contents
A 'clean' version of the template can be found in the file template.txt. This file can be used to start a new chapter from scratch.
There are also some guidelines for the format of the document body. These are discussed in the paragraph 7. The format of the the document body below.
|
You can see that the document uses a strict HTML 4.01 document type with the iso-8859-1 characterset. Nothing spectaculair. Note that the header contains a meta-tag which prevents certain browsers to autonomously add links to the text in the name of user-friendlyness. We really don't need that. Note that the header contains a string %%TITLE%%. This is a placeholder for the chapter title. This is the text that will be displayed in the browser's title bar. These 'template variables' are further explained in the section 6. Template variables below.
NOTICE:
It is very convenient to add a single word or acronym to the
TITLE-tag identifying the book. In this document that
would be the word 'Guidelines'. The title of this chapter in the
TITLE-tag is: 'Guidelines - III. Template
explanation'. This way the word 'Guidelines' shows up in the
title bar of the browser window. You can separate the chapter title
and the book title with a dash.
|
The navigation bar starts with the centered title of the book. This is not the title of the chapter. This navigation bar also has clickable links on the lefthand side and the righthand side which lead to the previous and the next chapter respectively. If there is no previous or next chapter, there is no clickable link and no text 'Prev' or 'Next'. Please refer to section 6. Template variables below for an explanation of the variables %%BOOKTITLE%%, %%HREFPREV%% and %%HREFNEXT%%.
Please note that the links also have the attribute
accesskey. This allows for a so-called hotkey to
follow the link by clicking a particular key combination on the
keyboard. Often this is a key-combination, e.g. the letter
P or N (as we use here) in combination with
the Alt-key.
|
This navigation footer looks very much like the navigation header. The
same strategy is used for clickable links to the previous and the next
chapter in the book. Note, however, that there is also a link labeled
'Home'. Clicking this link (or using the accesskey Alt-H)
navigates to the table of contents of the book. This table of contents
is used as the starting point for accessing the book. It is handy to
have a link in every chapter that brings you back to the table of
contents.
Note that the links not only have the labels 'Prev' and 'Next' but that the titles of the chapters are also shown. This makes it easier to navigate through the book. The titles of the previous and next chapters should be consistent. That is: %%TITLE%% in the file 'previous.html' should be identical to %%TITLEPREV%% in this document.
|
Note that the author's name and email address are placed here, in the
ADDRESS-tag. Also the date of last modification is placed
in the document footer. Preferably this date follows the ISO date
format but it is allowed to use a special code like
$Date$ for use with
CVS.
previous.html.
index.html.
next.html.
previous.html.
next.html.
A-tag with
href="mailto:..."); a simple plain-text address is OK
as long as it is obvious where the author can be reached. You may want
to try and make it harder to harvest the e-mail address by constructs
like author (at) example (dot) com.
$Date$ for use with CVS.
H1-tag.
|
Note that this title has a name. This name, top, is used
to jump to from a link at the end of every section. After this title
there is always a section with the table of contents for this
chapter. This is done via a section-title in an H2-tag.
|
Note that it is allowable to link to sub-sections too. We use the crude way of adding two non-breakable spaces to indent the link in the table of contents. This may sound old fashioned but it does render properly in text-oriented browsers like Lynx.
The contents section is always followed by a section called "Introduction".
|
Note that this section too, has a name (here: "h1"). This is the name that is linked to from the table of contents. This section summarises the contents of the chapter. As with all other sections (excluding the table of contents) the section ends with a clickable link which allows the user to jump to the top of the document.
|
Note that the link is positioned in the right hand side of the page. This is considered less disturbing than when this link would be flush left.
Author: Peter Fokker <peter (at) berestijn.nl> $Id: template.html,v 1.6 2006/04/05 14:36:15 peter Exp $