
INSTALL  faq-system 0.3.5  Thomas Linden [ tom@daemon.de ]



Here I will discuss the installation procedure and the configuration 
of the faq-system.


Please take a look to CHANGELOG too. New Features, enhancements and bugfixes
are documented in this file!



TABLE OF CONTENTS:

1. Requirements
2. File description
3. Preparation
4. Installation
	FAQ.CONF
	Protection
5. Getting started
6. Problems
7. Bugs











1. Requirements
---------------

What do you need to install and run the programs:

        - linux operating system. I have developed the software under
                linux and I guess it can't compile on other platforms.

        - compiler "egcs" or gcc 2.8.x. type "g++ -v" to determine your
		compiler version. If you have a compiler older than gcc 2.8.x
		(i.e. gcc 2.7.x) you may compile the sources, but they will
		not run properly! 
        
        - database system "mysql". You need to have installed the whole 
                mysql package with librarys and headers. I have developed
                the scripts on 3.21.33, maybe it is possible with earlyer 
                versions - I actually don't know, sorry.
		NOTE: since the version 3.22.22 the format of the grant tables
		has been changed! Refer to the website of mysql.

        - a webserver. the best choice is apache 1.3 (which I am using).
                If you use another webserver, please make sure, you can
                run cgi-bin's with it. The webserver has to run on the 
                same machine like the database.

        - gnu "make". You need it to prepare the installation, to run the
                compile process and so on.

        - "install". Needed to install the files to their location with 
                the neccessary permissions and attributes.

        - and - of course - all neccessary librarys and header files to 
                compile C++ source code. If you do not have all headers
                and/or libs you will receive an error-message during the
                compilation. If this occurs, please update your system!

        - last not least: always remeber murphy's law...


Currently I use NOT autoconf to create my configure script, so it doesn't 
determine, if all libs, headers and so on are installed. This will come as soon
as possible.
In the meantime please make sure yourself, that all required files are
available.











2. File description
-------------------

CHANGELOG...............Description of changes since the last version(s)
CONFIG..................main configuration file
COPYING.................GPL License description
INSTALL.................this file
README..................general informations
VERSION.................contains the version number
AUTOR...................contains my name and email-adress
answer.cc...............saves a new answer to the database
cgi.h...................class definition file [ class CGI ]
config.h................class definition file [class Pro and config ]
configure...............shell script, generates Makefile and a few 
			other files
database.cc.............mysql++lib from Roland Haenel <rh@ginster.net>
database.h..............mysql++lib from Roland Haenel <rh@ginster.net>
faq.format..............format decription of the database
faq.sql.................sql dump of the database
file.h..................class definition file [ class file ]
getanswer.cc............output of answer(s) to a given question
html.h..................class definition file [ class HTML ]
index.cc................generates the faq itself and is used as interface 
			to the faq-system
modify.cc...............modifys existent database records. it modifies both
			topic, question and answer.
question.cc.............saves a new question to the database
sample.sh...............sample script(/bin/sh), that answer.cgi could execute.
search.cc...............searching trough the database
topic.cc................saves a new topic to the database


Files generated by configure:

Makefile................the Makefile, needed by gnu make
conf.h..................c++ definition file
faq.conf................faq-system configuration file with default settings
index.html..............the database instance selection page













3. Preparation
--------------

Make sure you have all neccessary packages installed on your system, the following
packages do you need:
See "1. Requirements" for a detailed list of software required.

Please note, if you plan to install more than one instances of faq-system you must repeat
all the following steps for each instance.

If everything seems to be installed, edit the file CONFIG. You can modify the following parameters:

---
This is the subdirectory, where the DBADMIN mode files will be installed. After installation you may 
want to protect this directory with a .htaccess file
	_ADMIN="dbadmin"

The base URL for your cgi-bins. 
	_CGI_BASE_URL="http://localhost/cgi-bin/sql"

The base URL for your html's
	_HTTP_BASE_URL="http://localhost"

The unix path to the html's
	_HTTP_PATH="/usr/local/httpd/htdocs"

The unix path to the cgi-bins
	_CGI_PATH="/usr/local/httpd/cgi-bin/sql"

The name of your faq database
	_DB_NAME="faq"

The default values for faq.conf. You can change these values everytime you want.
Note, that, if you leave _DB_USER and _DB_PASS blank, than it is the webserver,
who connects to the database using the username and password running as. This is
the preferred method. If this differs on your system, of course you can change it 
	_DB_HOST=localhost
	_DB_USER=
	_DB_PASS=
	_DB_TABLE_TOPIC="topic"
	_DB_TABLE_ANSWER="answer"
	_DB_TABLE_QUEST="question"

OBSOLETE. But will perhaps used in the future, leave it blank. It's currently not used.
	_DBADMIN_EMAIL="root@localhost"

User ID and Group ID of the webserver. Make sure, this user have all permissions to the database,
if you did not specify username/Password for database login!
	_HTTPD_USER="wwwrun"
	_HTTPD_GROUP="nogroup"

If there is an older version of faq-system installed,
then you can here specify, if your existing faq.conf
should be overwritten or not.
Choose "YES" to keep the old file and "NO" to overwrite it.
	_KEEP_CONFIG="YES"

