Skip to content

Latest commit

 

History

History

doc

README.FAQ

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 (https://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 $