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.html
is set with a simple text file, and that order can be easily changed.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.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.
makefaq.pl