The c++ compiler, you can specify a complete path, if it is at another location
	_COMPILER="g++"

The gnu install binary
	_INSTALL="/usr/bin/install"

The directory that contains the mysql include files
	_MYSQL_INCLUDES="/usr/include/mysql"

The directory that contains the mysql library files
	_MYSQL_LIBS="/usr/local/mysql/lib" 

The default mode for full-index output(written to faq.conf), either "large" or "topic". See section "Usage"!
	_FULL_FORMAT="large"

You can specify html "templates" for header and footer. These files must consist in the directory which you have specifid
in the parameter "_HTTP_PATH". If you leave this parameters blank or the files cannot be opened,
default headers and footers will be generated:
	_HEADER="head.html"
	_FOOTER="foot.html"

-- 

NOTE: directories that not exists, will be created by install, you don't have to do anything.
















4. Installation
---------------

When you are ready with CONFIG, you can type the following command [make sure, you are in the
directory where you have copied the faq-system sources]:
	./configure


You should see any informational output. it will not determine your system setup. That means,
if one or more required headers or library are absent, then configure will _not_ notify you about this
problem. I will change in the near future to gnu autoconf and automake.
The script will generate some files (see above).


If nothing went wrong, type:
	make

You should see now some compiler output. If you receive any warnings or error messages, then
you may not have all neccessary libs and/or includes on your system or too old versions installed.
You must correct the situation yourself. If you need assistance, feel free to drop me a line.
Don't forget to include the error output so I can realize what were wrong.


If everything was fine, type:
	make install

The files will be installed and the neccessary permissions will be set.

Now you need to build the database. Use the script provided within this package.

First, create the database:
	mysqladmin create faq

Don't forget to define the permissions for this database. The Webserver itself has to have all
permissions: update, insert, select, delete. 

Now enter the following command
	mysql faq < faq.sql

If you get no message from mysql, then the operation was successfull.

Note, that you can use more than one database with these binaries, you have simply to repeat the above
steps and to insert an instance to faq.conf.


FAQ.CONF
--------
This file will go to your webroot (which you should have had configured in CONFIG), it has a really
simple format:
A database instance starts with "<name>" and ends with "</name>". As you see, it looks like html, so 
you should understand it. Here an example:
<faq>
        DATABASE=faq
	HOST=localhost
        USER=
        PASS=
        TOPIC=topic
        ANSWER=answer
        QUESTION=question
        FORMAT=topic
	SCRIPTSUPPORT=off
        RUN=
        TXT=faq.txt
	NAV=icons
</faq>
The following parameters are REQUIRED:
DATABASE, HOST, TOPIC, QUESTION, ANSWER

The other ones you can leave blank or they may not exist. A short Description of them:
USER: The user the faq-system uses to connect to a database.
PASS: Tha password used to connect to the database
FORMAT: "topic" or "large" possible. If "topic" is configured, then one file per topic
	will be created. If "large", then only one file will be created for the whole faq.
