image: tdoc.gif


english/tdoc.tex
Version 1.2
Document 1.2

29/10/1996

Contents

Introduction

This program builds a complete, indexed documentation from your tcl scripts.

You add documentation information to your scripts 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 powerfull enough to create nice and good looking documents.

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

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

Here are some highlights

The Tcl Documenter is also available as a commercial version. This version adds the following features:

Documentation Overview

Creating documentation for source code is normally a tedious and error prone process - especially when sources are modified after the documentation is written.

tdoc 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. Indexing 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

As explained in the previous chapter the format in which documentation is written should be a simple text format (so it can be mixed with source code and therefore kept in the same file as the source).

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 to 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.

The following sections are an excerpt from the original perlpod.pod manual page:

PERLPOD

 

NAME

perlpod -- plain old documentation

DESCRIPTION

A pod-to-whatever translator reads a pod file paragraph by paragraph, and translates it to the appropriate output format. There are three kinds of paragraphs:

That's it. The intent is simplicity, not power. I wanted paragraphs to look like paragraphs (block format), so that they stand out visually, and so that I could run them through fmt easily to reformat them (that's F7 in my version of vi). I wanted the translator (and not me) to worry about whether " or ' is a left quote or a right quote within filled text, and I wanted it to leave the quotes alone dammit in verbatim mode, so I could slurp in a working program, shift it over 4 spaces, and have it print out, er, verbatim. And presumably in a constant width font.

In particular, you can leave things like this verbatim in your text:

    Perl FILEHANDLE $variable function() manpage(3r)

Doubtless a few other commands or sequences will need to be added along the way, but I've gotten along surprisingly well with just these.

Note that I'm not at all claiming this to be sufficient for producing a book. I'm just trying to make an idiot-proof common source for nroff, TeX, and other markup languages, as used for online documentation. Translators exist for pod2man (that's for nroff(1) and troff(1)), pod2html, pod2latex, and pod2fm.

SEE ALSO

the pod2man manpage and the section on PODs: Embedded Documentation in the perlsyn manpage

AUTHOR

Larry Wall

Documenting Tcl Scripts

Now that you know the documentation format you need to add documentation to your tcl source code (perl does recognize pod paragraphs as belonging to the documentation, tcl does not). Therefore you have to put your documentation inside of tcl comments.

We have put some other (arbitrary?) limitations on the location of documentation and on the contents of the documentation to ease the extraction of documents and to allow uniform looking output.

Example Script

Before going into the details here is a simple example of a documented tcl script:

# =head1 add offset to point
# =head2 Description
# This routine takes the point given by
# its first argument, adds the given 
# offset and returns the new position.

# =head2 Arguments
# =over 3
# =item point
# This is the original point, it's format is a
# list of two (real) values.
# =item offset
# This is a list of two real values, representing
# the I<x-> and I<y-offset> to move.
# =back

# =head2 Return Value
# The return value is a list of two values
# representing the new (moved) point.

proc MovePoint { point offset } {
    set x [expr [lindex $point 0]+[lindex $offset 0]]
    set y [expr [lindex $point 1]+[lindex $offset 1]]
    return [list $x $y]
}

Formatting Conventions

Every procedure documentation starts with a =head1 title. The title itself should briefly describe what the function does. This string is also used in indexing the procedure. There should be only one =head1 in a procedure documentation block.

All other titles should be of the =head2 type. You should (but don't need to) adhere to the standard headers used in manual pages (eg. Description, Arguments, Return Value, Errors or Bugs). You may use any of the formatting options available in pod to make your documentation more readable.

The first non-comment statement after the documentation should be the proc line as it is used to extract the name of the procedure and the actual arguments. This information is used to create the Synopsis-section for the current entry.

Output Example

Here is the (LaTeX-) output of the above example:

MovePoint - add offset to point

 

Synopsis

 
        proc MovePoint { point offset } {}

Description

 

This routine takes the point given by its first argument, adds the given offset and returns the new position.

Arguments

 
point
This is the original point, it's format is a list of two (real) values.
offset
This is a list of two real values, representing the x- and y-offset to move.

Return Value

The return value is a list of two values representing the new (moved) point.

Documenting Procedures in C Source Code

Documenting tcl procedure definitions in C sources is a bit different to the above process. As with the tcl script documentation is kept in front of the actual function that implements the new command (this is not identical to the place where Tcl_CreateCommand is used).

Documentation is started with a C comment start followed by a line beginning with =head1. This line contains the name of the tcl procedure that is implemented by the C code, a dash and a short description of what the procedure does.

The rest of the documentation follows the guidelines given in the Tcl-part. A final note: the comment must be closed by a */ on an extra line.

Again, an example to clarify things:

/*
=head1 add offset to point
=head2 Description
This routine takes the point given by
its first argument, adds the given 
offset and returns the new position.

=head2 Arguments
=over 3
=item point
This is the original point, it's format is a
list of two (real) values.
=item offset
This is a list of two real values, representing
the I<x-> and I<y-offset> to move.
=back

=head2 Return Value
The return value is a list of two values
representing the new (moved) point.
*/

static int 
MovePoint(
 ClientData Data, Tcl_Interp *interp, 
 int argc, char **argv)
{
...
}

Using the Tcl Documenter

tdoc scans tcl scripts and C source files for documentation that follows the guidelines described in the previous chapters. It extracts this information and build the documentation from it. You may display the generated documentation or you may directly write it to a file in one of the available formats.

tdoc operates on the current directory by default. It displays all files that have an extension of either .tcl or .c. You may select files to document or unselect selected files by using the selection list shown by the programm:

image: tdoc1.gif

A different directory may be selected by using the menu option File/Select Directory, by entering a directory on the command line or by modifying the entry field Directory.

The title of the generated document may be changed by modifying the entry field Title.

Now click on Document and tdoc opens a new window displaying the generated documentation. You may also use the menu File/Export Data As to write the documentation to a file.

image: tdoc2.gif

Copyright

The programm tdoc is available in two version:

Copyright for the Public Domain Version

This version is fully functional and contains essentially the same features as the commercial version. Missing are the package selection mechanism, the direct connection to emacs and some of the export formats. The public-domain version is a lot slower as it uses more tcl-level routines.

There is no guarany that the public-domain version will be available any longer, that it will be supported or that any bugs will be fixed.

This software may be used, copied, modified and distributed for free as long as the copyright stays intact and you don't make any money from it.

Copyright for the Commercial Version

This version is fully functional and contains all the features described in the previous chapters. With the purchase of this software you are entitled to use the services of softWorks (maintenance, support, upgrades). Ask for more details about the commercial version of tdoc (or just start the license-manager and select tdoc).

Generic Copyright Terms

This programm contains parts with their own copyrights like Tcl and its extensions TclX, Tk, Blt and Tix. These packages are all freely available from the internet.

IN NO EVENT SHALL THE AUTHOR OF THIS SOFTWARE BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE AUTHOR OF THIS SOFTWARE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE AUTHOR OF THIS SOFTWARE SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE AUTHOR OF THIS SOFTWARE HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

Additional information may be found in the document General Business Policy and Terms of Delivery.

Changes

Version 1.1

This is the first version made available to the public. The subversion 1.1.1 is the public domain version, 1.1.2 is the commercial version.

Known Bugs

Currently there are no known bugs. There are probably some minor inconveniences hidden deep inside the program...



softWorks
Richard Schwaninger
Tue Oct 29 15:12:31 MET 1996