Coding conventions

Formatting

The following list gives some hints on the coding conventions used throughout the source.

• Statement keywords have one space after them, and no space between the parentheses and the enclosed expression:

  if (foo) /* good */ if( foo ) /* bad */

• In general there is never a space after an open parenthesis or before a close parenthesis:

  foo(arg) /* good */ foo( arg ) /* bad */

• Expressions broken over more than one line are aligned LISP style:

  if ((a && b) || (c && d))

• else is on a separate line from the preceding brace:

  if (foo) { } else if (bar) { } else { }

• case clauses without a break always have a "fall through" comment where the break would occur:

  switch (foo) case x: /* do something here */ // fall through case y: }

• A statement governed by if or else that is longer than a single line always is surrounded by {}. The following is unacceptable:

  else if (foo) ; else ;

• Long function headers should not be broken before the parenthesis that starts the argument list.

Headers

Every header file should be surrounded by an ifndef. Here is a skeleton for a header file named filename.h:

/* copyright notice goes here */

#ifndef filename_INCLUDED
#define filename_INCLUDED 1

/* contents go here */

#endif /* not filename_INCLUDED */
      

Namespaces

Every file should be surrounded by a namespace. Namespaces are never used directly in order to support compilers which don't understand namespaces. The general skeleton for a .cxx file in the namespace NAMESPACE is:

/* includes go here */

#ifdef NAMESPACE
namespace NAMESPACE {
#endif

/* content goes here */

#ifdef NAMESPACE
}
#endif

Files in the lib/, nsgmls/, sgmlnorm/, spam/, spent/, spgrove/ and sx/ directories use the namespace SP_NAMESPACE. Files in grove/ use the namespace GROVE_NAMESPACE. Files in style/ and jade/ use DSSSL_NAMESPACE.

DSSSL_NAMESPACE imports everything from SP_NAMESPACE and GROVE_NAMESPACE (see style/dsssl_ns.h).

VC 5 and 6 have bugs in the namespace management, which mean that all these 3 need to be defined to be the same.

The conditional stuff is to deal with compilers that don't support namespaces.

Templates

To cope with different compilers capabilities with respect to templates, all template instantiations are collected in files with names ending in _inst.cxx. These are generated from _inst.m4 files.

To add a new template instantiation, add a macro call of the form

__instantiate(/* your template instatiation */)

to the appropriate .m4 file.

API definitions

When building DLLs on Windows, every class or function which should be exported by the DLL has to be prefixed with

__declspec(dllexport)

when building the DLL and with

__declspec(dllimport)

when using it outside the DLL.

This is hidden behind the _API macros which get defined appropriately. Every declaration of a class of function which is part of the public interface of its library should be prefixed with the proper _API macro. Files in lib/ and include/ use SP_API, files in grove/ use GROVE_API, files in spgrove/ use SPGROVE_API, files in style/ use STYLE_API.

Messages

Messages for the main classes are collected in separate classes. Eg there is a class InterpreterMessages for all messages of the class Interpreter.

The sources (.h and .cxx files and, on Windows, .rc files) for the <class>Messages classes are generated from .msg files by the msggen.pl Perl script.

Adding a new message amounts to adding one line to the correct .msg file. The lines in these files have the following format:

<message type><args>+<identifier>+<relevant clause>+<message text>

<message type> must be one of the I, W, Q, X or E. These stand for info, warning, quantity error, idref error and error, respectively.

<args> is the number of placeholders of the form %n in the <message text>.

<identifier> is the C++-identifier used to refer to the message.

<relevant clause> is used in SP to give an exact reference to the SGML standard for each error message. Outside of SP, this field is usually left empty.

<message text> is the text of the message. It can contain placeholders of the form %n where n is a number between 0 and <args> - 1. These placeholders will be replaced by suitable arguments if the message is issued.

Message arguments come from classes derived from MessageArg. StringMessageArg is a string, NumberMessageArg is an unsigned long.

There is a special form of message which also gives a location for the error which can be defined by adding one more field of the form +<aux text> at the end of message definition. <aux text> will usually be an explanation of the location like "first definition was here" (for a duplicate definition error). This form of message is only implemented for <args>≤1.

Issuing a message is done by a call of the form message(<class>Messages::<identifier>, ...) where <class> is the class to which the message belongs and <identifier> is the identifier used in the message definition. The remaining arguments to the message() call must match the %n placeholders in the message. For messages which give location information, the last argument must be an object of type Location.