doc/README.FAQ

   1
   2 Contents
   3 --------
   4
   5 * Building the FAQ
   6 * File List
   7 * A quick note on the syntax of faq.xml
   8
   9
  10
  11
  12 Building the FAQ
  13 ----------------
  14
  15 This FAQ is written in XML and translated to HTML using an XSL stylesheet.
  16 The XML source is processed using James Clark's (http://www.jclark.com/)
  17 XSLT processor XT and XML parser XP.
  18
  19 The XSL stylesheet used to generate the HTML version is here (faq.xsl).
  20
  21 The text version is generated in three steps: first, an XSL stylesheet
  22 (faq-txt.xsl) is used to generate a simple HTML. Then, a second XSL
  23 stylesheet (faq-txt-pass2.xsl) transforms the HTML into plain text. An awk
  24 script (faq-txt.awk) then performs the word wrapping.
  25
  26
  27
  28
  29 File list
  30 ---------
  31
  32 README.FAQ                This file
  33 faq.xml                   The source of the FAQ
  34 faq.dtd                   The DTD to which conforms faq.xml
  35
  36 faq.xsl                   Stylesheet to convert faq.xml into HTML files
  37
  38 faq-txt.xsl               Generation of faq.txt, first pass
  39                           Stylesheet to convert faq.xml into faq-txt.html
  40 faq-txt.dtd               The DTD to which conforms faq-txt.html
  41 faq-txt-pass2.xsl         Generation of faq.txt, second pass
  42                           Stylesheet to convert faq-txt-html into faq-txt-tmp.txt
  43 faq-txt.awk               Generation of faq.txt, third pass
  44                           An AWK program for performing word wrapping
  45 Makefile                  Used to generate the FAQ via 'make'
  46
  47
  48
  49 Other files are generated ones :
  50
  51 *.shtml                   The faq in HTML format
  52 faq-txt.html              Generated by pass 1 during generation of faq.txt
  53 faq-txt-tmp.txt           Generated by pass 2 during generation of faq.txt
  54 faq.txt                   The faq in text version
  55
  56
  57
  58
  59
  60 A quick note on the syntax of faq.xml
  61 -------------------------------------
  62
  63
  64 This XML file is based on the DTD specified in "faq.dtd". See "faq.dtd" for
  65 a rigourous definition; a simple overview is given here, to help in making
  66 quick additions and modifications.
  67
  68 The FAQ is composed of two parts : a <head> and a <body>. The <head>
  69 contains the title (in our case, "NEdit Frequently Asked Questions"), the
  70 list of <maintainers>, a <summary> which gets displayed ahead of all
  71 questions, a section showing how to download the FAQ (<download>) and
  72 other, less important stuff.
  73
  74 The <body> part is composed of many FAQ <section>s. A section has a title
  75 and groups several FAQ entries. A particular section exists, called
  76 <about-section>, which contains the description of the FAQ itself.
  77
  78 A section is generally composed of several "Question 'N' Answer" entries
  79 (<qna>). A <qna> contains a question (<q>) and the answer to that question
  80 (<a>). An identifier must be given to each <qna>, via the attribute "id". A
  81 longer version of the question may be specified via <long-q> as another
  82 element of <qna>; in this case, the <q> is displayed in a table of
  83 questions, while the longer and more complete version, <long-q>, is
  84 displayed along with the answer.
  85
  86 The <long-q> and <a> elements contain text paragraphs. The <q> doesn't
  87 contain paragraphs and behaves like a single paragraph itself.
  88
  89 A text paragraph is indicated by one of the elements <p>, <blockquote>,
  90 <ul>, <ol> and <pre> (which, in the DTD, are collectively referred to as
  91 %paragraph-styles;).
  92
  93    The <p> denotes a basic paragraph and contains text.
  94
  95    The <blockquote> indicates an indent, and it contains other paragraphs
  96    inside. A nested <blockquote> will indent relative to the previous one.
  97
  98    The <ul> and <ol> indicate respectively an unnumbered and a numbered
  99    list. Both <ul> and <ol> contain one or many <li> elements. A <li>
 100    element contains text.
 101
 102    The <pre> indicates a preformatted piece of text, which will be output
 103    with no further modifications.
 104
 105 Paragraphs of type <p> and <li>, as well as <q> and a few other elements of
 106 the <head>, contain text. Text is composed of free text and style elements.
 107 The style elements are the following :
 108
 109    <email> indicates an e-mail address.
 110
 111    <img> indicates an image. It has a required attribute "src" which must
 112    be a URL referring to the image, and a "alt" attribute containing
 113    alternate text, used for non-image-capable formats.
 114
 115    <site> indicates a web site. The text between <site> and </site> must be
 116    a URL.
 117
 118    <link> indicates a HTTP hyperlink. Its required attribute "href" must be
 119    the URL to link to. An attribute "alt" may contain alternate text.
 120
 121    <em> stands for emphasized text.
 122
 123    <strong> stands for strong text.
 124
 125    <tt> is used for terminal output and for the contents of configuration
 126    files.
 127
 128    <code> is used for command names, when included inline within text.
 129    Generally, <pre> paragraphs are used for several lines of code.
 130
 131 The distinction between <tt> and <code> and furthermore <pre> is not so
 132 clear. A clearer and better definition is needed.
 133
 134 $Id: README.FAQ,v 1.3 2002/09/26 12:37:37 ajhood Exp $