FAQmanager version 2.2.2
Copyright (c) Richard Lawrence 1999,2000

The latest version of this document and FAQmanager can always be found at http://www.custard.org/~richard/faqmanager

NOTE: FAQmanager is the new name for FAQMan. The change was necessary as there is a FAQ-related product already available with the original name. Sorry for any confusion.

Contents

  1. What is FAQmanager?
  2. System requirements
  3. Creating .faq files
  4. The table of contents (toc) file
  5. Putting it all together
  6. Making it look pretty
  7. Searching
  8. Version history
  9. Licence issues and contact details

What is FAQmanager?

FAQmanager is a simple perl program that allows you to quickly and easily manage and maintain your Frequently Asked Questions list. A Frequently Asked Questions list (or FAQ as people like to call it) is just that, a list of questions and answers about something that people ask a lot. Its often used for clubs, societies, code and newsgroups and saves people from answering the same questions over and over again.

FAQmanager, however, cannot help you to write your own FAQ's. Instead it provides a simple way for you to update, modify and remove questions or sections without having to modify a large amount of HTML.

There are no hard and fast rules to planning a FAQ. The best thing to do is to use your favourite search engine (mine is google) and search for "FAQ" so you can see how others have attempted it. More often than not, FAQ's are split into a number of logical sections with a number of questions in each. However, there is no "right" rule of doing this.

Once you have your questions and structure then FAQmanager can make your life easier in the following ways:

System requirements

FAQmanager was written using perl 5.005_03 under Redhat Linux 6. The latest version was written using perl 5.6.0 under Redhat Linux 7. So there is a pretty good bet that it'll happily work under any reasonably modern flavour of Linux/UNIX with perl 5 or greater.

I don't have access to Activestate Perl under Windows at the moment so I cannot speculate whether it will work correctly. If anyone has managed to get it working and would like to tell me what they did, then it would be appreciated. Having said that, I can't see why it wouldn't work.

If the demand is there, I may do a version of FAQmanager in ASP.

To get the code running, you need to decompress it into your web directory (for example "public_html") and, under UNIX, you need to make the faqmanager.cgi program executable with "chmod 755 faqmanager.cgi".

FAQmanager assumes that your version of perl is located in /usr/bin/perl. If it is not then you will need to edit the first line of the script and change it to the proper location

There is a very basic example of a FAQ located in the example directory.

Creating .faq files

FAQmanager uses several files to create its FAQ. One of these are known as .faq files. These files end in .faq (obviously) and contain the list of questions and their answers in the following format:

  The title of the section
  :: A question
  The answer to that question
  :: Another question
  The answer to the other question
  :: Some other question
  Some other answer

and so on. So, in English, the first line contains the title of that section and from then on each question is prefixed with a :: and directly after it is the answer. These files should be saved with some sort of name ending in .faq (so, for example, "general.faq" or "configuration.faq" or whatever you like)

The format of the questions and answers should be in HTML. That means you can happily use hyperlinks, bold, underline, lists etc. to define how they look. However, if you'd like to change the standard font of the questions or the answers then you should realise that FAQmanager supports stylesheets and therefore hold off adding font tags until you read section 6 entitled Making it look pretty.

The table of contents (toc) file

So now you have one or more .faq files. All you need to do now is define which are used and their order. This is done using a Table Of Contents file or toc for short.

This file is very simple. Each line contains the filename of the faq that should be used. The order is very important, if you put one filename before another, then its questions will be in the section before the other. If you don't like the order, you can safely move entire sections around from the toc file. Here is an example toc file for, say, a bit of software:

  general.faq
  requirements.faq
  building.faq
  using.faq
  bugs.faq
  credits.faq

Each one of these files points to a .faq file which contains the questions for that section. Easy huh?

Hint: FAQmanager was designed so that multiple toc's and faq's could share the same directory. If you're only going to use one toc then it is recommended that you name it "faq.toc". If you do so, then there is no need to define the toc in the url as faqman will automatically assume its that.

Putting it all together

Now you have several .faq files and your .toc file, now is the time to put them together! Point your webbrowser to the script and see what happens. On my computer its http://localhost/~richard/FAQmanager_2.2.2/faqmanager.cgi but yours will definately be slightly different.

If all goes well, you'll see one of two things. Either an error message generated by FAQmanager saying it can't find "faq.toc" or you'll actually see the contents page (if you called your toc file "faq.toc")

