Project Guidelines

Dag-Erling Smørgrav

January 19th, 2002

Table of Contents

1. Introduction

2. General guidelines

2.1. English style
2.2. XML style

3. Source code

3.1. Language
3.2. Coding style

4. Internal documentation

5. External documentation

6. Project web site

Bibliography

1. Introduction

This article describes the Convention Database project's guidelines and standards for source code and documentation.

This document is a work in progress!

2. General guidelines

2.1. English style

Do not use contractions.
Except for acronyms, avoid abbreviations, especially latin ones: use “such as” or “for instance” instead of “e.g.”, “that is” instead of “i.e.”, “and so forth” or “and so on” instead of “etc.” or “et al.”, and so forth.
When a sentence ends in a right parenthesis or quotation mark, place the punctuation mark before the closing parenthesis or quotation mark (not after.)

All human-written XML documents shall be encoded in ISO-8859-1 and have complete XML and document-type declarations. If the document uses untypable characters (such as © or —), the corresponding XHTML entities should be imported into the document as shown below:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML
V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" [
  <!ENTITY % HTMLlat1
    PUBLIC "-//W3C//ENTITIES Latin 1 for XHTML//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent">
  %HTMLlat1;
  <!ENTITY % HTMLspecial
    PUBLIC "-//W3C//ENTITIES Special for XHTML//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent">
  %HTMLspecial;
  <!ENTITY % HTMLsymbol
    PUBLIC "-//W3C//ENTITIES Symbols for XHTML//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent">
  %HTMLsymbol;
]>

Note that long tags are wrapped, and the continuation lines are intented two spaces to the right of the opening angle bracket.

The header shall be followed by an XML comment including a copyright declaration and the RCS Id string:

<!--
   - Copyright (c) 2002 The Glasgow Worldcon 2005.  All rights reserved.
   -
   - $Id$
  -->

Element and attribute names shall be written in lower-case. Elements shall begin one line below and two spaces to the right of their parent element. Elements that contain text nodes (other than ignorable whitespace) shall be block-formatted, with the fill column set to 70. Important logical blocks such as sections, paragraphs and list items shall be separated from their siblings by a single blank line.

<article>
  <articleinfo>
    <author>
      <firstname>Dag-Erling</firstname>
      <surname>Smørgrav</surname>
    </author>
    <authorinitials>des</authorinitials>
    <pubdate>January 19th, 2002</pubdate>
    <title>Sample Article</title>
    <copyright>
      <year>2002</year>
      <holder>The Glasgow Worldcon 2005</holder>
    </copyright>
  </articleinfo>

  <section id="section">
    <title id="section.title">A section</title>

    <para>A paragraph.</para>

    <para>Another paragraph with a link to <link
      linkend="othersection"
endterm="othersection.title"/>.</para>
  </section>

  <section id="othersection">
    <title id="othersection.title">Another
section</title>

    <para>Lorem ipsum dolor sit amet, consectetuer adipiscing elit,
      sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna
      aliquam erat volutpat.</para>
  </section>
</article>

Machine-generated XML documents that are intended for web publication shall follow the same rules as human-written documents. Other machine-generated XML documents shall be encoded in UTF-8, and contain as little whitespace as possible in order to conserve memory, storage space and bandwidth.

4. Internal documentation

The source code for all deployed systems shall be fully annotated with Javadoc comments conforming to the conventions outlined in [Javadoc].

5. External documentation

External documentation (whitepapers, manuals and the like) is maintained in a separate doc directory in the CVS tree. All external documentation shall be written in DocBook XSL (DTD version 4.1.2 or newer, stylesheet version 1.48 or newer).

Efforts shall be made to avoid deprecated constructs such as <artheader> (use <articleinfo> ) and <sectN> (use <section> .)

The authoritative DocBook reference is [Walsh1999], which is also available online [DocBook].

6. Project web site

The project's web pages are maintained in a separate www directory in the CVS tree. All HTML documents must be valid XHTML 1.0 Transitional.

Online documentation

Books

Project Guidelines

Dag-Erling Smørgrav

1. Introduction

2. General guidelines

2.1. English style

2.2. XML style

3. Source code

3.1. Language

3.2. Coding style

4. Internal documentation

5. External documentation

6. Project web site

Bibliography