Configuration File format:
==========================
The FAQtor configuration file is in Windows INI file format. A typical INI file
consists of the following format:
[section_name1]
name1=value1
name2=value2
# comment
[section_name2]
name1=value1
name2=value2
The FAQtor configuration file is divided into 3 sections, namely:
- output
- page
- format
The beginning of each section is designated by [section_name] (eg. [output]) and each section contains
different options.
Here is a breakdown of each section:
output:
=======
Currently, only one option exists for output: "filename". Filename designates the path of the
output file to create. By default, this is "faq.html"
[output]
filename: faq.html
page:
=====
The page section consists of 3 options: start, end and sep.
- Start specifies the html markup that precedes the actual FAQ output.
- End specifies the html markup that follows the actual FAQ output.
- Sep specifies the delimiter that divides the questions and answer sections of the FAQ and
also divides each answer from one another.
Alternatively, the start and end options can specify filenames to use rather that defining the HTML
inline (in the configuration file). To specify a filename,
start: filename=somefile
which instructs FAQtor to use the file, "somefile" to precede the FAQ output.
Here are the defaults for the [page] section:
[page]
start: \
FAQ\
\
Frequently Asked Questions
end:
sep:
Notice that a backslash (\) is used to indicate a multi-line value. This convention is enforced
by INI file format rules and not specific to FAQtor.
Additiontally, inclusion of a style-sheet (css) can further customize the output that FAQtor creates.
format:
=======
The format section is used to customize the appearance of the FAQtor generated FAQ. This section
recognizes 4 options:
- section: describes the appearance of each section in the FAQ
- question: describes the appearance of each question in the FAQ
- answer: describes the appearance of each answer in the FAQ
- top: describes the appearance of the link back to the top of the FAQ
The defaults for this section are:
[format]
section: %(section)s
question: Q. %(sindex)s.%(qindex)s %(question)s
answer: A. %(sindex)s.%(qindex)s %(question)s
%(answer)s
top: Return to top
This section allows you to mix HTML along with parameter names that will be substituted by FAQtor
when it produces the FAQ. The format for each of these parameters is: %(param_name)s
For the substitution to succeed, this convention must be followed strictly and is enforced by
Python (string/dictionary substitution rules) rather than FAQtor.
For the "section" option, the %(section)s outputs the name of the section in the FAQ.
As seen above, this can be embedded within any HTML tags.
The "question" option recognizes these parameters:
- %(sindex)s : outputs the section # (which is assigned by FAQtor)
- %(qindex)s : output the question # (which is assigned by FAQtor)
- %(question)s : output the actual question
The "answer" option recognizes these parameters:
- %(sindex)s : outputs the section # (which is assigned by FAQtor)
- %(qindex)s : output the question # (which is assigned by FAQtor)
- %(aindex)s : output the answer # (which is assigned by FAQtor-- and always equals qindex)
- %(question)s : output the actual question
- %(answer)s : output the actual answer
Note: the sindex, qindex and aindex variables that are assigned by FAQtor are derived, beginning from 1
based on the order of appearance in the xml input file. That is, the first section listed in the xml
input file is 1, the second is 2, etc... If a section is added between these two sections then the
original 2nd will become section 3 when FAQtor regenerates the FAQ. Therefor, it is not a wise idea
to explictly refer to the links within the FAQ because they will change if the order changes. This
limitation will be addressed in the next version of FAQtor.