makefaq.pl: FAQ

What is makefaq.pl?

makefaq.pl is a Perl script designed to make the creation and maintenance of an HTML FAQ page very straightforward. It uses the Perl module Text::Textile to allow FAQ authors to use simplified markup rather than writing raw HTML.

What are the basic features of makefaq.pl?

makefaq.pl has been designed from the ground up so that creating and maintaining a FAQ page can be done using only a text editor.
FAQ questions and answers reside in ASCII text files, one question and its corresponding answer per file.
Text files with questions and answers use simplified markup (standard HTML is an option).
The order in which questions are displayed by faq.html is set with a simple text file, and that order can be easily changed.
The structure of faq.html is defined by a simple template, and user variables are defined in a simple configuration file.
faq.html builds with a simple make invocation.
makefaq.pl generates valid XHTML.
CSS can be used to define the appearance of faq.html.

What is faq.tmpl?

faq.tmpl is the template that describes the structure of the HTML FAQ page. It is used by the Perl module HTML::Template.

What is faq.ini?

faq.ini is the configuration file for makefaq.pl. Here is faq.ini for this page:

[site]
	template = faq.tmpl
	css = faq.css
	favicon = favicon.ico
	output = faq.html
[header]
	h1 = Frequently Asked Questions
	h2 = All the Answers Fit to Print
[footer]
	author = Pann McCuaig
	email = yourmanpann@users.sourceforge.net
	modified = time
[page]
        title = makefaq.pl: FAQ
        markup = textile
	order = faq.ooq

Acceptable values for modified are date, time, and none. Acceptable values for markup are textile, html, and none.

faq.ini is parsed using the Perl module Config::IniFiles.

What is faq.css?

faq.css is the CSS file that determines how faq.html will be rendered.

What is faq.ooq?

faq.ooq is a text file that list the order of questions in the FAQ page. The faq.ooq file for this page follows:

whatmfpl.txt
basic.txt
faqtmpl.txt
faqini.txt
faqcss.txt
faqooq.txt
whatmake.txt
howtext.txt
thispage.txt
todo.txt
download.txt
sflogo.txt

What is the Makefile?

The Makefile tells the make utility how to build faq.html. When make is executed it checks to see if any of the files on which faq.html depends has been modified since the last time faq.html was built. If so, make rebuilds faq.html; if not, make does nothing.

Simply type make at the shell prompt. Or, you may want to try working like I do. I have a browser window open displaying faq.html. In another window, I work on the FAQ text files using my editor of choice, vim. From within vim I can type :mak and make is executed. Then I refresh my browser window and my changes are immediately visible.

faq.html uses a rather simple Makefile:

CMD = ./makefaq.pl
COMMON = makefaq.pl faq.tmpl faq.ini faq.ooq

faq: faq.html

faq.html: ${COMMON} *.txt
	${CMD} faq.ini

How are the Q & A text files structured?

The Question is on the first line, followed by a blank line, followed by the Answer. Here is faqtmpl.txt (with Textile markup, and line breaks added for readability):

What is @faq.tmpl@?

@faq.tmpl@ is the template that describes the structure of the
 HTML(HyperText Markup Language) FAQ(Frequently Asked Questions) page.
 It is used by the Perl module
 "@HTML::Template@":search.cpan.org/~samtregar/HTML-Template-2.9/.

Was this page generated with makefaq.pl?

Indeed it was.

How do you plan to improve makefaq.pl?

I need to improve portability and test makefaq.pl on platforms other than Linux.

I would like to (optionally) list all the Questions at the top of the page, linking each Question to the Q & A in the body of the page.

It should be straightforward to make simplified markup schemes other than Textile optional.

Where can I get a copy of makefaq.pl?

Monitor the SourceForge Project Page. When I get through everything on the list that follows, you'll be able to download makefaq.pl from SourceForge.

~~Register project with SourceForge~~
~~Get this web page up on the SourceForge~~ Project Website
~~Get project source files into the SourceForge~~ Subversion Repository
~~Learn how to build a SourceForge Release~~
~~Release the first pass of makefaq.pl~~ Download Page