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
|
Contents
--------
* Building the FAQ
* File List
* A quick note on the syntax of faq.xml
Building the FAQ
----------------
This FAQ is written in XML and translated to HTML using an XSL stylesheet.
The XML source is processed using James Clark's (http://www.jclark.com/)
XSLT processor XT and XML parser XP.
The XSL stylesheet used to generate the HTML version is here (faq.xsl).
The text version is generated in three steps: first, an XSL stylesheet
(faq-txt.xsl) is used to generate a simple HTML. Then, a second XSL
stylesheet (faq-txt-pass2.xsl) transforms the HTML into plain text. An awk
script (faq-txt.awk) then performs the word wrapping.
File list
---------
README.FAQ This file
faq.xml The source of the FAQ
faq.dtd The DTD to which conforms faq.xml
faq.xsl Stylesheet to convert faq.xml into HTML files
faq-txt.xsl Generation of faq.txt, first pass
Stylesheet to convert faq.xml into faq-txt.html
faq-txt.dtd The DTD to which conforms faq-txt.html
faq-txt-pass2.xsl Generation of faq.txt, second pass
Stylesheet to convert faq-txt-html into faq-txt-tmp.txt
faq-txt.awk Generation of faq.txt, third pass
An AWK program for performing word wrapping
Makefile Used to generate the FAQ via 'make'
Other files are generated ones :
*.shtml The faq in HTML format
faq-txt.html Generated by pass 1 during generation of faq.txt
faq-txt-tmp.txt Generated by pass 2 during generation of faq.txt
faq.txt The faq in text version
A quick note on the syntax of faq.xml
-------------------------------------
This XML file is based on the DTD specified in "faq.dtd". See "faq.dtd" for
a rigourous definition; a simple overview is given here, to help in making
quick additions and modifications.
The FAQ is composed of two parts : a <head> and a <body>. The <head>
contains the title (in our case, "NEdit Frequently Asked Questions"), the
list of <maintainers>, a <summary> which gets displayed ahead of all
questions, a section showing how to download the FAQ (<download>) and
other, less important stuff.
The <body> part is composed of many FAQ <section>s. A section has a title
and groups several FAQ entries. A particular section exists, called
<about-section>, which contains the description of the FAQ itself.
A section is generally composed of several "Question 'N' Answer" entries
(<qna>). A <qna> contains a question (<q>) and the answer to that question
(<a>). An identifier must be given to each <qna>, via the attribute "id". A
longer version of the question may be specified via <long-q> as another
element of <qna>; in this case, the <q> is displayed in a table of
questions, while the longer and more complete version, <long-q>, is
displayed along with the answer.
The <long-q> and <a> elements contain text paragraphs. The <q> doesn't
contain paragraphs and behaves like a single paragraph itself.
A text paragraph is indicated by one of the elements <p>, <blockquote>,
<ul>, <ol> and <pre> (which, in the DTD, are collectively referred to as
%paragraph-styles;).
The <p> denotes a basic paragraph and contains text.
The <blockquote> indicates an indent, and it contains other paragraphs
inside. A nested <blockquote> will indent relative to the previous one.
The <ul> and <ol> indicate respectively an unnumbered and a numbered
list. Both <ul> and <ol> contain one or many <li> elements. A <li>
element contains text.
The <pre> indicates a preformatted piece of text, which will be output
with no further modifications.
Paragraphs of type <p> and <li>, as well as <q> and a few other elements of
the <head>, contain text. Text is composed of free text and style elements.
The style elements are the following :
<email> indicates an e-mail address.
<img> indicates an image. It has a required attribute "src" which must
be a URL referring to the image, and a "alt" attribute containing
alternate text, used for non-image-capable formats.
<site> indicates a web site. The text between <site> and </site> must be
a URL.
<link> indicates a HTTP hyperlink. Its required attribute "href" must be
the URL to link to. An attribute "alt" may contain alternate text.
<em> stands for emphasized text.
<strong> stands for strong text.
<tt> is used for terminal output and for the contents of configuration
files.
<code> is used for command names, when included inline within text.
Generally, <pre> paragraphs are used for several lines of code.
The distinction between <tt> and <code> and furthermore <pre> is not so
clear. A clearer and better definition is needed.
$Id: README.FAQ,v 1.3 2002/09/26 12:37:37 ajhood Exp $
|