SCRIPTSUPPORT: "on" or "off" possible. if turned on ("on"), then you must specify a script-
	name(RUN). This script will be executed by answer.cgi everytime you answer to a 
	question. 4 Commandline parameters are given to this script:
	1. the name of the calling program (in this case "answer.cgi", but maybe other
	   cgi's will use it too)
	2. The question itself. Blanks will be replaced with "+". You have to parse them
	   out within your script.(i.e.: "What+the+hell+is+that+?")
	3. The position of the question (i.e. "3.12.").
	4. The name of the database-instance.
RUN: The script to be executed. Some notes:
	- it MUST exist and MUST executable by your webservers userid
	- take a look to the file "sample.sh". It such a script, which one could use.
	- Pay attention when you use this feature. This could be a security hole, if
	  script/program is not secure(i.e. if it changes system files or so)
TXT: index.cgi can also create a plain txt file from you faq database. If you want to use
	feature, you must provide here the name of this file (without path). it will be
	created in the same directory, where the html-faq is.
NAV: the kind of navigation bar created for topic-pages. You can use "icons" or "text", or 
	you can leave it blank, then "text" is the default. The following icons will be 
	copied to you web-basedirectory: top.gif, previous.gif and next.gif. There are two
	other sets of icons, simply rename them if you like them more then the default ones.

You can insert as many instances as you want. 
Last Note to faq.conf: If have had installed an older version of faq-system, you can leave
you original config file untouched. The system will work with older files too. Bevor installing
you have to set the variable "_KEEP_CONFIG" in CONFIG to "YES" if you want to keep your old
file.



Protection
----------

Make sure you have the dbadmin subdirectory ( both directories, one in http-root and one in the cgi-bin
directory) password protected. With apache webserver it is very easy to do this, please refer to the 
documentation from apache to learn more about this issue.
If you have configured apache to protect these directories, you can cd to them and use the tool provided
within apache:
	htpasswd -c .htpasswd username
You will prompted for a password. Additionally you will need a .htaccess file. Here an example:
	AuthUserFile /home/httpd/html/faq-system/.htpasswd
	AuthName faq-system
	AuthType Basic
	<Limit GET>
	require valid-user 
	</Limit>















5. Getting started
--------

In the first step that you did before compiling (did you?), you should have edited the file CONFIG. There 
are two important parameters: _HTTP_BASE_URL and _ADMIN. You will find in _HTTP_BASE_URL/_ADMIN/index.html
your starting point. Here you must type a database instance (which you should previously have installed),
then the script index.cgi generates the "workinpage" for you, from where you can modify the database.
You can protect the dbadmin subdirectory with .htaccess, if you are using apache. If not, please see the
documentation of you software or contact your vendor.

Usage is very simple. To get started, you need minimum one topic. 
Click on the link "[ new topic ]" , type the topic and click "submit".

Now click on "[ reload site ]" - the new topic should appear. Now you can insert a new question under 
this topic by clicking on "[ ask ]". Fill out every field and click on "save". by clicking on the reload-
link the new question should appear. But, as you see, you cannot click on this question, because the
system could not find a related answer. 
NOTE: in user-mode the "ask" link is available too. But the data the user fills in here will not be stored
to the database. An email-message will sent to you. You can modify this email-adress bevore compiling in
the file CONFIG.

To answer to this question click on "[ answer ]", fill out the fields and click save. When you have reloaded 
the database, you should see that that the question has an underlying link. When you click it, you will
come to a new page with the answer.

If you want to search trough the database, simply click on "[ search ]". Please note, that the search will
only processed through the keywords. So you can manipulate the search results! 

If you want to view the full-index of your faq database, click on "[ full index ]". 
You can copy the index to another locaton or what ever you want to do with it.

There are two ways, the full-index can be created. The first one is the "topic-mode", where an index-site
will created an an extra page for every topic. 
The other mode is "large-mode". Then only ONE page will be created with an index and anchors to every section 
of the faq. This is the mostly used format in the internet.
You can select, which format with full-index you want to use by setting the variable "FORMAT" in faq.conf 
inside your database instance-definition.

The name of the fullindex will be created from the name of the database. For example if the database's name is
"sql-faq" then the index name is: "sql-faq.html" and (if configured) the topics names: "sql-faq_topic_section.html.

To modify a database entry, click on "[ modify ]". A new form appears with the current values filled. Simply
edit them and click "Save". You can either modify a topic, a question, an answer and it's related keywords.

If you modify an answer (or even if you create a new one), you can use a special feature of the faq-system:
You can use special characters to create a hyperlink. Normally you will use simple html-tags to do so. But
it may be possible, that you want to have a link to another part of the faq. Here an example:
	Say, you want to get a link to the section 12.26. of your faq, because it is a related theme.
	Type the following line in the answer-field:
	##_12_26#See also this section#
	The html output generated from the system:
	<a href="http://yourhost/somewhere/topic_12.html#_12_26">See also this section</a>
	When you do it in this way you don't have to remeber some strange urls (or to copy/paste), you have
	only to know the Topic number and the Question Number. You can see these numbers in the mainview.

	You can insert as many links as you wish. Additionally, when you do not use "_12_24" but "site.html",
	then the link will simply point to this url.

You may want to search trough the database, use the [ search ] link. Usage should be clear.

















6. Problems
-----------

Compiling
In most cases, when you have problems to compile the package, you do not have the egcs compiler or not 
gcc 2.8.x. 

The other way to get problems is, when you do not have all neccessary headers and/or libs installed. 
Update your system in this case.

Some persons had also problems with libstdc++ 2.9.0. With 2.8.0 everything will work fine. If anybody knows,
why, please mail me!

Database
You may get some strange errors from mysql. This occurs mostly, when the permissions to the database are not 
set properly, tables does not exist and so on. 

cgi's:
You may get a "Fatal Server Error" if you want to run a cgi-bin from your browser. This happens mostly when the
webserver could not execute the scripts. Some possible causes:
	- the "cgi-bin" directory is not configured as cgi-executable, see access.conf
	- the username and/or group that you had configured in CONFIG were wrong. For example the webserver
	  runs as "wwwrun" but you have typed "wwwadmin". The installation procedure will install all cgi-bin's
	  with this owner. Solution: reedit CONFIG and run "make install" again, or change it yourself.
	- The permissions may be perfect, but the webserver cannot access the main directory. For example:
	  you have configured /home/httpd/cgi-bin as you cgi-bin dir. but the webserver cannot access "/home".
	  The best way to determine, is to login yourself as the webserver user and try to cd to the directory.
	  (you must temporarly provide a loginshell and a homedir for this user, don't forget to remove this
	  when you are ready!)
	- It maybe happen, that the cgi-program runs not perfectly. For example if a cgi-bin exits with exit(1),
	  then apache cannot handle it. That's why, all my programs exits with exit(0) so apache can display the
	  error-output. 
	  To test, what was happen, run the script from the command line. This happens, if you have compiled
	  the faq-system with gcc 2.7.x.
Anyway - it is a good idea to study the apache documentation about this topic.













7. Bugs
-------


If you find more bugs, please report it to tom@daemon.de. I will see if I can correct it.
















eof

