b. README

Version: 1.1.0
Date: 2001/06/05
features | limitations | demo | requirements | install | changes | credits | contact

b. is a Web-based manager for Web bookmarks. Bookmarks are stored in an XML file. Operations on the data are done with Perl scripts.

Features

Collaborative bookmarks

A new and powerful feature is the ability to share bookmarks. These shared bookmarks may be publicly viewed by all, while a certain set of users have the ability to add or change them. These users can also add comments to the shared bookmarks, as in a bulletin-board. The display of the shared bookmarks is highly configurable: one can show extra information associated with a bookmark, such as its popularity, when it was last visited, when it was added, etc. With these new features, b. becomes a collaborative space for sharing discoveries of the Web.

Old-style b. functionality is not lost however: one can still maintain a set of private bookmarks just as before. What's new is the option to exchange bookmarks between the private and shared sets.

Accessible from any Web browser

The main advantage for storing your bookmarks on the Web is to have them accessible from any Web browser. b. produces XHTML 1.0 code, doesn't use any Javascript, and is best viewed with a CSS1-compliant browser such as Netscape 6+/Mozilla, Internet Explorer 5+, and Opera 5+.

Bookmark data stored in XML format

XML has quickly become an acknowledged standard for the management of data transmitted over the Internet. Its foundation as a markup language like HTML gives it a wide base of users, and its precept of separating data from its display provides XML versatility for the many possible uses of the data.

I'm using a DTD for collaborative bookmarks called XBEL-collab. It's a slight modification of the XBEL DTD for bookmarks, to allow for features like comments and hit counts. The original XBEL DTD was created by python.org.

Customizable

In a themes/ subdirectory, one can determine the look of b. with CSS stylesheets, custom graphics, and HTML templates. There are more customization options with this new release.

Multi-user

b. supports multi-user environments. Using basic Web server user authentication (i.e. by password-protecting the b./ directory), only certain users can have access to b.. Each user has his/her own bookmarks and optionally can have his/her own theme, welcome message, etc.

Limitations

Must close browser to log off

This is a limitation of basic HTTP user authentication: once you have access to a directory, you always have access until your browser session has ended.

Modify bookmarks from one machine at a time

Problems can result if one attempts to modify bookmarks from two different machines at the same time. (Viewing and accessing the data from more than one machine is fine.) Although a backup of the XML file is written every time it is modified, something more secure could be implemented.

Demo

View an example of shared bookmarks >>. Also view a version of the same bookmarks from a user's perspective (read-only) >>. It is recommended that these pages be viewed with a CSS1-compliant browser like Netscape 6+/Mozilla, Internet Explorer 5+, or Opera 5+. For fun, I've specified two different themes for these pages.

Installation Requirements

Must be able to run Perl scripts on your Web server. For multi-user environments, must be able to password-protect the b./ directory.

Installation Instructions

Preliminary note: These instructions presume that you know something about dealing with CGI on a Web server.

new | upgrade | password-protect | customize

New installation

Unzipping will create two folders b./ and b.shr/. Move these folders to your Web site. The folders contain Perl scripts, so they both must be CGI-executable. Further, the Web server must recognize .pl files as CGI scripts. (The Apache directive to add to the b./ and b.shr/ directories is "AddHandler cgi-script pl".)

If the Web host is Unix, make sure the following files are executable (chmod 755).

b./b.contrib.pl
b./b.del.pl
b./b.fold.pl
b./b.link.pl
b./b.mod.pl
b./b.mod2.pl
b./b.see.pl
b./b.usrnfo.pl
b./b.usrnfo2.pl
b./index.cgi
b.shr/b.link.pl
b.shr/b.usrnfo.pl
b.shr/index.cgi

The following files and directories must be writable by the Web server.

b./
b./b.xml
b./users/
b.shr/
b.shr/b.shr.xml

Also make sure that the location of the Perl interpreter is at /usr/bin/perl. It probably will be. Otherwise, modify the first lines of the above Perl scripts.

Point your Web browser to http://<some_domain>/b./index.cgi. If you're like me, you'll probably need to spend some time trying to figure out why the CGI is not properly configured. First check if it's a permissions problem by going through the above instructions again.

Finally, when you're satisfied things are working, you'll probably want to password-protect the b./ directory (see notes >>). However, once you've done this, b. will create a new starter bookmark file in the users/ subdirectory, obsoleting the b.xml bookmark file in the root b./ directory. If you want to preserve any changes you've made to this file, follow these steps: 1) close your browser; 2) download the bookmark file you wish to save, usually b./b.xml; 3) upload this file into the b./users/<user_name>/ directory, overwriting the starter bookmark file.

