makefaq

makefaq is a Python program that creates a Frequently Asked Questions (FAQ) list from a
specially formatted text data file. For output, it can can generate either an HTML page, a
text file, or a DocBook XML file.

January 28, 2009 - After basically five years of not really working on
this project at all, I've decided to revive it a bit primarily as a way to learn about the
git version control system and the github repository site. I will be honest and say that I
don't know how many actual changes/improvements I'll be making to the code, but I will be
making some changes purely to learn about using git. If you have any
requests for changes, please feel free to email me.

(And if none of that made any sense to you, please just skip along down the page and
download the source code directly from the links below.)

February 29, 2004 - Release 2.5 is now out with a minor change so that
using it with Python 2.3 no longer generates a warning.

February 22, 2003 - FYI, based on: 1) feedback from a number of users
who have indicated they are very happy with the current data file format and have no
interest in having an XML data format; and 2) my own current lack of time to implement the
XML interface, I'm going to put the plans to implement the XML data file format on hold
for the moment.

Note that version 2.0 introduced a new data file format with support for
multi-line entries. The older 1.x data file format will NOT work by default. However, by
adding the '-r 1' (for "revert") command-line option, the old style of data file
format will work fine.

Modifications Necessary:

You may need to change the path to where python is located, and you will need to
change the data file and header and footer file to be appropriate for your site.

Usage:

In the default configuration with no command-line options, the program will output an
HTML file (faq.html) based on the contents of a data
file (faq.dat), a header file (faqheader.html)
and a footer file (faqfooter.html) in the same directory.

Type makefaq -h to see the full range of command-line options now available.

Description:

This program creates an HTML or text Frequently-Asked Question page from a text file
where each category, question and answer is defined. An example is here. See below for other examples .

There is the capability to generate both an HTML and text FAQ off of the same data file, as well as a range of configuration
and command-line options. View the README and INSTALL files for more information.

Bugs:

If someone uses the special entities of either &lt; or &gt; to generate the
< or > character, those entities are not stripped from the output when in text or
screen mode.

For those of you purely interested in the python code itself, it is available
here. If you are a python developer and interested in the CVS repository, check the project page there for
information about how to get the latest code.

If you do use the program to generate a publicly available FAQ page,
please do send the URL to dyork@lodestar2.com so
that we can list it here as another example of the program in action. Examples
include:

What are the odds that two people interested in building FAQ's for web
sites and interested in learning python would both reside in close geographical
proximity to each other? Amazingly, Dave and I both lived in New Hampshire, USA, and
got to meet face-to-face at a talk Dave gave on PHP in February 2000 for the Seacoast (NH) Linux User Group (SLUG). A picture of the
two of us is below. I (Dan) am on the left, Dave on the right... I think perhaps we'll
institute a rule that any new contributors need to have a beard! (Just kidding...)