arts is the slightly grown up version of a few scripts written at Kiva
Networking to deal with a problem. The problem was that people would send
out mail messages to staff mailing lists that contained information that
ought not be forgotten. But it was being forgetten and lost in mail
folders. The original version of arts, blackarts, solved this problem by
providing an easy way to take those mail messages as they were created or
seen by people and push them into a web based document repository and give
them some semblance of order. Over time the system has grown to support
multiple repositories, sections in the repositories, and crosslinking of
documents between sections.

arts is a collection of scripts which process and manage incoming mail to create
a knowledge base. A configuration file arts.pl
defines individual repositories and where files will live. Each repository
is created as a collection of directories and a series of new script names
(symlinks to the installed scripts).

arts.gw accepts incoming mail on a pipe (generally via an alias in
/etc/alias or a similar mechanism), determines if the sender is allowed to post to the
repository, cleans up the message, adds some meta tags and writes it out
with a unique filename.

arts.ct is exec'd by arts.gw or run out of cron and parses the meta information in the documents to create tables of
contents. If the 'faq' setting for the repository is set in the config file
the main contents page will contain a link to a single document that has
been generated for that section. arts.ct takes an optional
-q argument that prevents it from spewing warn() messages when
exec'd from arts.gw.

artslist can be used to get a list of what is in each repository and what documents
are up to date or stale.

The meta information contained in the headers of the documents is used by
artslist to determine the freshness of the document. By default any
document going into arts is designed to expire in 15 days. The meta tags
are:

owner is the person who sent the mail
expires is when the document is going to expire
creation gives the day this file was created
title is the subject from the message
section is special and explained below

Expires and title can be used by artslist or by a program called webwatcher
which is designed to help keep web content from going stale. Webwatcher is
available at systhug.com.

change it so that it contains entries for all the repositories you wish to
have. Remember that the repositories are designed to be accessed from the
web. The pathnames you enter are absolute filenames in the file structure
of your system, not URLs. The entries in the config file describe what each
field means.

this will create the directories and symlinks necessary for the
repositories. when you do this the more directories that are created by
hand beforehad, the better the permissions will match what you are actually
after.

artsinstall will suggest some aliases to add to /etc/aliases, do that and
run newaliases.

artsinstall will also create the symlinks in the install directory that
symlink repositoryname.{gw,ct} to the main binary.

For each .ct program symlink create a cronjob that will run the contents
generator as frequently as need. If you have people who are editing their
files after they post them (which a good thing) you'll want to run the
contents generator this way to ensure that any title or section changes
they make show up.

Test by sending mail to the alias from a user that exists in the groups as
you configured them for each repository. If things aren't working you will
get a bounce message to the sending address. If things are working the file
will be placed in the repository and the contents files described in
arts.pl will be created and updated with the new document information.

Those created pages can then be viewed with a web browser pointed to a URL
that maps to your file location.

If you get stuck, contact the author, Chris Dent <cdent@burningchrome.com>, he
needs some advice on how to make these instructions better.

When sending mail to an arts repository which includes other recipients it
is wise to BCC the arts address, otherwise you run the risk of including
responses in the repository and that can get messy.

A document is made up of a title and a body. The body comes from a mail
message with the signature stripped off (if it has '-- ' at the beginning).
Text will be translated so that things that look like HTML still display as
raw text. If you want HTML in your document you should prepend a '!' to the
beginning of the line. This says don't translate on this line.

The title of the document comes from the Subject line of the mail message.

Repository sections describe categories in the repository for documents
that are similar in some fashion. The section is determined by the Subject
line. If there is no section the section defaults to 'misc'. If you would
like a section prepend the section name to the subject followed by a '#',
like this;

Subject: section name#This is the title

You may, if you like, crosslink a document into multiple sections, like
this:

Configuration is kept in the arts.pl file. If you choose to create an additional repository or change the
features of an existing repository you should make changes in arts.pl it is run anytime the other scripts are used. If you create a new
repository, you may run artsinstall again to get things setup.

The program and associated documentation is Copyright 2000 Chris Dent
<cdent@burningchrome.com> all
rights reserved. This program is free software; you can redistribute it
and/or modify it under the terms of either the GNU Public License or the
Perl Artistic License. The author would appreciate notification if you find
bugs, make improvements or otherwise have comments.