FAQ Manager FAQ

1.1 Why Do I Need a FAQ Manager?   (08/09/98 Paul Johnson <pauljohn@ukans.edu>)

FAQ Manager makes it easy to update Web documents. Use your browser to inspect your document, hit the FAQ Manager link, and voila! (or Shazam! or Eureka!) you are in an editor.

If you've ever had to maintain an outlined list of items in HTML format, and then make sure the numbering in your outline matches a separate Table of Contents, you already know why FAQ Manager is valuable.

1.2 What are the Special Features of FAQ Manager?   (08/09/98 ? <?>)

FAQ Manager allows you to create FAQ pages very easily. It has these special features:

1. Automatic Outlines

2. FAQ Manager creates an outline structure that can be two headings deep. You can have a FAQ with many questions grouped into a smaller subgroups. There is no limit to the number of questions or groups.

3. User Friendly Interface

The interface is self evident. FAQ Manager has split 3 modes: New, Edit and Move/Delete.

1. Creating new Items:

• Type in the content of question/answer
• Write a link to another page instead of typeing the content
• Upload the file for the Answer section from your disk (so you can write it with your favorite page editor)

2. Editing Items: Easy select->edit->submit combo. Again like in 'Add new item' you can upload a new file, write the content yourself or just leave the URL to another document

3. Move/Delete Items: In that mode you can move or delete items and groups of items very easily if you select a destination of move to be a trash can, the selected items will be deleted.

Submit the Changes and Check them Out: Changes are implemented when you hit the "Submit" button. Then pressing 'Back to document' button will take you immediately to the page you have been editing and you will see the latest changes.

4. Fix your Mistakes

If you submit a change, a Commit Rollback feature appears. You can undo several stages of editing!

5. HTML Codes Can be Used in FAQ Manager Documents

FAQ Manager creates a nice looking outline if you just type in material, but if you want some special HTML tags, go ahead and use them.

6. On-Line Help

The How Do I...: button will give you the detailed help for the usage of the current mode.

2.1 How do I get the FAQ Manager?   (08/09/98 ? <?>)

You can download it for free from http://www.eprotect.com/stas/TULARC/works/faq_manager/

2.2 What do I need to install and make it work?   (08/09/98 ? <?>)

FAQ Manager runs on Unix/Linux systems. It is a perl script, so most importantly it requires:

