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.
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.
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
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.
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.
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.
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.
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.
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
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.
So far we have created two notes, with one blade in each.
Kelp allows us to have more than one blade per note.
Let's now extend the url note, by placing the following blade at the very beginning of hello.c.kelp:
@url http://kelp.sf.net http://kelp.sf.net/tutor.html
The content of hello.c.kelp will be:
@url http://kelp.sf.net http://kelp.sf.net/tutor.html @about A sample program used in Kelp's tutorial. @url in _hello.c http://kelp.sf.net/hello.c
If we now execute plantforest and kelp, the printout should look like this:
_hello.c (2)
The note count for our module hello.c is still 2. It so happens there are three blades, two of which belong to note url.
Let's now run kelp @url, and take a look at the output:
@url in _hello.c http://kelp.sf.net http://kelp.sf.net/hello.c http://kelp.sf.net/tutor.html
The two blades named url have been concatenated into one note with the same name.
As a general rule, blades with the same name form one single note, as demonstrated by the previous example.