make_faq

	make_faq

"Faq-maker, Faq-maker, make me a Faq..."

What is it?

An HTML generator that builds chunks/chapters/questions-and-answers or whatever, and builds indexes to hold it all together. It's common usage is to build FAQ (Frequently Asked Questions) HTML from text documents.

The script reads in plain text files, and then indexes sections or chapters or questions in that file and puts that index at the top of an HTML file (like a table of contents) which then link down into the file. Furthermore, it will do this for a number of files and create a global index/table of contents. This is difficult to explain, so it's better to just see some examples, but keep in mind that this can be used for more general purpose tasks than just FAQ building.

Features:

Generic purpose - can be configured to build a FAQ, write a book, make some toast..
Configuration script can contain includes or variables that get expanded
Simple, small, and easy to modify or improve.

License:

This software is essentially free, but please read my payment spiel
Please read the full license

Examples:

I use it to generate the DaveFAQ and my new experiment DaveHistory.

As a specific example, Section 2 of the DaveFAQ is generated from a simple text file. The configuration file is a little more complicated, but keep in mind that it needs to hold all the extra header and footer HTML.

Download:

It's a single perl script.

Documentation?

The input to make_faq is a bunch of text files and a single config file. For this example, we'll deal with the common task of building a FAQ. First you create a bunch of questions. In this case we'll designate new questions by a line starting with "q: " and we'll put the topic of this file (or section) on the first line.

    Chapter One - Monty's Questions

    q:  What is your quest?
    I seek the holy grail

    q:  What is your favorite color?
    Blue

We create a few files like this, let's name them txt_1, txt_2, etc..
Now we need to configure how they are built. The configuration file is a list of keys and their values. The following syntaxes will work:

    Some_String  =  blah
    Multiline_String  =    "this
                            is many
                            lines"
    Another_Quoting   =    'or use halfquotes
                            if you need to include
                            "doublequotes"
                           in your string'
    Another_Quoting   =    'but don't worry, 'quotes' only
                            end a string at the end of a line.'

We can also use some tricks in our conf file to save typing:

    # shell style comments are okay
    Name = David Ljung Madison
    Hello = Hi, my name is conf(Name)   # Replaces with configuration value 'Name'
                                        # And no, order is not important.

    Bad_Idea = include_file(/etc/passwd)	# Can include files

    # Header is special, it can do a few things:
    Header = SPACE_OUT(Hi there)	# Spaces out text using &nbsp;
    Header = Section $NUMBER		# Replaced with a string version of
					# the section number ("one","two",..)
    Header = Topic $TOPIC		# Replaced with the topic
    File = This file is saved in $OUT	# Path of the current file

All of this goes in a file called conf. You need to define the following:

New_Chunk: Indicates the start of a new chunk/question/paragraph. For a faq, use something like 'q:'
Short_Index: Name of the short index file (just links to the chapters)
Long_Index: Name of the long index, links to chapters and chunks/questions
Text_Files: Our list of text files (can use glob characters). Make sure each filename ends with the section number. Suggested value: "txt_*"
Header: The HTML header for each section
Footer: The HTML footer for each section
Short_Header/Short_Footer: HTML header/footer for short index, if you want it to be the same as the section header you could just do: Short_Header = conf(Header)
Long_Header/Long_Footer: For long index

You can invent any other "variables" in the conf file to be used by other conf variables to reduce the size of the file (using conf(..))

There's one last trick, since the Short_Header and Long_Header are likely to be the same except for their linking to each other, you can refer to the other by name with $OTHER and by link with $OTHER_HTML.
In other words, you can do something like this:

    Short_Header = "
      Blah blah blah..
      <a href=$OTHER_HTML>$OTHER Index</a>
      "
    Long_Header = conf(Short_Header)

It might help to snag the conf file from DaveFAQ and using it as a starting point.

Requires:

Perl, which kicks ass

Install

It's just a perl script. No install required.

Revision History:

See the CHANGELOG

Bugs:

Not a chance.

Freshmeat?

You bet.