There is a reason for this. By default, FAQmanager assumes that your toc file is called "faq.toc". However you can tell it to use a different toc filename (say, for example, you have multiple toc's in one directory) with the toc= argument.

If you get the former error (and its an error generated by FAQmanager) then add "toc=blah" where "blah" (don't include the .toc ending) is the name of your toc and you should find that the menu comes up! Yes? Fantastic.

Making it look pretty

So now everything is working, its time to make it look pretty. At the moment its rather dull and boring so we'll learn about templates.

FAQmanager allows you to use templates. These have the ending .ftf (FAQmanager template file) and contain the HTML you'd like to "wrap around" the FAQ.

If you look at one of the .ftf files in the archive you'll see that they contain html and one tag which you haven't see before called <faqmanager> which is on its own line. This is that tag that FAQmanager takes out and replaces with its own content. So anything before that tag will be at the top of the page and amything after that tag will be at the bottom.

There are three different template files. If you assume that your toc file is called "blah" then you have:

FAQmanager also allows you to use stylesheets to change the font size and style all over the document. If you don't know what a stylesheet is and how to use one then you should search on the web for some documentation.

FAQmanager uses the id tag with the following variables:

Searching

FAQmanager allows the user to easily search the faqs for a specific string. In order to do this, you need to place the following html within one (or more) of the template files:

  <form method="get" action="faqmanager.cgi">
  Search the faq: <input type="text" name="search">
  <input type="hidden" name="toc" value="blah">
  <input type="submit"></form>

This example assumes "blah" is the name of the toc, which you'll want to change. The output of the search page can be changed using the templates described above.

If your toc file is called "faq.toc" then you don't need to include the line that states <input type="hidden" name="toc" value="blah">.

Searching is, by default, case insensitive. That means that if you search for "fish" you will get back strings that match "fish", "Fish", "FISH", "FiSh" and so on. If you would like searching to be case sensitive (so that searching for "fish" will only return "fish") then you need to edit the faqmanager.cgi script and look for the line that says:

  my $case_sensitive = 0;

and change it to say:

  my $case_sensitive = 1;

If you do this, don't forget to tell people on your search page that it is case sensitive - otherwise they will wonder why they get so few results!

Version history

v2.2.2 (29th May 2001)

  1. Fixed incorrect usage of &nbsp which would mean non-IE browsers wouldn't render it.
v2.2.1 (25th May 2001)
  1. Fixed "@words[$count] better written as $words[$count]" error that would spam the webserver logs.
  2. Replaced the multi-line comment generated by the code with a single lined one after reports that netscape and lynx weren't showing the faq correctly because of it.
v2.2 (30th April 2001) - by Leo B Julius
  1. Updated searching algorithm so that multiple words are AND'ed and quotes can be used to ensure that exact matches are found.
v2.1.2 (25th April 2001)
  1. Fixed bug that made some searches return incorrect results (by Leo B Julius).
  2. When searching both the question and the answer will be searched, rather than just the answer (by Leo B Julius).
v2.1.1 (12th January 2001)
  1. Fixed bug that caused FAQ to occasionally be placed under all the HTML.
v2.1 (12th October 2000)
  1. Cleaned up code slightly.
  2. Fixed bug which caused trailing whitespace characters in the toc file caused FAQmanager to report an error.
  3. Added option for Windows users to set the path correctly if they have problems with paths.
  4. Added option for people to define whether searches are case sensitive or not.
  5. Revised this documentation and cleaned up example.
  6. Added request in the readme for people to mail me sites where they've used the script (just for curiosity sake really).
v2.0 (2nd September 2000)
  1. There is only one script called faqmanager.cgi now rather than two.
  2. The format of the toc file has changed. There is no need to place the URL of the main page on the first line and therefore you should remove it.
  3. The template structure has been redesigned. You should concatenate the top and bot files together and insert the <faqmanager> tag in the middle. Please be aware that the filenames of these files have changed too.
  4. If you don't define toc= then the code assumes the toc is called "faq.toc".
  5. The stylesheet tag faqanswer controls the output of the answers to faqs. You should re-define this and not the <p> tag.
  6. You can now allow people to search the faqs looking for strings.
  7. The arguments t= and f= have been fleshed out to toc= and faq=.
  8. The instructions are in HTML and not FAQ format.
  9. Error messages are more informative.
  10. Despite the pain in updating, it really is worth it!
v1.0 (Sometime end 1999)
  1. Code rewritten, documented and released.
v0.9 (Sometime mid 1999)
  1. Concept devised and original code written. It was never released.

Licence issues and contact details

This code is copyright (c) Richard Lawrence 1999,2000. You are given permission to use and modify the code for your own purpose but you may not redistribute this code with any modifications without prior permission from myself.

There is no warranty on the code. You use it at your own risk and the author cannot be held responsible for loss or damage to data or systems through the direct or indirect usage of this code.

Finally, you may not remove the lines of code that insert a comment into the html crediting me and pointing them to this site. Since its an HTML comment, no-one will see it anyway unless they specifically look at the source and it will not alter the way your html looks.

This code is NOT copyleft. With copyleft you can make changes and redistribute the changes, with this you can't. Why? Because its an original idea and i'd like control on how and where it progresses. Just because you can't redistribute the changes doesn't mean you can't modify the code to suit your needs.

If you find a bug and its something to do with the code i've written (and not because you've changed something and its broken) then please email me at richard@custard.org and i'll take a look. It would be helpful to also let me know what version of perl you are running and what Operating System.

If you do use the script on your site then I'd love to have a quick email from you pointing me to it. If you do, then it gives me a chance to see how you've used it, work out if I can make any improvements and above all, give me a nice warm feeling inside that I can use to write even more free scripts.

Finally, please note that I do not provide support for version 1.0 of the script anymore.
If you are having problems with it, please update to version 2.1.

Last updated: 25th April 2001