To view the publicly accessible collection of bookmarks, go to http://<some_domain>/b.shr/index.cgi. Note there are no buttons to add or modify the bookmarks. Also note that the look of b.shr can be quite different from b.!

Upgrade from previous version

It is recommended that you first save a copy of your old installation of b., especially the b.xml bookmark files, as well as any custom themes. Don't bother retaining any b.conf files, as the format for those files has changed. After archiving, clear out or delete the b./ folder on the Web server to begin fresh. Follow the New installation instructions above >>. Once things seem to be working properly, you may upload your saved b.xml files. If there's a problem, check that the b.xml files are still writable by the Web server.

If you've created your own themes, then you'll need to make slight modifications to your b.css stylesheets. Furthermore, the themes/ directory is no longer in the b./ folder. It's now in the b.shr/ folder, to make the themes publicly accessible. Test your custom theme by uploading it into a subdirectory of the b.shr/themes/. If some things look wrong, use the included themes' stylesheets to guide you in making changes.

Note on password-protecting b.

For user authentication, b. uses the basic HTTP/1.0 security mechanisms standard with most Web servers. So you must set up your Web server to do this in order to take advantage of the multi-user features. I'm not going into how this is done since this differs among Web servers. If you're the admin of your Web server, then you may already know how to do this. If you are setting up b. on a remote server, then your host provider will probably have some Web-based configuration tool which allows you to specify certain directories as accessible to certain users. You'll need to provide a user name and password for each b. user.

Customize b.

Many customization options have been localized in various b.conf files. The b.conf file in the main b./ directory provides default options for the private bookmarks. View that file to see what options are available. Users may override these default options with a b.conf in his/her own user directory. The b.conf file in the b.shr/ directory allows many of the same options as the b./b.conf file, except that they apply to the b.shr bookmarks.

New themes may be added by adding subdirectories under the themes/ directory. Use the existing themes as an example. You may specify alternate bookmark and folder icons, as well as custom HTML templates. This new version of b. gives much more control over the display of your bookmarks.

The files b.template.xml and b.template.conf in the b./ directory are the starter files created for new users if they don't already have those files. You may modify these templates to customize starter environments for new users.

Changes

1.1.0 2001/06/05
Major development release with many new features. The major new features are: support for collaborative bookmarks; greater control of bookmark display with HTML template files; timestamping of created/modified/accessed times for bookmarks; record of hits for shared bookmarks; each user has own informational page; new theme; et.al.
1.0 2001/05/15
Version 0.4.1 below upgraded to stable version 1.0. No different in other respects.
0.4.1 2000/12/19
Bug fix for Apache complaints of "Not enough arguments for mkdir...". Thanks to Sean McGrath for catching this. Sean also suggested a clarification for the installation instructions.
0.4.0 2000/11/15
Can support multiple users when used in conjunction with basic HTTP user authentication. This feature is optional and no script modification is necessary if you wish to stay single-user, or if you wish not to use password-protection.
Fixed bug which disallowed the deletion of bookmark/folder descriptions. Thanks to Mark Jordan for pointing this bug out.
Some minor code cleanup and fixes.
0.3.0 2000/09/15
Added the ability to open and close folders. By hiding rarely-used bookmarks, one can speed up the bookmark display.
Fully compliant with the XHTML 1.0 >> strict specification. XHTML is an XML-ization of HTML 4 for broader accessibility among various browsers, present and future.
Folders and bookmarks can now have the characters &, ", <, > in their titles/descriptions. Other special characters may be inserted by inserting the appropriate HTML codes (e.g. &copy; for ©).
0.2.1 2000/07/03
Fixed bug: When deleting an item, the parser code would incorrectly mark the end of the range to be deleted. The result would be the unintended deletion of extra items. This bug has been fixed.
0.2.0 2000/06/28
Initial release

Credits

The initial parsing of the XML data was aided by the regular expressions in REX >>, written by Robert D. Cameron. The XML spec for bookmarks, XBEL >>, was created by python.org.

Contact

Check for the latest at http://www.n-gon.com/freshmeat/b./. You can also e-mail me at victor@n-gon.com regarding comments, suggestions, bugs, and some assistance. I reserve the right to ignore some questions deemed too painful to consider.