Preface

Author: $Author: maroy $
Version: $Revision: 1.1 $
Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/htmlFileConventions.html,v $

Scope

This document describes the HTML file conventions for the LiveSupport project. See also the generic description of the file conventions in the LiveSupport project.

Introduction

HTML pages written as part of the LiveSupport documentation should conform to either the HTML 4.01 Transitional or XHTML 1.0 Transitional specifications.

Naming

HTML document files are named by the following rules:

there are no spaces in the file name
the file name begins with a lower case letter
for file names containing multiple words, each additional word begins with a capital letter
the extension of the file is .html (not .htm)

For example, a file with a single-word name may be named like: single.html, whereas a file with multiple word name would be like: multipleWordNameFile.html.

Structure

Each HTML file is partitioned by using the <h1> element to mark the start and name of each partition. The file has the following mandatory structure:

Preface
Scope
Introduction?
Additional sections+

HTML header

The HTML header of the document should describe the title and author of the document. The following HTML code should be inside the <head> element for the HTML page:

    <title>The title of the file</title>
    <meta name="author" content="$Author: maroy $"/>

The Preface section

This section holds the following specific text:

This document is part of the LiveSupport project, Copyright © 2004 Media Development Loan Fund, under the GNU GPL.

Author: $Author: maroy $

Version: $Revision: 1.1 $

Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/htmlFileConventions.html,v $

The Scope section

This section describes the scope of the document in short form. This details the areas which the document covers, and sometimes holds references to related documents.

The Introductions section

This optional section introduces the topic of the document to the reader.

Additional sections

These section hold the real content of the document, with freely named sections and sub-sections. The normal HTML heading elements (<h1>, <h2>, ...) should be used to mark and group the sections. Sample source code included in the HTML document should be put inside a <pre><code>...</code></pre> block, like the following:

    // some sample code here
    int i = 1;

Template

See a generic template for HTML documents. You may freely copy this template when starting to create a new document.