WebKNotes

About

WebKNotes is a web based Knowledge database of notes written in Perl, stored in a plain file (text/html) hierarchy. An existing static web page hierarchy can be changed into a interactive system by using WebKnotes.

• Notes and subtopics about anything added by any user.
• Search facility.
• User Authentication
• Users can edit notes they created.
• Notes can be viewed using several different methods, or the files can just be browsed.

• like plain web pages, but anyone can add and edit pages online.
• like newsgroups, but the hiearchy grows, as every note is a catagory.
• like Wiki, but notes are organized in a hiearchy, and notes can be html, text, and now even Wiki files.
• like Slashdot, but not database backed. Webknotes currently would probably not scale well to that level.

WebKNotes is written and maintained by Don Mahurin.

Project

Download WebKnotes on the sourceforge download site, or from the sourceforge ftp1 site

Install

Running

Example:

http://yoursite/cgi-bin/wkn/browse.cgi
http://yourispsite/~yourusername/cgi-bin/wkn/browse.cgi

From there you can login, add topics, edit topics, and get file level access.

The "User Accounts" link will allow you to add and modify user permissions. For this, use the administration user created by the configuration script. If for some reason, you have no administration user. You can manually edit a users file(in private directory) and add an 's' to the permissions.

More Information

css.htxt - Information on CSS class definitions

css_tables.htxt - Information on CSS bug work arounds

permissions.htxt - List of all the user/group permissions

mod_perl.htxt - Description of support for mod_perl

Copying

Disclaimer

I claim no responsibility for this package. If it harms something in any way whatsoever, It's not my fault. If you do not understand the risks involved in using this package, do not use it.

Sample

Samples with themes ( NEW! )

Here are some examples on sourceforge:

SourceForge like
Freshmeat like
Freedos/Happy Peguin like
More Happy Peguin like
Slashdot like
Linux Games like

(You can't currently add anything notes on the wkn on sourceforge)

Supporting this project:

Probably the best support now is just having people use it and tell me about it.

Feedback, bug reports, success/horror stories

If use_cvs is defined in filedb::define, each directory with a CVS directory is assumed to be cvs, and changes will be commited when added, edited or appended.

It is assumed that such cvs directories are not externally changed.

- support of indented (tabbed) paragraphs in htxt. - make illegal dir pattern configurable.

subscribe.cgi -
possibly subscription options stored in private_dir/subscriptions/USER/path_with_dots
Options are:
  n - non-recursive

Configure should save setup constants only used for configuaration in setup_define.pl (in directory that Configure is ran from).

possibilities for email verified:
 - Ability to Add topics via EMAIL
 - Email subscription.
   - auto-subscribe to topics that you create
   - [un/]subscribe to other/all topics
 - Ability to usubscribe ALL.
 - Ability to reply to a knotes email and have it put in DB
 - Ability to subscribe to a flat dir or the dir tree.

MAYBE SOMEDAY::
 - Database backend

An optional file page_template.html may exist in your installed cgi-bin directory. This file is expected to be an html template, where the actual output of the cgi will replace the XML tage: <%$page%/>

The content before the tag will become the page_header.

The content after the tag will become the page_footer.

The following is the order in which permissions are set and/or modified:

   $default_permissions set in filedb::define
   User permissions (set via user accounts)
   Per directory permissions (set via access/permissions)

A permissions string is a comma separated set of permission modifications n format:

   {WHO}{MODIFIER}{PERMISSIONS}

WHO: - Who the permissions are applied to

   'o' - directory owner
   'u' - registered user
   'v' - verified user (by email)
   'g' - users in directory group
   'a' - all

MODIFIER: - How the the current permissions are modified

   '=' - new permissions replace current permissions.
   '+' - new permissions are added to current permissions.
   '-' - new permissions are removed from current permissions.

PERMISSION: - What permissions are set or unset

   'r' - read
   'n' - add note
   'c' - create
   'm' - modify
   'a' - append
   'd' - delete
   'u' - upload
   's' - system privalege
   'i' - inherit permissions
   'S' - subscribe permission
   'M' - mail permission (send modification notification to subscribers)

Note that usually when specifying directory permissions, you want to specify the inherit ('i') permission, so that sub-topics are created with the same permissions.

Examples:

Anyone can add and read notes, Owners can modify and delete notes:

   $default_permissions = "a+rn,o+mad";

Anyone can read, Users can add and append, verified users can modify and upload, owners can delete:

   $default_permissions = "a+r,u+na,v+mu,o+d";

This license is derived from the Perl Artistic License with
the sections not applicable removed ( later part of 6. 7, 8 )
 
		       a General Artistic License

				Preamble

The intent of this document is to state the conditions under which a
Package may be copied, such that the Copyright Holder maintains some
semblance of artistic control over the development of the package,
while giving the users of the package the right to use and distribute
the Package in a more-or-less customary fashion, plus the right to make
reasonable modifications.

Definitions:

	"Package" refers to the collection of files distributed by the
	Copyright Holder, and derivatives of that collection of files
	created through textual modification.

	"Standard Version" refers to such a Package if it has not been
	modified, or has been modified in accordance with the wishes
	of the Copyright Holder as specified below.

	"Copyright Holder" is whoever is named in the copyright or
	copyrights for the package.

	"You" is you, if you're thinking about copying or distributing
	this Package.

	"Reasonable copying fee" is whatever you can justify on the
	basis of media cost, duplication charges, time of people involved,
	and so on.  (You will not be required to justify it to the
	Copyright Holder, but only to the computing community at large
	as a market that must bear the fee.)

	"Freely Available" means that no fee is charged for the item
	itself, though there may be fees involved in handling the item.
	It also means that recipients of the item may redistribute it
	under the same conditions they received it.

1. You may make and give away verbatim copies of the source form of the
Standard Version of this Package without restriction, provided that you
duplicate all of the original copyright notices and associated disclaimers.

2. You may apply bug fixes, portability fixes and other modifications
derived from the Public Domain or from the Copyright Holder.  A Package
modified in such a way shall still be considered the Standard Version.

3. You may otherwise modify your copy of this Package in any way, provided
that you insert a prominent notice in each changed file stating how and
when you changed that file, and provided that you do at least ONE of the
following:

    a) place your modifications in the Public Domain or otherwise make them
    Freely Available, such as by posting said modifications to Usenet or
    an equivalent medium, or placing the modifications on a major archive
    site such as uunet.uu.net, or by allowing the Copyright Holder to include
    your modifications in the Standard Version of the Package.

    b) use the modified Package only within your corporation or organization.

    c) rename any non-standard executables so the names do not conflict
    with standard executables, which must also be provided, and provide
    a separate manual page for each non-standard executable that clearly
    documents how it differs from the Standard Version.

    d) make other distribution arrangements with the Copyright Holder.

