-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathFAQ.html
More file actions
279 lines (215 loc) · 8.76 KB
/
FAQ.html
File metadata and controls
279 lines (215 loc) · 8.76 KB
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
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
<!-- This page was generated automatically with FAQtor.py -->
<a name="#top"></a>
<html>
<head><title>Your Project FAQ</title></head>
<body bgcolor="white">
<center><h1>Your Project Name Frequently Asked Questions</h1></center>
<center><h3>Maintained by <A HREF="mailto:dan.nygren@gmail.com">
dan.nygren@gmail.com</A></h3></center>
<center><h3>Last updated: 02 Dec 2021 </h3></center>
<table border="0">
<tr><th colspan="2" align="left"> <br>About</th></tr>
<tr><td>Q. 1.0 </td><td valign="top"><a href="#1_0">What is FAQtor?
</a></td></tr>
<tr><td>Q. 1.1 </td><td valign="top"><a href="#1_1">What does FAQtor do?
</a></td></tr>
<tr><td>Q. 1.2 </td><td valign="top"><a href="#1_2">Can you show me a webpage that uses FAQtor?
</a></td></tr>
<tr><td>Q. 1.3 </td><td valign="top"><a href="#1_3">Who developed FAQtor?
</a></td></tr>
<tr><td>Q. 1.4 </td><td valign="top"><a href="#1_4">Why didn't you feed back these changes to the original FAQtor?
</a></td></tr>
<tr><th colspan="2" align="left"> <br>Usage</th></tr>
<tr><td>Q. 2.0 </td><td valign="top"><a href="#2_0">What do I need in order to use FAQtor?
</a></td></tr>
<tr><td>Q. 2.1 </td><td valign="top"><a href="#2_1">How do I run FAQtor?
</a></td></tr>
<tr><td>Q. 2.2 </td><td valign="top"><a href="#2_2">I ran FAQtor and got an error. What do I do?
</a></td></tr>
<tr><td>Q. 2.3 </td><td valign="top"><a href="#2_3">What does the XML input file look like?
</a></td></tr>
<tr><td>Q. 2.4 </td><td valign="top"><a href="#2_4">What does the config file look like?
</a></td></tr>
<tr><td>Q. 2.5 </td><td valign="top"><a href="#2_5">Why would I want to use a config file if it's optional?
</a></td></tr>
<tr><th colspan="2" align="left"> <br>XML input file</th></tr>
<tr><td>Q. 3.0 </td><td valign="top"><a href="#3_0">What is the structure of the XML input file in?
</a></td></tr>
<tr><td>Q. 3.1 </td><td valign="top"><a href="#3_1">How do I refer to answers (from other documents or from within the FAQ itself)?
</a></td></tr>
<tr><th colspan="2" align="left"> <br>Configuration File (optional)</th></tr>
<tr><td>Q. 4.0 </td><td valign="top"><a href="#4_0">What format is the configuration file in?
</a></td></tr>
</table>
<hr>
<h1 id="About">About</h1>
<a name="1_0"></a>
<h2>A. 1.0 What is FAQtor?
</h2><br>FAQtor is short for "Frequently Asked Questions generaTOR".
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="1_1"></a>
<h2>A. 1.1 What does FAQtor do?
</h2><br>FAQtor is a python script that enables you to easily create and maintain a list
of questions and answers in a configurable format.
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="1_2"></a>
<h2>A. 1.2 Can you show me a webpage that uses FAQtor?
</h2><br>The page you are viewing was generated by FAQtor
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="1_3"></a>
<h2>A. 1.3 Who developed FAQtor?
</h2><br><a href="http://www.phil-schwartz.com">Phil Schwartz</a>
<p>
Dan Nygren made a few additions to Phil's excellent work to allow pointing a
reader to a particular section of the FAQ (e.g.
http://www.example.com/FAQ.html#About ), set the date last updated
automatically, support for Python 2.7, and then Python 3.X .
</p>
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="1_4"></a>
<h2>A. 1.4 Why didn't you feed back these changes to the original FAQtor?
</h2><br>I did make an attempt, but was unable to successfully do so. Hosting my
changes per the license on github seemed to be the right thing to do.
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<h1 id="Usage">Usage</h1>
<a name="2_0"></a>
<h2>A. 2.0 What do I need in order to use FAQtor?
</h2><br>Python 3 is required. FAQtor was tested with Python 3.5.3
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="2_1"></a>
<h2>A. 2.1 How do I run FAQtor?
</h2><br><pre>
$ python faqtor.py yourfaq.xml [yourconfig.cfg]
</pre>
<p>
A makefile has been provided to allow this to be done easier and keep all the
FAQtor files in a FAQ subdirectory and move the generated FAQ.html to the main
directory.
</p>
<pre>
$ make
faqtor.py FAQ.xml FAQ.cfg
chmod u=rw,g=r,o=r FAQ.html
cp -p FAQ.html ..
</pre>
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="2_2"></a>
<h2>A. 2.2 I ran FAQtor and got an error. What do I do?
</h2><br>Most errors are caused by a question, answer, or section tag not being matched
by a corresponding closing tag.
<p>
Another common error is using an & instead of <tt> &amp;</tt> for an
ampersand etc. Consult a list of HTML character codes to make sure you are not
using a character that must be encoded.
</p>
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="2_3"></a>
<h2>A. 2.3 What does the XML input file look like?
</h2><br>The FAQtor FAQ was generated with this XML file.
See <a href="./FAQ.xml">FAQ.xml</a> in the FAQtor source distribution.
The XML input file can contain HTML so I often have preformatted text sections
to show portions of screen dumps:
<pre>
prompt> mycommand | grep ':CA' | sed 's/+//' | sed 's/;//' \
| sed 's/^[ \t]*//;s/[ \t]*$//' | sort | uniq
FRU-Part-Number:CA01022-0680 05D /371-2227-04
FRU-Part-Number:CA01022-0690 10G /371-2219-07
FRU-Part-Number:CA06620-D023 A0 /371-2215-01
FRU-Part-Number:CA06620-D342 B0 /371-2228-02
FRU-Part-Number:CA06620-D382 A0 /371-2239-01
</pre>
... horizontal rules
<hr />
<strong>
Items that need to be strongly pointed out
</strong>
<hr />
<em>
Emphasized areas of text.
</em>
<hr />
... or lists:
<ul>
<li> Feature A </li>
<li> Feature B </li>
<li> Feature C </li>
</ul>
<hr />
<h3>
Headings
</h3>
<hr />
<h4>
Different Headings
</h4>
<hr />
I also like to include a source for my information at the end of an answer so a
reader knows where the information in the answer came from.
<p>
(Source: Dan Nygren)
</p>
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="2_4"></a>
<h2>A. 2.4 What does the config file look like?
</h2><br>The FAQtor FAQ s also generated using the config file in the FAQtor source
distribution. This file is optional. If not supplied, defaults are provided.
See the <a href="./FAQ.cfg">FAQ.cfg</a> file in the FAQtor source distribution.
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="2_5"></a>
<h2>A. 2.5 Why would I want to use a config file if it's optional?
</h2><br>Although FAQtor will use defaults, it is recommended that you create a config
file to customize the layout of the FAQ.
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<h1 id="XML input file">XML input file</h1>
<a name="3_0"></a>
<h2>A. 3.0 What is the structure of the XML input file in?
</h2><br>Please refer to the <a href="./README_xml">README_xml</a> in the FAQtor source
distribution
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<a name="referring to answers"></a>
<a name="3_1"></a>
<h2>A. 3.1 How do I refer to answers (from other documents or from within the FAQ itself)?
</h2><br>In the XML input file, within each answer section that you wish to refer to you
must assign a name-value entity. Only answers that you wish to refer to require
this additional syntax, which looks like this:
<pre>
<a href="www.example.com/FAQ.html#referring to answers">Referring to Answers</a>
http://www.example.com/FAQ.html#referring to answers
file:///home/dnygren/FAQtor/FAQ.html#referring to answers
</pre>
<p>
Now, anywhere you wish to refer to it, you simply use the anchor with the name
you just created. This name can be anything as long as it adheres to HTML
syntax rules.
</p>
You can use the URL in the summary of questions at the top of the FAQ, however
this can result in pointing to the wrong question if you don't add questions
sequentially and then get the question numbers out of order.
<pre>
<a href="www.example.com/FAQ.html#3_1">Referring to Answers</a>
http://www.example.com/FAQ.html#3_1
file:///home/dnygren/SW/Git/FAQtor/FAQ.html#3_1
</pre>
<a href="#top"><p align="right">Return to top </p></a>
<hr>
<h1 id="Configuration File (optional)">Configuration File (optional)</h1>
<a name="4_0"></a>
<h2>A. 4.0 What format is the configuration file in?
</h2><br>The config file uses a standard Windows INI file format. For more information
on the config file, please refer to README.cfg in the FAQtor source
distribution.
<a href="#top"><p align="right">Return to top </p></a>
<hr>
</body></html>