arts - arts is a system for creating quick knowledge bases from mail messages
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:
<meta name="owner" content="cdent"> <meta name="expires" content="+15"> <meta name="creation" content="19980715"> <meta name="title" content="nehi live pop testing"> <meta name="section" content="">
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.
Installation is relatively painless. The basic goal is to create the filesystem entries where the documents will go, add symlinks identifying the new repositories, and add mail aliases.
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.
0 */1 * * * root /usr/sbin/wanarts.ct
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:
Subject: section one & section two#This is the title
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.
configuration file
gateway program
contents page generator
repository creator
tool for displaying info on repository docs
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.
More info can be found at http://arts.sourceforge.net including a sample arts repository with further documentation.