====================
What is FAQ-O-Matic?
====================

The Faq-O-Matic is a CGI-based system that automates the process of
maintaining a FAQ (or Frequently Asked Questions list). It allows
visitors to your FAQ to take part in keeping it up-to-date. A
permission system also makes it useful as a help-desk application,
bug-tracking database, or documentation system.

This documentation itself is, naturally, maintained with Faq-O-Matic:

  http://faqomatic.sourceforge.net/

===============
Latest Version:
===============

Before you get in too deep, make sure you have the latest version
of the FAQ-O-Matic. Check the main website to see which version it is
running:

  http://faqomatic.sourceforge.net

Especially the Administrators' Guide:

  http://faqomatic.sourceforge.net/cgi-bin/fom?file=3

And check the download site for the most recent revision:

  http://sourceforge.net/project/showfiles.php?group_id=10674
  http://prdownloads.sourceforge.net/faqomatic/


===========
Quickstart:
===========

% perl Makefile.PL
% make
% make install
% mv fom /usr/local/etc/httpd/cgi-bin/fom
         (or wherever your CGIs live.)
% netscape http://localhost/cgi-bin/fom
  (or whatever browser you prefer)
           (or whatever the URL would be to execute the CGI)

* subscribe to faqomatic-users (see link to FOMFOM at bottom).

* add your Faq-O-Matic (a description is fine if it's not public) to
the List of Faqomatics (on the FOMFOM).

* send Jon a postcard, if you're feeling generous.

======================
Themes and Variations:
======================

* If you don't have the privilege to install the modules in an "official"
  place, tell Makefile.PL that before you start:

    % mkdir ~/user_perl
    % perl Makefile.PL PREFIX=~/user_perl
    % make
        ...

* If your web server requires CGIs to have a certain suffix, simply
  rename the generated file "fom" to something like "fom.cgi":

        ...
    % mv fom /usr/local/etc/httpd/cgi-bin/fom.cgi
    % netscape http://localhost/cgi-bin/fom.cgi

* If the user that CGIs run as can't write to the directory in which
  CGIs reside (a wise security move), create a writable meta/ directory
  (or a link to one) there in advance:

        ...
    % mv fom /usr/local/etc/httpd/cgi-bin/fom
    % mkdir /usr/local/etc/httpd/cgi-bin/meta
    % chown nobody /usr/local/etc/httpd/cgi-bin/meta
    % netscape http://localhost/cgi-bin/fom
    
    or
    
        ...
    % mv fom /usr/local/etc/httpd/cgi-bin/fom
    % mkdir /somewhere/else/meta
    % chown nobody /somewhere/else/meta
    % ln -s /somewhere/else/meta /usr/local/etc/httpd/cgi-bin/meta
    % netscape http://localhost/cgi-bin/fom

* If you'd rather not even put a link in that directory, modify the
  fom CGI stub to name the meta directly:

    % vi fom
    % cat fom
    #!/usr/local/bin/perl
    use Faq::Omatic::dispatch
    Faq::Omatic::dispatch::main('/somewhere/else/meta/');
        % mv fom ...

  Either of the above two techniques are also suitable for running
  multiple FAQ-O-Matics on one server. Keep in mind that if the FAQs
  are related, they should probably be kept together as one FAQ with
  a few main categories, so searches will search the entire lot.


=====
Bugs:
=====

  Bugs and problems are best reported at
  http://sourceforge.net/tracker/?func=add&group_id=10674&atid=110674



============
Author Info:
============

        Jon Howell
        jonh@cs.dartmouth.edu
        http://www.cs.dartmouth.edu/~jonh