The Source Documentation System

version: 3.1
date: 1997/04/10

Introduction

This program helps you to document your programms. It supports you when you create or add documentation and produces good looking (printable) output.

You add documentation information to your sources (currently C, C++, Java, Tcl, Perl and Pod) using pod (Plain Old Documentation), the documentation format also used in perl. The documentation options provided by pod are simple and easy to learn but powerful enough to create nice and good looking documents.

sdoc uses this information to create a pod-document which in turn may be transformed to HTML, LaTeX, Postscript, nroff or just plain text.

The preview function of sdoc lets you create documentation interactively - add or modify your documentation to the source file and check the output for correctness.

Documentation Overview

sdoc cannot write the documentation for you but it makes the task a little bit easier. As programmers generally don't like to write documentation a good documentation system has to provide benefits to the programmer. It should be easy to learn and use but should also create nice and good looking documents. Indexes should be added automatically and the programmers should be able to easily check and modify the documentation.

Most important of all is that documentatation and source are not contained in seperate files. The documentation should be as close to the source as possible. Most of the time it is sufficient to document procedures and their arguments, not the internal code. Therefore the documentation should be put near the procedure header and it should document the usage of the procedure.

The Documentation Format

Without additional special effects (eg boldface, list constructs, references) one cannot create an effective, good looking documentation. Therefore we need a simple formatting language like TeX or nroff. Both of these languages offer too many features, as does HTML. A better suited choice is the documentation format of perl - Plain Old Documentation. This format has only a minimal set of simple commands and is therefore easy to learn. It is especially well suited for documenting programms, as this is it's main usage. And as an added benefit there are a lot of converters around to translate pod into other formatting languages like HTML or LaTeX.

Details and References

    http://www.neosoft.com/tcl/ftparchive/sorted/development
    ftp://ftp.neosoft.com/pub/tcl/sorted/development
          Sdoc3.1.*

    ftp://sunsite.unc.edu/pub/Linux
          Sdoc3.1.*