SDS is in constant development but I hope that things will consolidate more or less in the structure it is now. This document explains some of the basic architecture of SDS.

The path..

SDS currently consists of two important dataformats, CSF (Code Structure Format) and SDOC. Both formats are defined in XML to allow them to be used in/by as many systems and languages as possible. CSF is the core format, meant to represent useful information about code and it's structure. A CSF-file can be linked/merged with another CSF-file and produce one CSF-file which contains all the information in both formats. The linking/merging will allow information gotten from different compilations within the same project to be linked together, and even information from several projects can be linked together.

How the CSF-information is used will vary, but SDS provides the SDOC format if you want documentation from the CSF-file. A CSF->SDOC tool will extract the information necessary from CSF and combine it with e.g modularisation preferences, to produce a format meant to represent the documentation. The SDOC format doesn't look awfully pretty and is just a base format which needs to be presented in HTML, LaTeX, etc.

Quite simply we have the path: Code -> CSF -> SDOC -> Presentation

There's also a graphical representation of the csf flow.

Producing CSF

CSF is as said the core format, and if someone manages to produce CSF, they will be able to use all tools which uses CSF. This means that if language FOO can be translated into CSF you get all CSF-tools free, e.g documentation, traversable call-trees. Typical applications which can be made to produce CSF are compilers, homemade-parsers, graphical development-tools etc. The example application here is the Java parser from ANTLR which through the java2csf tool produces CSF

Using CSF

CSF contains all the basic information collected about methods, classes, comments, macros and so on. Many tools can be based on CSF, e.g call-tree traversers, tree-shakers. Be aware that CSF is in many ways a 'raw' format and may contain hundreds of entries which are absolutely uninteresting to some tools (e.g comments), while they might be used by other tools (/** */ comments are documentation in Java). CSF allows tools and programs to reason about programs and code without needing to create a custom parser for each and every language.

The SDOC Approach

CSF is a hardcore format for code, and is as such not directly useful as documentation. A CSF to SDOC translator should besides connecting e.g /** */ comments with appropriate objects to make documentation also allow for other levels of customization. One example is "modules" which we usually group our systems into. Code in itself does not know about modules, except maybe in the more primitive form of packages and namespaces found in some languages. A module can through the included csf2sdoc tool be defined by specific files, directories, special prefixes or classes. A module or a class may also have different parts or categories; a libc module may have a category of I/O functions and a class may have a category of get-functions and another with set-functions.

SDOC is basically presentation-independent and can be seen as an extraction of some CSF-info and the addition of modules and categories. Currently SDOC can only be presented in HTML but support for DocBook (ie TeX, HTML and Nroff) will be added.

For a better overview, see the graphical representation of the sdoc flow.

Directory structure

[Outdated]

The directory-structure in SDS currently looks like:

apis - API specifications
apps - applications
doc - documentation
include - various include-files for C/C++
intl - GNU Gettext library
po - language-translations
src
- clisp - Common Lisp code
- csf - csf-api
- emacs - lookup-function for documentation
- expat - xml-parser
- modspec - module-api
- prefs - prefs-api
- sdoc - sdoc-api
- tools - common library for c++
tests - tests I use
xml - mostly DTDs

The include-directory and the src-directory basically have the same structure.

Important Code Guidelines

Note: The various APIs used are generated from XML-specifications and if you wish to add a new language, add it in the API-generator (src/clisp/) to keep it sync'ed with the others.

The code in SDS follows guidelines which are liberal, I guess:

Modules (e.g XML, SDOC, CSF) should use a common prefix on classes, method, variables, etc. to make sure the correct code is called and make things more readable.
Code should be written in a style suitable for the language it is written in. In C++ it might make sense to call a class CSF_Method while in Lisp it would probably be called CSF-Method. Use your language's style and idioms.

C/C++ code should follow these extra guidelines because the languages look so messy:

All types should begin with an uppercase letter. All variables and functions should start with a lowercase letter.
Global functions and variables should be known in as little area as possible. Hidden header-files or using static helps. Use module-prefix where possible to avoid conflict.
C++ Source-files should have the extension .cpp and headerfiles have .H . For C use .c and .h