This tutorial has been written for Kelp version 1.4.

It assumes that Kelp has been installed for your platform and can be executed from the command prompt.

To check the appropriate version is installed on your system, run kelp -v and plantforest -v from the command line.

Hello, World! Suppose our task is to annotate a source code file called hello.c stored on this very web server.

Our task is to look at this file and understand it, a task commonly known as "code walk". Usually we would be able to modify the file's content and insert our own comments, taking note of anything that may help us understand the code better.

Unfortunately, we are not able to modify hello.c : it is stored on the webserver and any changes made to a local copy would not be visible to anyone else accessing the file; they would also most likely be irrelevant when the file is modified.

All the information (possibly hundreds of lines of text) would be lost. The obvious solution is to write our notes in a separate file. What we need is a system to link the notes we are carefully writing, back to the relevant source code. Back to Contents

Getting started Let's create an empty file called hello.c.kelp .

The file's location is not important, as long as we have execute permission on the directory where the file is stored.

For argument's sake, let's say the directory where you stored the empty hello.c.kelp file is called kelptutor , and it is located in your home directory. ./ | +-kelptutor/ | +-hello.c.kelp Back to Contents

Our first note We are going to describe what hello.c is about.

Let's open hello.c.kelp , which is currently empty, and write: @about A sample program used in Kelp's tutorial. The first line is an 'at' character ( @ ), immediately followed by the word about , and a newline character.

The second line is a plain text line which describes what this source code module is about.

In Kelp, we call this a blade.

Every blade has a name. This blade's name is about.

Every blade with a matching name forms what we call a note, so notes in Kelp are composed of blades with the same name.

Let's save the file.

We now have the note about for hello.c on our local system. This note is composed of one blade.

In the next section we will see how to retrieve this note. Back to Contents

Planting the forest Let's move into the kelptutor directory, and run the command: plantforest If there are no errors, the program exits silently, and a file called forest appears in the directory.

You can also check the program return code, which should be 0. CAVEAT Do not delete forest ; it is used by Kelp when retrieving notes.

If you accidentally delete forest at any time during this tutorial, just execute plantforest again in this directory. Back to Contents

Running kelp From the kelptutor directory, execute the command: kelp The output should look exactly like this: _hello.c (1) If it doesn't, please check your are using the version of Kelp this tutorial was written for and correctly followed the instructions above. If you require any further assistance, you are welcome to use our Help forum. Back to Contents

Kelp's output Let's interpret the printout from executing kelp : _hello.c This is the name of the module we just described. The name of the module begins with an undescore ( _ ).

(1) This is the count of all the notes (not the blades) written for module hello.c . We only wrote one note in hello.c.kelp , so it is hardly surprising this number is 1. Back to Contents

Another note Let's now take note of the URL where hello.c can be found.

In hello.c.kelp , let's add this blade: @url http://kelp.sf.net/hello.c The only difference between the previous blade and this one is the text after the @; the two blades belong to two different notes. The content of hello.c.kelp should look exactly like this: @about A sample program used in Kelp's tutorial. @url http://kelp.sf.net/hello.c Back to Contents

More output from kelp Whenever we modify a .kelp file, we need to run plantforest , so that kelp can recognise the changes.

Therefore, we must run plantforest first, then we can run kelp .

The output should look like this: _hello.c (2) As expected, the note count is now 2. But we are still not able to see the content of those notes.

That's because we must specify additional arguments when calling kelp to display the note we want to retrieve.

Right now we want to display the blade we just wrote, so we execute the command: kelp @url The output will look like this: @url in _hello.c http://kelp.sf.net/hello.c We specified the name of the note we wanted to print using a command line parameter composed of the @ symbol and the name of the blade.

In general, to display a note, we need to indicate its name when executing kelp . Back to Contents