FAQs: A Suggested Minimal Digest Format
Chris Lewis
clewis@ferret.ocunix.on.ca
Subject: 1. Introduction and Intent
The intent of this FAQ is to provide current and future FAQ maintainers
with a simple description of a minimal format for FAQs. This minimal
format is a simplification of RFC1153 digest format that is sufficient
to be compatible with common newsreader digest handling functionality,
current practise, and Thomas Fine's "FAQ digest format to HTML" converter
which allows more sophisticated viewing on HTML-aware systems such
as Mosaic or WWW. There are other more sophisticated formats that
you can use, but this is the simplest one.
Rather than confuse the issue by documenting all of the variation
allowed by existing practise and software, this documents a single
variant. However, it can be extended by reviewing the documentation
for Thomas Fine's converter (see: ftp://<whatever>)
This FAQ is written entirely in the minimal digest format, and
can be used as an example. You can usually skip from one section
to the next by pressing ^G.
This FAQ describes only how FAQ sections should be delimited, and
a couple of suggestions for meta-references to such things as FTP
or WWW repositories in formats that other tools support.
Subject: 2. Table of Contents
1. Introduction and Intent
2. Table of Contents
3. What Should the Overall FAQ Look Like?
4. What's a Section, and How is it Formatted?
5. What is the Table of Contents Format?
6. What are External Meta References, and What is Their Format?
7. Where Do I need to Look for Other Information?
Subject: 3. What Should the Overall FAQ Look Like?
Most FAQs lend themselves to a format like:
<news headers>
<news.answers required headers if the FAQ is registered>
<title and author>
<introductory section>
<table of content section>
<Q&A>
<Q&A>
<Q&A>
While FAQs aren't always lists of questions and answers, they usually
have "sections" of text. Whether they be sets of lists, individual
Q&A's, textual sections, whatever. The digest format is all about how
these sections are delimited for automatic parsing.
Subject: 4. What's a Section, and How is it Formatted?
A "section" is merely a block of text. In many FAQs they are simply
the introduction paragraph, the table of contents, and each question
and answer. Through the use of digest format, most newsreaders can
skip from section to section using the convention presented here, and
more sophisticated packages can hypertext them.
A "section" consists of:
<blank line>
Subject: <subject line>
<blank line>
<text>
Note that "Subject:" must start in column one and have one blank between it
and the subject line. If you have to put "Subject:" in and don't want it
interpreted as a section header, just make sure that it isn't in column
one (just like above).
The subject can be any arbitrary string of text. You may wish to use
a numbering scheme, for it makes it easier for your readers to "grep"
down to the precise section they want.
The text is free format ASCII and may be formatted any way you wish.
Current FAQ maintainers take note: if you're already using a consistent
format for your FAQ, converting to this format will often require only
a single global edit command.
Subject: 5. What is the Table of Contents Format?
The Table of Contents simply consists of the subject lines from the rest
of the FAQ, excluding "Subject:", and preferably indented. The subject lines
should be exact copies of the section headers.
This is only a suggestion. There is no existing software that parses this
data.
Subject: 6. What are External Meta References, and What is Their Format?
Many of the more sophisticated viewers can "jump" from one FAQ to the
next, retrieve data via FTP, or send email simply by "pointing at"
properly formatted "tags" in your FAQ.
This section describes some conventions that are in common use.
If your FAQ refers to a FTP-able file, use this format:
ftp://<inet>/<str>/<str>
Where "<inet>" is the Internet domain name of the server, and the rest
of the "<str>/<str>" is the file name.
This string can be anywhere in the document, inline with text or whatever.
[What other conventions are there? Could we invent a couple?]
Subject: 7. Where Do I need to Look for Other Information?
[Need to enumerate, in FTP:... format those FAQs that describe how
to register with news.answers and general header considerations.]
-- Look on the bright side - at least the PC's reached gender parity!Chris Lewis; clewis@ferret.ocunix.on.ca; Phone: Canada 613 832-0541 Ferret list: ferret-request@ferret.ocunix.on.ca
[
Usenet Hypertext FAQ Archive |
Search Mail Archive |
Authors |
Usenet
]
[
1993 |
1994 |
1995 |
1996 |
1997
]
© Copyright The Landfield Group, 1997
All rights reserved