General Links
SDS Homepage
General Documentation
Main index
Copyright notices
What is SDS
Installing SDS
Using SDS
Language frontends
Plans/further releases
Developer Documentation
Architecture description
Developer How-To
XML-system for classes
CSF Specification
CSF DTD Documentation
Develop code in Lisp
Email page maintainer
Hosted at

SF project page


SDOC Information

Table of Contents:

  1. The SDOC XML Format
  2. Converting CSF to SDOC
  3. ModSpec Examples

1. The SDOC XML Format

SDOC has just recently been revised due to the revision of CSF. SDOC is the documentation format of SDS, and more or less use the same mechanisms as CSF, but adds a few other constructs specific for documentation. "SDOC modules" are specified by the ModSpec format which currently only is documented by an example. SDOC-tools also adhere to preferences specified in a preference-file.

Please Note: A csf2sdoc tool is allowed to add values to info-fields which most CSF-tools might not understand.

New/changed/removed constructs

SDOC is basically like CSF, except that it adds two constructs; the module and the category. The module is a documentation construct which allows one to group other constructs into modules based on various criterias. The modules are defined in a specific xml-format; ModSpec;, and then CSF-data is translated into SDOC-modules using those specifications. The category construct allows one to split up classes and modules into different parts for presentation. Categories are also specified with ModSpec.

SDOC basically copies the raw CSF-data into new locations in SDOC but doesn't use all parts with the same vigour. SDOC also adds a new field to most constructs, the doc-field which basically serves the same purpose as the info-field but contains documentation.

<doc type=doc_type>
   <text>... text ...</text>

One important part is removed from CSF; comments. These are if applicable, translated into documentation (the doc elements).

2. Converting CSF to SDOC

This is usually an unproblematic job. Check the csf2sdoc tool and it's command-line options. However, it does work in a certain manner which might be interesting to know about.

Documentation from Source Code

If your front-end is much to brag about, it also gets you the comments in the source code and places them in the CSF-file. csf2sdoc will filter out all comments and if the text begins with an asterisk '*' (at least for C++ and Java) it will try to find the construct it belongs to and add the info to the appropriate DOC-field. Ordinary comments are removed.

Documentation from INFO-fields

Some languages are constructed more intelligently than others and contain documentation as part of the constructs. These should be placed in appropriate INFO-fields which the converter will move to appropriate DOC-fields for the SDOC-format.

Documentation from ModSpec

When arranging modules and categories with the ModSpec format, one can add several info-fields. These should be moved to appropriate DOC-fields during conversion. No rules are made here yet, though.

Documentation Keywords

More info on documentation-keywords will be added later. Some keywords will have side-effects, like creating a category.

Keywords that probably will be supported:

  • approval - who has approved the object in question
  • author - who has written the object in question
  • desc - the usual description
  • dstruct - describes a data-structure
  • equiv - an "equivalent to"-field
  • memo - see oneline
  • oneline - a one-line description, e.g for index
  • param - for docs about parameters
  • remark - caveats and helpful remarks
  • returns - for functions; description of the return value
  • seealso - a link-simplifier which links to other objects
  • sketch - a sketch of a function or class or construct
  • space - estimate on space use, complexity, etc
  • time - estimate of time use, complexity, etc
  • version - information about the version of the object

3. ModSpec examples

SDS does also support C and allows one to document C-like modules. It's highly configurable and support three ways to find an object's module and category. It is best explained with an example, here with modules.xml:

<?xml version="1.0"?>
<!DOCTYPE modules SYSTEM "modules.dtd">

<!-- Example of a module for a whole directory (recursive) -->
  <module name="libc" fullname="GNU C-Library">
    <info type="memo" value="The important c-library"/>
    <info type="desc" value="Don't leave home without this library"/>
    <info type="version" value="2.0.7"/>
    <info type="organisation" value="FSF"/>
    <category name="Stdio">
      <desc> This is stdio...</desc>

(.. snip categories.. see modules.xml ..)        
    <category name="C++">
      <desc> This is GNU C++ </desc>

<!-- Two familiar examples for gtk/gdk programmers which use prefix. -->
<module name="GTK">

<module name="GDK">

<!-- Example of module with specified files -->
<module name="Hummingbird">


This is hopefully understandable, a module is defined over a scope (and first come is first served) and the categories (or modules within) defines their scope with respect to the scope of their parent. Hopefully directory, filename and prefix should be enough for most code.