4. You may distribute the programs of this Package in object code or
executable form, provided that you do at least ONE of the following:

    a) distribute a Standard Version of the executables and library files,
    together with instructions (in the manual page or equivalent) on where
    to get the Standard Version.

    b) accompany the distribution with the machine-readable source of
    the Package with your modifications.

    c) give non-standard executables non-standard names, and clearly
    document the differences in manual pages (or equivalent), together
    with instructions on where to get the Standard Version.

    d) make other distribution arrangements with the Copyright Holder.

5. You may charge a reasonable copying fee for any distribution of this
Package.  You may charge any fee you choose for support of this
Package.  You may not charge a fee for this Package itself.  However,
you may distribute this Package in aggregate with other (possibly
commercial) programs as part of a larger (possibly commercial) software
distribution provided that you do not advertise this Package as a
product of your own.  

6. The data files supplied as input to or produced as output from the
programs of this Package do not automatically fall under the copyright
of this Package, but belong to whoever generated them, and may be sold
commercially.

7. The name of the Copyright Holder may not be used to endorse or promote
products derived from this software without specific prior written permission.

8. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

				The End

HTXT files are txt files with simple Hyper links and some implied text formatting.

Links are specified with [ [ LINK ] ] ( brackets are not space separated in a actual link. )

LINK has the form RELLINK or URLLINK or URLLINK|LINKTEXT or RELLINK|LINKTEXT.

Where rellink is a relative link to a directory or file or to another htxt file (specifying the extention is optional).

Layouts and themes are saved with a user settings. For anonymous users, the settings are passed along with each request. You can change the layout and theme, by choosing "Layout/theme" at the bottom of the page. If you wish to create your own theme, see css.

The layout of the file and directory listing can also be changed. Also there can be a "super layout" specified. This is actually a layout that contains another layout. Typically this is a framed layout or nothing.

Webknotes supports mod_perl. You need "PerlSendHeader On" to turn the double header off.

Before, I use a couple of globals for two purposes:
  - keep track of current layout in view_lib.pl
  - for caching user_info and user for calls in a query.

Basically when I put it in mod_perl strange things happened because, those values were global accross queries.

I think perl objects are messy and wanted to keep it simple, with the idea of some scoped globals that are local to a query.

The solution I came up with is a method called "localize_sub" in each main package file. A query main function is "converted" my these functions to localize the globals to that function.

Problem remaining:

You can't run mod_perl scripts setuid. This means that the only way to have wkn work is to have 'www', 'web' or 'httpd' own everything, and run the cgi scripts with no setuid. This is not secure.

Maybe what we need is setuid SpeedyCGI.

A user can turn off or on subscription for a particular topic using the "Subscribe" button on each topic page.

A user must have permission 'S' to subscribe, and other users must have permission 'M' to generate subscription mail. See permissions.

The directory hierarchy is esstially a directory tree.

Usually, topics and sub-topics are represented as directories in the tree.

The text of each topic is stored as file inside the directory. For HTML, and pre-formated HTML, this is README.html, For Text, this is README. For HText, this is index.htxt. For Wiki, this is FrontPage.wiki

