makefaq Frequently-Asked Questions

For more information about this faq, please contact EDIT FAQHEADER.HTML AND PUT YOUR NAME AND CONTACT INFO HERE

FAQ Revised: Sunday 29 February 2004 02:21:00

Table of Contents

1. General
2. Data
3. Programming

1. General

1.1. What is the purpose of this program?
To build a Frequently-Asked-Question page in either HTML or text.

1.2. Who wrote it?
Dan York wrote the initial program and released it. Dave Seidel then modified it to include configuration classes and other substantial changes. Dan integrated those changes with his... and released it.

1.3. Why was the program written?
Dan was updating the FAQ for the Linux Professional Insititute and didn't want to manually update the page. Simultaneously, he was trying to learn more about python and specifically about classes... and he had a long airplane ride ahead of him... so he wrote the code. Dave was looking to create a FAQ for his BEAST/BSE web site and was looking to learn more about python, so he took Dan's code and changed it almost beyond recognition!

1.4. Is there a web page for this program?
Yes, http://www.makefaq.org/.

1.5. Why the jump from version number 0.5 to number 2.0?
I would like to move to a more typical release plan of major version numbers and minor point releases. With the major change of the new data file format, this release definitely warrants a change in the major version number. However, releasing it as version 1.0 gives the impression that this is a brand-new program, i.e., the first release, when in fact the code is at this point quite mature. It was a mistake for me to start out the first releases as 0.x. As they really should have been the 1.x series, this jump to 2.0 is designed to correct that mistake.

1.6. I am writing my FAQ in a language other than English. Will makefaq give me the data and time in the format appropriate for my language?
Yes. At this point, makefaq looks for the LANG environment variable defined in your operating system. If it is there, makefaq uses the value of LANG for your locale and will use that to generate the appropriate time/date string. Note that in some instances, it will also automatically replace the text strings "FAQ Revised" and "Table of Contents" with the appropriate text strings. Currently, these strings are only defined for English, German, French and Brazilian Portugeuse. If you are in a different locale, you will get the appropriate time/date string and the English text strings. Note that if makefaq cannot determine your locale, it will default to US English ('en_US').

1.7. What if I want to use a specific locale that is different from what my LANG environment variable is set to?
You can use the '-L' command-line option to specify a locale. See the README file for more details.

2. Data

2.1. Do I have to call the data file faq.dat?
That is the default file name used in all of the current configurations. If you want to change the file name, you can modify the configurations in the actual source code or use the '-i' command line option.

2.2. What does the data file look like?
A plain text file. Each entry consists of a category name, question, and answer separated by XML-ish tags <c>, <q>, <a>. HTML can be used in both the question and answer sections of the line. The category, question and answer can still all be on a single line, or can be spread out over many other lines. You can see the faq.dat that generated this file here.

2.3. If you say this is "XML-ish", are there end tags as there would be in XML?
No, there are no end tags in the data file format. You simply begin with <c> and the category field is considered to have ended when the program finds the <q> tag. The question field is ended by the <a> tag, and the answer section is ended by either the next <c> or the end of the file.

2.4. Do I have to use <c>, <q>, and <a> as the tags in the data file?
Those are the default settings and there is no command-line way to change them. If you wish to use some other delimiters, you will need to change the makefaq.py code itself. See the README file for more information.

2.5. Is there a limit to the length of an answer?
No. It can be as long as you like.

2.6. Do all questions for a category have to be together in the data file?
No, the program will build the questions for each category as it reads the entire file. So the questions can be in any order. You may find it best for your own sanity to group them together in the data file, but that's another issue.

2.7. How many categories can I have?
As many as you like.

2.8. Can I still use the old, single-line file format?
Yes, however you must use the '-r 1' command-line option to tell makefaq to "revert" to using the old data file format.

2.9. If I am still using the old, single-line format, do I have to use the pipe as the delimiter?
No, you can use another character as the delimiter in the data file. You simply have to use the '-d' command-line option to provide makefaq with the new character. Remember that you need to use '-r 1' to use the old format.

2.10. Why '-r 1' and not just '-r'?
A future version of makefaq will use a pure XML format and at that time (but not now) using '-r 2' will let you use files in this current pseudo-XML format.

3. Programming

3.1. Why python?
Why not? It's easy and fun.... visit www.python.org for more information.

3.2. Are there enhancements you would like to add?
Subsequent revisions have tackled most of the enhancements I was seeking to add. At the moment, the only real enhancements I would like to add are:

3.3. Can I modify this program?
Sure, go ahead. It's licensed under the GNU General Public License. I'd ask you just to send back modifications so that I can pass them along to others.

3.4. Does the program do any error-checking?
The program does basic error checking to see if the files exist and can be written, and also does some very simplistic checking on the formatting for the data file.

Copyright (c) 2002 Dan York CHANGE THIS TO YOUR NAME

This list of questions and answers was generated by makefaq.

To modify this footer for your own use, the copyright and such can be changed in faqfooter.html