y-notes documentation page

What is y-notes?

y-notes is a simple system that allows you to specify points of your web pages which your website's visitors will be able to annotate. y-notes annotation points are identified by a pin icon (

). Examples of such points can be found in this page at the top right corner, before the section "What do I need in order to be able to run y-notes?" below, and other places. Try clicking on some of the pins and sticking your own notes to this page. If after a few weeks you decide to visit this site again your notes will all be here, just as you left them.

You can also gather all your y-notes in a notebasket window (click here and it will pop up) which will help you navigate the web site much like your bookmarks would do (except that you don't have to clog up your browsers bookmark file!)

If your site is highly interactive, and you think your users might benefit from being able to share their notes, you may configure y-notes in a way that allows notes to be shared. If you add a note to the paragraph bellow, you will be able to choose whether to make it public (shared) or private:

Sample sharable annotation point: The link underneath the icon shows the number of public messages left by other users. You can see them by cliking on the link. Clicking on the pin will bring up a "note editor" with a checkbox; selecting it will make your note public.

y-notes implements all these functionalities through a set of lightweight applets and cgi scripts. The notes are kept at the server so that users can retrieve them at a later time and use them as a navigation aid. y-notes are particularly useful in large sites such as tutorials and reference manuals. They can also be used in web pages as a fairly uncomplicated way of gathering user feedback without requiring registration, logins, or passwords.

Why would I want to use y-notes?

For the the web user, y-notes provide a convenient way to add annotations to a web site without having to go into the messy business of managing a large set of bookmarks.

For the site maintainer, y-notes provides an easy and automatic way of gathering user feedback and improving the site design.

Besides, y-notes look nice :-)

What do I need in order to be able to run y-notes?

The main component of y-notes is a tiny Java^(tm) applet. Notes are stored on database managed through a CGI interface written in Perl. The requirements for running y-notes on your web site are, therefore:

A web server configured so that files with extension ".cgi" are run automatically via the CGI-BIN interface (the following line line in an Apache server config file, for instance, would do: AddHandler cgi-script .cgi
Perl 5.002 or greater,
The GNU database manager, GDBM, and
the respective Perl GDBM module (normally included in the standard Perl distribution for UNIX.

If you want to compile the Java sources, you'll obviously need a Java compiler in addition to the list above.

What will the visitors to my web pages need in order to use y-notes?

In order to run y-notes most comfortably all your users will need is a java-enabled web browser^*.

If your users are running a non-java enabled browser, then their annotation points will be automatically redirected to a fallback HTML form, which is less pretty and more cumbersome than the note applet, but does the job.

(* N.B.:Mac users running Netscape equipped with the default Netscape java interpreter might experience problems, as a few standard classes are missing from Netscape's (up to 4.6, at least) implementation of Java for the Mac. If you're a Mac user and are unable to see any pin applets on this page, check Netscape's Java console. If you see lots of complaints about missing classes, consider using MRJ as a plugin instead.)

How do I get the programs? Can I get the source code?

Y-notes is now hosted at

The latest releases of the source code as well as the compiled applets can be downloaded from the the y-notes project page.

y-notes is copyrighted by S. Luz and distributed under the terms of the GNU General Public License as published by the Free Software Foundation. You can use, redistribute and/or modify y-notes provided that the copyright notice and permission appear in all copies and in supporting documentation.

How do I install y-notes on my web site?

That's easy (assuming your web server runs on a Unix box). Here's what you'll need to do:

Download the latest release of y-notes from the y-notes project page at SourceForge.net (y-notes-?.?.?.tar.gz, a tar'd/gzip'd file),
Uncompress y-notes-latest.tar.gz,
edit the first lines of Makefile and
run 'make install'

See the source of this index.html for an example of how to add annotation points to your pages.

Then proceed to the documentation pages to find out about y-notemize.pl and the scripts provided with y-notes which will help you "y-nnotate" many pages in a web site automatically.

Thanks (What on Earth is Smalto??)

y-notes was 'invented' as a navigation aid for users of a web-based tool called "Smalto" (hence the name of the Perl package).

Dr. Luz wishes to thank Fabio Carvalhaes Luz for finding and helping sorting out a bug in the note applet, and Niels Ole Bernsen and anonymous users of Smalto for much valuable feedback and suggestions.

I'm not going to bother telling you what Smalto is all about, but you may visit the web site if you're desperately curious.

© 1999-2001 S. Luz

Page annotated with y-notes