forked from danyork/makefaq
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathfaq.html
187 lines (172 loc) · 10.8 KB
/
faq.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
<html>
<head>
<!-- Change this title to something more appropriate for your FAQ. You
do NOT need to leave the reference to makefaq.py in there. -->
<title>Frequently-Asked Questions built by makefaq.py</title>
<!-- If you do not want to use a CSS stylesheet, remove this next line. -->
<link type="text/css" rel="stylesheet" href="faq.css">
</head>
<body bgcolor="#FFFFFF">
<h1>
<!-- Change this text line below to something more appropriate -->
<code>makefaq</code> Frequently-Asked Questions
</h1>
<!-- Change this line to have your contact information in it. -->
<p>For more information about this faq, please contact <b>EDIT FAQHEADER.HTML
AND PUT YOUR NAME AND CONTACT INFO HERE</b>
<hr>
<p><i>FAQ Revised: Wednesday 28 January 2009 22:39:43</i></p>
<hr><h2>Table of Contents</h2>
<dl>
<dt><b>1. General</b></dt>
<dd><ul>
<li><a href="#General0">1.1. What is the purpose of this program?</a></li>
<li><a href="#General1">1.2. Who wrote it?</a></li>
<li><a href="#General2">1.3. Why was the program written?</a></li>
<li><a href="#General3">1.4. Is there a web page for this program?</a></li>
<li><a href="#General4">1.5. Why the jump from version number 0.5 to number 2.0?</a></li>
<li><a href="#General5">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?</a></li>
<li><a href="#General6">1.7. What if I want to use a specific locale that is different from what my
LANG environment variable is set to?</a></li>
</ul></dd>
<dt><b>2. Data</b></dt>
<dd><ul>
<li><a href="#Data0">2.1. Do I have to call the data file <code>faq.dat</code>?</a></li>
<li><a href="#Data1">2.2. What does the data file look like?</a></li>
<li><a href="#Data2">2.3. If you say this is "XML-ish", are there end tags as there would be in XML?</a></li>
<li><a href="#Data3">2.4. Do I have to use <c>, <q>, and <a> as the tags in
the data file?</a></li>
<li><a href="#Data4">2.5. Is there a limit to the length of an answer?</a></li>
<li><a href="#Data5">2.6. Do all questions for a category have to be together in the data file?</a></li>
<li><a href="#Data6">2.7. How many categories can I have?</a></li>
<li><a href="#Data7">2.8. Can I still use the old, single-line file format?</a></li>
<li><a href="#Data8">2.9. If I am still using the old, single-line format, do I have to use the
pipe as the delimiter?</a></li>
<li><a href="#Data9">2.10. Why '-r 1' and not just '-r'?</a></li>
</ul></dd>
<dt><b>3. Programming</b></dt>
<dd><ul>
<li><a href="#Programming0">3.1. Why python?</a></li>
<li><a href="#Programming1">3.2. Are there enhancements you would like to add?</a></li>
<li><a href="#Programming2">3.3. Can I modify this program?</a></li>
<li><a href="#Programming3">3.4. Does the program do any error-checking?</a></li>
</ul></dd>
</dl>
<hr><h2>1. General</h2>
<dl>
<dt><b><a name="General0">1.1. What is the purpose of this program?</a></b></dt>
<dd>To build a Frequently-Asked-Question page in either HTML or text.<br><br></dd>
<dt><b><a name="General1">1.2. Who wrote it?</a></b></dt>
<dd><a href="mailto:[email protected]">Dan York</a> wrote the initial program and released it. <a href="mailto:[email protected]">Dave Seidel</a> then modified it to include configuration classes and other substantial changes. Dan integrated those changes with his... and released it.<br><br></dd>
<dt><b><a name="General2">1.3. Why was the program written?</a></b></dt>
<dd>Dan was updating the FAQ for the <a href="http://www.lpi.org/">Linux
Professional Insititute</a> and didn't want to manually update the page.
Simultaneously, he was trying to learn more about
<a href="http://www.python.org">python</a> 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 <a href="http://beast.gtk.org/">
BEAST/BSE</a> web site <i>and</i> was looking to learn more about python,
so he took Dan's code and changed it almost beyond recognition!<br><br></dd>
<dt><b><a name="General3">1.4. Is there a web page for this program?</a></b></dt>
<dd>Yes, <a href="http://www.makefaq.org/">http://www.makefaq.org/</a>.<br><br></dd>
<dt><b><a name="General4">1.5. Why the jump from version number 0.5 to number 2.0?</a></b></dt>
<dd>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 <i>1.0</i> 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.<i>x</i>. As they really
should have been the 1.<i>x</i> series, this jump to 2.0 is designed to correct
that mistake.<br><br></dd>
<dt><b><a name="General5">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?</a></b></dt>
<dd>Yes. At this point, makefaq looks for the <b>LANG</b> environment variable
defined in your operating system. If it is there, makefaq uses the value of LANG
for your <i>locale</i> and will use that to generate the appropriate time/date string.
Note that in some instances, it will <i>also</i> 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').<br><br></dd>
<dt><b><a name="General6">1.7. What if I want to use a specific locale that is different from what my
LANG environment variable is set to?</a></b></dt>
<dd>You can use the '-L' command-line option to specify a locale. See the README
file for more details.<br><br></dd>
</dl>
<hr><h2>2. Data</h2>
<dl>
<dt><b><a name="Data0">2.1. Do I have to call the data file <code>faq.dat</code>?</a></b></dt>
<dd>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.<br><br></dd>
<dt><b><a name="Data1">2.2. What does the data file look like?</a></b></dt>
<dd>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
<a href="faq.dat">faq.dat</a> that generated this file here.<br><br></dd>
<dt><b><a name="Data2">2.3. If you say this is "XML-ish", are there end tags as there would be in XML?</a></b></dt>
<dd>No, there are <i>no</i> 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.<br><br></dd>
<dt><b><a name="Data3">2.4. Do I have to use <c>, <q>, and <a> as the tags in
the data file?</a></b></dt>
<dd>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.<br><br></dd>
<dt><b><a name="Data4">2.5. Is there a limit to the length of an answer?</a></b></dt>
<dd>No. It can be as long as you like.<br><br></dd>
<dt><b><a name="Data5">2.6. Do all questions for a category have to be together in the data file?</a></b></dt>
<dd>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.<br><br></dd>
<dt><b><a name="Data6">2.7. How many categories can I have?</a></b></dt>
<dd>As many as you like.<br><br></dd>
<dt><b><a name="Data7">2.8. Can I still use the old, single-line file format?</a></b></dt>
<dd>Yes, however you must use the '-r 1' command-line option to tell makefaq to
"revert" to using the old data file format.<br><br></dd>
<dt><b><a name="Data8">2.9. If I am still using the old, single-line format, do I have to use the
pipe as the delimiter?</a></b></dt>
<dd>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.<br><br></dd>
<dt><b><a name="Data9">2.10. Why '-r 1' and not just '-r'?</a></b></dt>
<dd>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.<br><br></dd>
</dl>
<hr><h2>3. Programming</h2>
<dl>
<dt><b><a name="Programming0">3.1. Why python?</a></b></dt>
<dd>Why not? It's easy and fun.... visit <a href="http://www.python.org/">www.python.org</a> for more information.<br><br></dd>
<dt><b><a name="Programming1">3.2. Are there enhancements you would like to add?</a></b></dt>
<dd>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:
<ul>
<li>moving to a pure XML format for the data file</li>
<li>if not moving to pure XML, at least modifying the data file format to be case-insensitive, i.e. allowing both
<c> and <C></li>
<li>modifying the text mode output to insert a line break after a certain number
of characters</li>
</ul><br><br></dd>
<dt><b><a name="Programming2">3.3. Can I modify this program?</a></b></dt>
<dd>Sure, go ahead. It's licensed under the <a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License</a>. I'd ask you just to send back modifications so that I can pass them along to others.<br><br></dd>
<dt><b><a name="Programming3">3.4. Does the program do any error-checking?</a></b></dt>
<dd>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.<br><br></dd>
</dl>
<hr>
<p>Copyright (c) 2002 Dan York <b>CHANGE THIS TO YOUR NAME</b></p>
<!-- You do NOT have to keep this line below in here. I have no issue if
you wish to remove it. -->
<p><i>This list of questions and answers was generated by
<a href="http://www.makefaq.org/">makefaq</a>.</i>
<p><i>To modify this footer for your own use, the copyright and such
can be changed in <code>faqfooter.html</code></i></p>
</body>
</html>