iFAQMaker is a simple PHP script to ease the managments of FAQs. Basically, it is a rewrite of the code I used in phpVideoPro (and, besides, this rewrite goes back there to replace the old code) -- and that is where the, on a first glance -- strange-looking syntax for the input files comes from. The main topics iFAQMaker is intended to cover are:

• Inserting/Deleting/Moving single topics (within the same FAQ file) without the hazzle of reorganizing indices, numberings and links
• Use of templates to display the FAQ corresponding to the web site design
• Use of user-definable makros for frequently used formatings etc.

iFAQMaker needs no database or the like - it simply works with files. In general, we can distinguish between the program code, configuration, and content files. One central index.php file is the only one to be called within the browser. It takes the topic to display as only argument, which is at the same time the basename of the content file to parse (without the extension): so http://www.myserver.tld/faq/index.php?topic=faqmaker parses the faqmaker.txt content file and displays it according to your setup, as you see it here.

This is just a short description - further below, this page also contains information about the setup, configuration, and the structure of the input files.

The installation of iFAQMaker is quite easy: just copy all the content of the archive to the place where you want to have it in your web tree, and it is ready to use. Of course you can adapt it closer to your website and personal requirements by e.g. placing the templates or content files to another location, and adjust the config to reflect these changes and more.

The configuration takes place in the config.inc files, which must reside in the same directory as the index.php itself (unless you change the include() command in the index.php to use a different file/location). For all relative directory/url specifications made here keep in mind, that they are relative to the index.php files location (not to the config.inc).

There are some other files for customizing iFAQMaker described in this document. These are the makros.inc file for your personal makro definitions, and the trans.inc file for description mapping ("translation").

The basic configuration of iFAQMaker is done here - and under normal circumstances, there should be no change necessary to the "program files" itself. Here you set up the files and directories used, charset and title, plus some additional elements you want to be in the generated page (this is be done by setting up placeholders for them in your Template files which we then refer here. All variable names used for the setup start with $fs to avoid conflicts e.g. with the makros ($fm*) and other variables. These initials stand for "Faqmaker Setup" resp. "Faqmaker Makro". The config.inc file is parsed as PHP script: so make sure you don't break the syntax ;)

In the provided sample config.inc file, the setup variables are provided with a short description of what they stand for, from which you should be able to understand their meaning. Just some words on the last block in this file, the placeholders for your Template file: Since these may contain phrases that need to go through the "translator", we set them up as tiny little function to be executed after we read the "TransTable file". The $fsNav array elements name is the name of the field in your Template file, the term assigned to it is the replacement.

Here you can set up makros for phrases/formatings you frequently use. Same as with the config.inc file, this is parsed as PHP code; so make sure to a) stick to the PHP syntax and b) prefix the makros names with $fm (recommended) to avoid overwriting e.g. setup variables. All these makros (as well as other set-up variables) you then can access in your FAQ text files by enclosing the makro name in curly braces (no blanks in between!). The $fmCodeOpen makro found in the shipped sample macros.inc thus can be addressed as {fmCodeOpen}

The trans.inc file, as the file extension may already suggest, again parsed as PHP code. It is looked for in the FAQ text file directory defined by the $fsFext variable of your config.inc file. and holds some useful mappings, defined in the array variable $fsLang. But what are these for?

We evaluate the topic name of a FAQ file by the file name. Since the file name itself sometimes is not very descriptive, we can map its name to a different "translation". So if you e.g. have a file named jr_tolkin.txt, and the FAQ should be titled "J.R. Tolkien", just enter this connection here:

$fsLang["jr_tolkien"] = "J.R. Tolkien"

These relations are then "translated" by the lang() function which, if it finds no matching relation, just returns the passed string with the first letter in uppercase. As you see in the example config.inc, you can make use of this for common placeholders in your templates as well.

For the "Template feature", iFAQMaker uses the template class from PHPLib. The template file itself is plain HTML code, containing some placeholders and block marks (for repeated parsing of a single part of the template). You can create your own templates (and stylesheets), and this way fit the resulting formated FAQ page into your design. Currently, iFAQMaker generates the HTML header directly, so you are restricted to HTML pages. This may change with some future version of iFAQMaker, if I see that there is need for (of course this depends on your feedback).

The input files are plain text (ASCII) files, containing several text blocks. Within these text blocks, you optionally can use placeholders which, as the name suggests, are replaced by iFAQMaker when the file is parsed. For some samples of how an input file can look like, see the page containing some iFAQMaker Demo input files.

Text blocks start with a block marker and end, logically, when the next text block starts (or at the end of the input file - whichever occurs first). There are three types of blocks: title, text and - optionally - the eof block. Block markers are enclosed in square brackets and must stand alone (without anything around it but, optionally, spaces) on a line. The block content then should start in the next line.

So the simple title block marker looks like [title]. Optionally, it can have up to two parameters that are separated by the pipe symbol. The first parameter is the title level (defaults to "1"), the second a name to be used for references -- this defaults to the block number, which is a bit cryptic and will just work for automatically generated references, as from the TOC to the topic. Such a "complete" block marker would look like [title|2|special], which would mark a 2nd level title whichs content can be refered to with <A HREF="#special">.

The same syntax applies to the [text] block marker, with the only difference that the two optionally parameters will have no effect here.

The placeholders can be devided into two types: makros and translators.

Makros are enclosed in curly braces. You can define own makros in the makros.inc file. Generally, you can not only use the makros defined there, but all variables set in the script can be refered by this - which is useful if you want to link to other categories (input files) available to the same iFAQMaker instance, by creating a href looking like <A HREF="{_SERVER["PHP_SELF"]}?topic=other_file">. Inside the curly braces there must be no spaces - or the makro will not work. Easy reason: Spaces are not allowed in variable names. Again, for details you may want to have a look at the Demo Input Files for iFAQMaker.

Translators are defined by the trans.inc file. This is thought for "translating" certain words that should always look the same throughout the document, but could change for several reasons - like e.g. brand names. Imagine for example the reference to a program in a FAQ - like iFAQMaker here. Now your FAQ is as big as > 100kB text file, mentioning the programs name several 20..200 times -- and now I decide to rename it to, e.g. phpMyFAQ. Now you could do a search-and-replace on all your FAQ files -- or simply change the phrase in the trans.inc file if you made use of translations.

To tell a translator, I used the old German "BTX style": so a word that starts with an asterisk (*) and ends with a hash (#) is considered a translator. Again, no spaces are allowed between the * and the #.

Generally, you can place comments everywhere inside the document (see the source input file of this page for example, if you can): every line that starts with a hash mark (#) is considered a comment (leading spaces are allowed). But there are two special areas treated completely as comments: the area before the first [title] and after the optional [eof] block markers. Everything in those places will completely be ignored. This can be useful if you e.g. temporarily want to remove a text block from the FAQ: just move it behind the [eof] mark, and it will no longer be displayed. Later (after some corrections, or whatever reason it was has been solved) you can move it back at any time, the information is not lost.

If the script is called without any parameter, it would not know which input file to process - so we should have a useful default. An index page, displaying all available categories (= input files), will make most sense in this case. For this issue, the infile name index.<ext> (where <ext> is the extension you specified with $fsFext in your config.inc file) is reserved: at this place you should create your "central page", containing links to all your FAQ files. This "index" file has the same structure as any normal input file.