About MMBase Documentation

Author: Michiel Meeuwissen
Date: 2002-12-05

This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.

The license (Mozilla version 1.0) can be read at the MMBase site. See http://www.mmbase.org/license

Table of Contents

1. Introduction
2. Docbook
3. Docbook editors

1. Introduction

This document will describe in what way MMBase is documented, and how you can contribute to updating or adding to the MMBase documentation. But first have a look at the overview of available MMBase documentation and how it is organized. The documentation is mainly written for different target groups. Documents of one target group may be important for other target groups as well. For instance, backend and frontend developers will have also have to be familiar with the documents on builders and applications.

There are several sources of documentation and information available. First there is the MMBase website (www.mmbase.org), which does supply knowledge and examples. The examples and HTML documentation which are shipped with an MMBase distro are available in the MMBase CVS source repository. The examples pages are in the html/mmexamples module, so new examples must be added there.

Formal documentation is available in the `docbook' XML format in the `documentation' modules of the CVS repository.

Some older documentation, which was not yet converted or rewritten to the docbook format is available in html/mmdocs of CVS.

2. Docbook

Documentation is set up in articles. An article needs an articleinfo object that describes the content. Article info should contain :

A title. you do not need to specify the title in article if you specify it in articleinfo. (it's not wrong but it's not needed either)
A date. The International Standard ISO 8601 specifies numeric representations of date and times is used. So a date is written as 2003-07-28.If only the month or even only the year is of interest: 2003-02 or 2003.
An edition tag with a Id: content, for versioning of the data.
An author group, with the authors. You can add an affiliation (organization) and your own name. Please do not add editors, links, or other stuff, as it will all be displayed in the documentation header and that may be a bit overkill (maybe we have to override the docbook xsl).

the following legalnotice:

					
<legalnotice>
	<para>
		This software is OSI Certified Open Source Software. OSI
		Certified is a certification mark of the Open Source Initiative.
	</para>
	<para>
		The license (Mozilla version 1.0) can be read at the MMBase
		site. See
		<ulink url="http://www.mmbase.org/license">http://www.mmbase.org/license</ulink>
	</para>
</legalnotice>

Use section, do not use sect1, sect2... And, if possible, use CDATA sections in your <programlisting>. This makes it easier to read when editing. CDATA sections look like this:

<programlisting format="linespecific"><![CDATA[

	<sample code>

]]></programlisting>

Although it is only a minor issue: the documentation preferably is written in U.S. English.

3. Docbook editors

Several docbook-editors are available. A number of editors used by the MMbase documentation team:

Jedit
Jedit is a Java-based text editor that uses colorcoding to ease editing of source code, such as java code, xml/html, and css. It provides a number of useful macros and plugins, including xml validation, tag completion, and xml auto-formatting.
Has some issues: it is a bit slow and occasionally freezes up, but it provides auto-save facilities and can recover after a crash. A good color-coded editor that works on all java-supporting platforms
see: http://www.jedit.org

Emacs
A multi-platform open-source editor that provides several handholds for editing. It has an XML-mode with tag- and attribute completion, which makes creating valid Docbook documents easy.
see: http://www.gnu.org/software/emacs/
see: http://www.xemacs.org/

XXE
A Java tool that allows you to edit xml files (only), specifically docbook xmls. It provides ways to associate a stylesheet with a xml so it can render a pleasing presentation of the docbook while you edit it.
With version 2.2 XXE solved the problems with handling or allowing edit of CDATA sections. XXE 2.2 generates nice formatted xml, which makes the results easy to read in other editors. XXE is able to convert XML files to html, RTF, Postcript and PDF. For non/semi-technical users XXE is found to be a very good choice to edit docbook documents!
see: http://www.xmlmind.com/xmleditor/