Subject: Re: FAQs?

From: [email-masked] (Jeffrey McArthur)
Date: Sun, 04 Dec 1994 21:01:18

>2) Has anyone done a FAQ DTD? I've been looking for tools to help
>maintain them, and have about decided that I'm going to have to write
>my own. This would seem to be a perfect application for SGML.
>Suggestions on what it should be would be greatly appreciated.

From:   Jeffrey C. Ollie     To: [email-masked]
Reply:  [email-masked], [email-masked],, [email-masked],,
j_mcarthur@bix
Date:   Fri, 03 Jun 1994 17:41:42 -0500
Subj:   Re: Pseudo-FAQ
____________________________________________________________

I've made some (what I think are) improvements to the FAQ DTD.  I've included
it below, as well as a .desc file for dtd2html.
--
Jeffrey C. Ollie
[email-masked]
http://caesar.cs.uiowa.edu/~jollie/

---------------------------------------------
<!--
  This is a proposed DTD for writing frequently asked questions.
  Original version 2 June 1994 by Jeffrey C. Ollie ([email-masked])
  Last modified 3 June 1994
  Proposed public identifier:
  +//ISBN 82-7640-023//DTD Frequently Asked Questions//EN//19940603
-->
<!ELEMENT faq - - (head, body)>
<!ELEMENT head - - (title, maintain, hdr*, althdr*, archive*)>
<!ELEMENT archive - O (#PCDATA)>
<!ATTLIST archive
          href    CDATA  #REQUIRED
          type    CDATA  #IMPLIED>
<!ELEMENT body - - (section+ | qna+)>
<!ELEMENT title - - (#PCDATA)>
<!ELEMENT maintain - - (name, email)>
<!ELEMENT name - O (#PCDATA)>
<!ELEMENT email - O (#PCDATA)>
<!ELEMENt content - - (#PCDATA)>
<!ELEMENT (hdr|althdr) - - (type, content)>
<!ELEMENT section - - (title, qna+)>
<!ELEMENT qna - O (q, a)>
<!ELEMENT q - O (#PCDATA)>
<!ELEMENT a - O (p+)>
<!ELEMENT p O O ((#PCDATA|link)*)>
<!ELEMENT link - - (#PCDATA)>
<!ATTLIST link
          name  CDATA  #IMPLIED
          href  CDATA  #IMPLIED>
<!ELEMENT type - O (#PCDATA)>
<!ENTITY  pstart STARTTAG "p">

<!SHORTREF amap '&#RS;&#RE;' pstart>
<!USEMAP   amap a>
------------------------------------------------------------
<?DTD2HTML -home- >
The FAQ DTD is being developed by several readers of the
UseNet newsgroup <a href="news:comp.text.sgml">comp.text.sgml</a>
as a standard way to mark up Frequently Asked Question lists.
<P>
<?DTD2HTML a >
This element contains the text that answers the associated
<a href="q.html">question</a> enclosed in the <a href="qna.html">Question
and Answer</a> element.
<P>
<?DTD2HTML althdr >                                       Page 2
Used to indicate that an "alternate header" should be included
if this document instance is used to generate a posting to
UseNet.  Some sort of processing directives could be used in
the <a href="content.html">content</a> element to automatically
update headers like "Last-modified:".
<P>
<?DTD2HTML archive >
This element contains a description of an archive site where copies
of this FAQ are made available.
<p>
<?DTD2HTML archive*href >
This attribute should contain a URL pointing to where a copy of
this FAQ is archived (in whatever form).
<p>
<?DTD2HTML archive*type >
This attribute should indicate what format the FAQ is stored in at the
site pointed to the href attribute.  The value should be interpreted
as a MIME type.<p>
If this attribute is missing, the type of the archived FAQ should be
inferenced from other information (like the headers returned by a
WWW server or a file extension).
<p>
<?DTD2HTML body >
<P>
<?DTD2HTML content >
<P>
<?DTD2HTML email >
<P>
<?DTD2HTML faq >
<P>
<?DTD2HTML hdr >
Used to indicate that an header should be included
if this document instance is used to generate a posting to
UseNet.  Some sort of processing directives could be used in
the <a href="content.html">content</a> element to automatically
update headers like "Message-id:" or "Supercedes:".
<P>
<?DTD2HTML head >
<P>
<?DTD2HTML link >
This element is used to introduce a hypertext link.  This element is intended
to work like the HTML &lt;a&gt; tag.  &lt;link&gt; was chosen because
&lt;a&gt; is being used to tag the text of the answer.
<p>
<?DTD2HTML link* >
<b>Note:</b> at least one of the href or name attributes must occur in
each link tag.
<?DTD2HTML link*href >
The URL that the link points to.
<p>
<?DTD2HTML link*name >
<p>
<?DTD2HTML maintain >
This element contains the name and e-mail address of the primary maintainer
of this FAQ.
<P>
<?DTD2HTML name >
<P>
<?DTD2HTML p >
A paragraph element.
<?DTD2HTML q >

Contains the text of a question.
<P>
<?DTD2HTML qna >
Encloses a question and an answer.
Page 3
<P>
<?DTD2HTML section >
<P>
<?DTD2HTML title >
<P>
<?DTD2HTML type >
The type of header, such as "From:", "Meassage-ID:", or "Archive-name:".
The content should not contain any whitespace.  If there is no trailing
colon, one will be added.
<p>
----
    Jeffrey M\kern-.05em\raise.5ex\hbox{\b c}\kern-.05emArthur
    a.k.a. Jeffrey McArthur          email: [email-masked]
    work:  (301) 306-5188
    home:  (410) 290-6935

The opinions express are mine.  They do not reflect the opinions
of my employer.  My access to the Internet is not paid for by my
employer.