• Perl5 (you can get it from http://www.perl.com)

  FAQ Manager requires that these perl modules be installed as well (they may already be present in your installation of Perl):

• CGI.pm (You probably already have it, but you can get it from http://www.perl.com/CPAN)
• Storable.pm (you can get information about where to find it from http://www.perl.com/CPAN)
• Dumper.pm (Distributed as Data-Dumper, version 2.04 or newer. Get it following the links from http://www.perl.com/CPAN)

• Note: a JavaScript enabled browser is needed to edit a FAQ Manager document.

2.3 How do I install it?   (09/09/98 ? <?>)

Check Your System Setup

First, make sure you've got a working system with Perl 5, the needed modules, and an http server. You probably should serve up a regular html document or two before you mess with FAQ Manager.

For purposes of installation, you have to know a little bit about your system--its web address and how it serves cgi scripts. Suppose for purpose of discussion that your server is named

your.server.com

You keep the executable cgi scripts in a directory such as

/home/http/cgi-bin/

and your web documents are in the "documentation" directory, such as

/home/http/docs/

Users can access these documents by going to the URL http://your.server.com/

You also need to know how cgi scripts are activated on your system. Later on, you will edit one of your html documents and insert a command to start up FAQ Manager. You need enough information to customize a command like this:

< A HREF="http://your.server.com/cgi-bin/faq_manager-2.02/faq_manager.pl"> click here to activate FAQ Manager </A >

You need not set your documentation directory to /home/http/docs. You can configure FAQ manager to write its output into any directory where you serve up HTML files. A single user, Bill Jones, might configure FAQ Manager to write into his personal space /home/billjones/public_html. Users would find his documents by going to the URL http://your.server.com/~billjones.

Prepare Perl Modules For FAQ Manager

I assume you have root access in what follows and then at the end add some comments for users who do not have root access but can install FAQ Manager under cgi-wrap.

If you have root access, you can install the perl modules in the /usr/lib/perl5 hierarchy. If you untar the perl module, all you do is type

% perl Makefile.PL
% make
% make install

Install FAQ Manager Software in CGI-BIN

• Step 1: Copy the FAQ Manager package to /home/http/cgi-bin/

  Unpack the package faq_manager.zip or faq_manager.tar.gz with:
  

  gzip -d faq_manager.tar.gz
  

  tar -xvf faq_manager.tar

  or

  unzip faq_manager.zip.

  That should create a directory with a name like faq_manager-2.02 with the FAQ Manager files in it.

• Step 2. Move the Images directory.

  You need to move the images somewhere in your documentation space. Change directory to faq_manager-2.02 (so now you are in /home/http/cgi-bin/faq_manager-2.02).
  (type "mv Images /home/http/docs/" . Don't forget where you put these, you will need this info later). These are FAQ Manager "icons". Change to the new Images directory, type "ls -la" to see the permissions and make sure that files in that directory are readable by the webserver. It is safe to make sure by "chmod 444 *" to give all users read access.

• Step 3. Edit your faq_manager configuration.
Go to /home/http/cgi-bin/faq_manager-2.02/setup.
Make a copy of config.pl for safe keeping, then use a text editor to open the file named config.pl . You need to put in a bunch of site information. See the explanations inside the file for more information.

One user named billjones installed Faq_Manager on a Redhat Linux 5.1 system and shared his configuration. He writes documents to his personal directory, as you can see:

$CGI_URL = 'http://your.server.com/cgi-bin';
$CGI_DIR = '/home/httpd/cgi-bin';
$DOCS_URL =  'http://your.server.com/~billjones';
$DOCS_DIR = '/home/billjones/public_html';
$cgi_obj_dir = "$CGI_DIR/faq_manager-2.02/data";
$self_url = "$CGI_URL/faq_manager-2.02/faq_manager.pl";
$image_url = "$DOCS_URL/Images";
$base_dir = $DOCS_DIR;
$base_url = $DOCS_URL;
$cookie_path = "/cgi-bin/faq_manager-2.02/";

• Step 4. Deal with permissions of faq_manager.pl and the data directory. The web server runs under the name of a user and that user must have the power to execute faq_manager.pl and access the data subdirectory of faq_manager-2.02. The name of the user under which httpd runs is system-specific. On many Linux systems, it is "nobody". It can be anything, really, according to the taste of the person who installs the web server software. You have to find out the user name used by the server. Look around for files like /etc/httpd/conf/httpd.conf

  Checking that the faq_manager.pl script is executable is the easy part. Worst case scenario is that you have to type "chmod 555 faq_manager.pl" This makes it executable by anybody.

  It is harder to be sure the web server can write in your data directory. Assume that in config.pl you set the

      $cgi_obj_dir  = "$CGI_DIR/faq_manager-2.02/data";
  

  The easy approach is to make the owner of the data directory the user that httpd runs under, such as nobody. You could type: "chown -R nobody.nobody ./data".

  The directory has be readable & writable, so you may set permissions:

  chmod ug+rw ./data

  Now your web server can read and write in the data directory.

• Step 5. Make sure the first line of faq_manager.pl is correct for your system (It has to be able to find Perl! That's the whole point of a Perl script, after all...). You can look around for the perl executable in directories such as /usr/bin/ or /usr/local/bin, or try a locator program such as "which perl" or "whereis perl" on Unix. (Note that you can have more than one perl installed you should find the latest one)

• That's all! Go fiddle around with some documents and make yourself famous on the Web.

If you don't have root access, but do have CGIwrap on your system, you can install FAQ Manager and the perl modules in your private user space, and then configure to use the CGIwrap setup.

• Install the Perl modules. First, make a directory in your home for them.

      % mkdir ~/user_perl
  

  Then untar the perl modules and do this:

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

  Next, make a personal directory for cgi scripts.

       % mkdir ~/cgi-bin
  

  Copy the FAQ Manager software in there, untar it, and then configure it.

  CGIwrap has some advantages. For example, cgi scripts run with your personal user name, so they have the ability to write in the data directory. (That's a lucky break, because you can't change the owner to "nobody" if you don't have root access).

  The disadvantage of CGIwrap installations is that Perl scripts have trouble finding subdirectories. Even if a user activates faq_manager.pl, that script may not be able to find its own subdirectories ./lib, ./setup, etc. There is a Perl module called FastBin which addresses that problem, but one user reported it didn't work, so these notes take a simpler approach. The plan is to "hardcode" all vital paths into the perl scripts so FAQ Manager runs.

• Edit faq_manager.pl.

  In faq_manager.pl, fix the path to your local perl AND add "use lib" commands to tell it where to find your perl modules.

  #!/usr/bin/perl -wT
  use lib '/home/billjones/user_perl/lib/perl5/site_perl';
  use lib '/home/billjones/public_html/cgi-bin/faq_manager-2.02';
  

  Second, Replace the line:

   require "./setup/config.pl";
  

  With the line that points to your config.pl file:

  require "/home/billjones/public_html/cgi-bin/faq_manager-2.02/setup/config.pl";
  

• Edit ./setup/config.pl. Most things are the same as the Root example above, but there are a few vital differences:

  First, get the initial URLs and DIRs correct:

  $CGI_URL = 'http://your.server.com/cgiwrap/billjones';
  $CGI_DIR = '/home/billjones/public_html/cgi-bin';
  $DOCS_URL = 'http://your.server.com/~billjones';
  $DOCS_DIR = '/home/billjones/public_html';
  

  You still have to set the these basics:

  $cgi_obj_dir = "$CGI_DIR/faq_manager-2.02/data";
  $self_url = "$CGI_URL/faq_manager-2.02/faq_manager.pl";
  $image_url = "$DOCS_URL/Images";
  $base_dir = $DOCS_DIR;
  $base_url = $DOCS_URL;

  Fix the cookie path

  $cookie_path = "/cgiwrap/faq_manager-2.02/";
  

  Now, in the bottom of the file, find these lines

  require "./lib/messages-lib.pl";
  require "./lib/html-lib.pl";
  require "./lib/parse-lib.pl";
  

  It is necessary to make those paths explicit so the faq_manager.pl can find its libraries! In Bill Jones's case, these change to:

  require "$CGI_DIR/faq_manager-2.02/lib/messages-lib.pl";
  require "$CGI_DIR/faq_manager-2.02/lib/html-lib.pl";
  require "$CGI_DIR/faq_manager-2.02/lib/parse-lib.pl";
  

• That should do it. Now proceed to make a FAQ Manager document.

2.4 How do I create a new FAQ page?   (09/09/98 ? <?>)

To create a new FAQ page, copy the template file from the ./tmpl directory into your documentation directory (or subdirectory of the documentation directory). The file is called faq_template.inline.html, but you should rename it (e.g. my_faq.html).

The CGI doesn't create the initial FAQ pages, you do that by editing this template.

2.5 How do I modify the template?   (09/09/98 ? <?>)

• Insert Your Permanent Content

  Modify the page you have just created to suit your needs. Near the top, find the words "Sample Faq". That is the section where you can insert any comments, welcome messages, or whatever.

  You can modify everything before:

  <!--end of top--> line (don't remove it !!!)

  You can modify almost everything under

  <!--start of bottom--> line (don't remove it !!!)

• Customize the call to the CGI script

  Next, find the line:

  < A HREF="http://www.nowhere.com/faq_manager.pl" > FAQ Manager </A >
  

  And change it so it points at your installed faq_manager. Do the same at the bottom of the file. To be perfectly clear, in the above example, this would be:

  < A HREF="http://your.server.com/cgi-bin/faq_manager/faq_manager.pl" > FAQ Manager </A >

• Warning about hand-editing FAQ Manager Documents

  Be carefult to leave the special comment tags, which are used by faq_manager.pl to locate the FAQ content's start and end. Do not fiddle around with text that FAQ manager creates. It won't work if it can't recognize the content!

2.6 How do I protect the FAQ Manager?   (09/09/98 ? <?>)

If you are going to use the FAQ Manager on the Internet or at the place you don't want others to change the contents of the FAQ but a group of authorized people you need to password protect the directory where faq_manager resides.

You need to create 2 files:

• .htaccess - this file specifies who is allowed to be authenticated and where it should look for the passwd file. Here is a sample file:

  AuthUserFile /home/httpd/cgi-bin/faq_manager/.htpasswd
  AuthGroupFile /dev/null
  AuthName FAQ Manager
  AuthType Basic
  
  Options ExecCGI   
  
  require user joe stas nati
  
  

  You need to modify it to suit your filesystem layout

• .htpasswd - this file keeps the pairs username:passwd to authenticate the users. Here is a sample file:

  joe:LksPl7LksPlOO
  stas:BDfu3LksPl7SS
  mati:kqMPl7BDfu3E3
  

  You can create this file using the htpassd script which is almost for sure available on every server

After you finish configuring these 2 files. Try to follow the link to FAQ Manager, and it should prompt you with login/passwd popup window. Try to login with username/passwd that you choose and if you succeed you have finished with this section

3.1 How does the tool work?   (08/09/98 ? <?>)

When you follow the link to faq_manager from the page you want to edit, the variable HTTP_REFERER is being set to an URL of the page you have called the cgi from. The tool translates the URL to the real path of the file on the filesystem by replacing http://your.server.com with /home/httpd/htdocs so URL of http://your.server.com/faqs/faq1.html will become /home/httpd/htdocs/faqs/faq1.html. The translation is done by using $base_dir and $base_url.

Now all is left to the faq_manager is to read the file, let you edit it, and write it back...

When you call the script it saves the top and the bottom of the html, grabs the rest of the content, splits it to groups, questions and answers and represent for you in GUI so you can edit it. Now every time you do submit to some action either add, edit or move/delete the html is recreated by taking the saved top and bottom htmls and recreating the content of HTML by internal function (that can be modified to suite your needs) a.k.a creates the index of FAQ and the question->answer pairs.

Another thing is how the original file is recreated when you edit it: Once page is read in, it's getting parsed. First we split the page into 3 parts top, body, and bottom by using $top_sep and $bottom_sep separators (these are the comments that you have been requested to keep untouched in the file). We remember the top and bottom since we will need them back when we will write back the modified document.

Next step is to parse the body and extract all groups, questions and answers. We do it with help of $g_begin_sep $g_end_sep $q_begin_sep $q_end_sep $a_begin_sep $a_end_sep separators. The extracted data is stored on the disk using the unique string to name the file. We pass that file name as a hidden parameter from form to form. Each time you apply some change -- a new file is created and passed along. Every time we increase the index of the object file .2 .3 ... etc. So you can always jump back to one of the prior versions.

With help of javascript we fill the question/answer input form with preset values when you select some item to modify.

The directory of objects $cgi_obj_dir is getting cleaned when the script called for a first time per faq it checks for files older than 2 days and delete them. Ofcourse you can change that value.

That's all. If you want to learn even more, read the code :-) It's well commented.

3.2 How do I work with FAQ Manager?   (08/09/98 ? <?>)

There is a complete online documentation when you work with the tool. Just press a 'How do I...' button in the action menu on the left side and you will get a new window with detailed documenation of the current mode usage. When you switch the modes (add/edit/move/delete) you get a different help page