Documentation format

[Pierre van Rooden]

I recently updated the docbooks in MMBase, trying to make them more uniform.
A such I want to note a few things to take into account with docbook documentation for MMbase:

Documentation is set up in articles.
An artcile 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. let's use one format for dates. The current format in most documentation is of the type '5 december 2002'.
- an edition tag with a $Id$ content, for versioning of the data.
- an author group, with the authors. You can add an affiliation (organisation) 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 eb a bit overkill (maybe we have to change 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, not 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>


I think we are making some progress with the documentation.
Ofcourse, we can do with your help, so if you have some docs, let us know!

--
Pierre van Rooden
Mediapark, C 107 tel. +31 (0)35 6772815
"Never summon anything bigger than your head."