In both HText and Wiki topic directories, Topics can also be created as files. The files are created there are given .htxt or .wiki file extensions.

Other files can be manually added to the hierarchy and are understood by WebKnotes.

index.html is assumed to contain the index for the topic hierarchy contained below it. No file listing is shown. No file listing is shown.

Other .html files can be viewed and editted, but no sub topics can be added.

Other .txt files can be viewed and editted, but no sub topics can be added.

Of course, all of this should be transparent, and users should not need to know the storage mechanism.

The css tables class serves to work around CSS bugs in existing browsers.

The _normal translation is to print it assuming a bug free CSS implementation (at least as used).

The _ns4 provides support for Netscape 4.

Some notes to keep your CSS portable:

For netscape any background and border information must be replicated in another -border class, since The ns4 workaround uses an outside table to get borders to work ( borders for tables, tr, and td are ignored by netscape.

Don't use "padding" definitions. No workaround exist for Netscape's bugs.

What you need to get started:

Perl5 - installed as /usr/bin/perl (if somewhere else, you need to modify all .cgi scripts using (util/perlpath) )

CGI.pm - part of standard Perl 5 dist.

A setuid mechanism. ./Configure will also ask about this.

Un-tar the source (not in a web directory), then in the webknotes directory, configure and install by running (in a terminal window): ./Configure ( if you are upgrading webknotes, run ./Configure --cgi=/home/.../cgi-bin/wkn, to default to your previous definitions )

This will create the define files, copy the cgi-bin directory and create an admin user.

The initial un-tarred directory is no longer needed after configuration unless you wish to re-configure.

This starting point will be something like: httpd://localhost/cgi-bin/wkn/browse.cgi, depending on the location of your cgi-bin.

Also, in the util directory is a script called 'cgitohtml', which will create a static file from a cgi script, given the cgi base.

Examples:

simple case:

 util/cgitohtml /~awebuser/cgi-bin/wkn
 /home/awebuser/public_html/cgi-bin/wkn/browse.cgi ""

Or, really specifically, on my dma web page (they use cgi-wrap for cgi scripts), I do:

 util/cgitohtml /cgi-bin/cgiwrap/dmahurin/wkn
 ~dmahurin/public_html/cgi-bin/wkn/browse.cgi "layout=page" \
 "" "wknbook" "Computer/Linux" "" \
 "People/Don Mahurin" "colspan=2" "People/Don Mahurin/Projects/wkn" \
 > ~/public_html/index.html

To allow one user to own and modify all the notes (via the cgi scripts), you need one of these on your web server:

   -setuid perl enabled(suidperl)
       chmod u+s *.cgi
   -cgi-wrap - http://www.unixtools.org/cgiwrap/
   -setuid apache module(suEXEC) enabled.
       http://www.apache.org/docs/suexec.html
   -use setuid_wrapper that was available with perl4
   -compile and use util/sperl_user.c
       cd util
       cc sperl_user.c -o sperl_`whoami`
       chmod a+x,u+s sperl_`whoami`
       using util/perlpath, change all cgi scripts to point to this exe.

To create a new theme, I suggest that you start with an existing one.

Here are the classes that you can add styles to:

   topics-back - The background behind topic boxes
   topic-table - Each topic table
   topic-title - The title in a topic table
   topic-info - Modification and owner of topic
   topic-text - text body of topic
   topic-actions - Action bar associated with topic
   topic-listing - Listing of sub topics 

There are longstanding bugs with various browsers with regards to CSS. For this reason, some hackery was needed. The workaround for Netscapes problems with borders required a containing border table to be create for each class that you want a border for:

   topic-table-border, topic-title-border, topic-info-border,
   topic-text-border, topic-actions-border, topic-listing-border.

In these definitions, for Netscape to work properly, you must repeat and background and border information that you placed in the complete css definition.

Also, do not use padding definitions. No workaround exist for bugs here.

The css_tables classes serves to work around CSS bugs in existing browsers.

To use WebKNotes as a DirectoryIndex and file handler in Apache, add the following section. "/docs" should correspond with the top level directory that WebKNote handles (doc_wpath).

/cgi-bin should be /cgi-perl or /perl if you use mod_perl.

 <Location "/docs">
    DirectoryIndex /cgi-bin/wkn/index_browse.cgi
    Action webknotes /cgi-bin/wkn/index_browse.cgi
    AddHandler webknotes .wiki
    AddHandler webknotes .htxt
 </Location>

Here a example of how to link within your notes to a Sub topic

I don't really understand why the wikis are so popular. So I gave up, and attempted to support .wiki as if it was a markup language.

There's a importwiki tool included to mine some wikis.

It remains unclear what mixing .wiki's and .wiki catagories and text and html really will look like.

Hopefully, people can use this in whatever way works.

There are still some issues to work our as to how to properly wiki in a hierarchy.

But some hierarchy has to help a little more than a flat directory for some casual browsing. Maybe I'll write an "auto hierarchy/auto link" program to generate a basic hierarchy. Or maybe you will ...