The basic changes are that I added the RFC1153-like hyphen line, and
allowed additional RFC-822 headers, and header continuation mechanisms.
After this iteration, I plan to get it registered and start posting
it live.
I'd particularly appreciate suggestions on:
1) Which newsgroups to post to.
2) URL format references to and brief descriptions of related
material and further reading.
3) Discussion on whether we should put in a "format" subheader
to start giving hints to formatters what format to accept.
I put a "Faq-Format:" header in below, but something is
probably already in use. Suggestions?
Thank you.
Subject: FAQs: A Suggested Minimal Digest Format
Newsgroups: <whereelse?>,news.software.readers,news.answers
Followup-To: poster
Reply-to: digfaq@ferret.ocunix.on.ca (Digest FAQ commentary reception)
Summary: A suggested digest format for USENET FAQs.
Approved: <not yet of course>
Keywords: faqs digest format
Organization: Elegant Communications Inc., Ottawa, Canada
Archive-name: <tbd>
Last-modified:
Faq-Format: minimal-0.0
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 that is compatible with
a wide range of software that understands digest format.
This format is entirely optional. But it is designed to give you
the biggest "bang per buck" in terms of existing software compatibility
and minimum effort. If you believe that your FAQ can benefit from more
sophisticated formats, by all means use them. As such, this FAQ
can be simply considered a guide on how to trigger some basic digest
capabilities in end-user viewing software.
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 in many newsreaders.
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.
Note to reader software implementors: you should not take this format
as gospel, instead, use it as a guide to one minimal format of many
more sophisticated ones. You should really be reading RFC1153,
Thomas Fine's material, and consulting news.answers for how FAQS
are defacto formatted.
------------------------------
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>
<section>
<section>
<section>
<section>
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, groups of Q&A, textual sections, whatever. The digest format
is all about how these sections should be 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>
<string of 30 hyphens>
Subject: <subject line>
<additional optional RFC822-like headers>
<blank line>
<text>
Note that the string of hyphens and "Subject:" must start in column one.
"Subject:" has one space or tab 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). If your subject
line is too wide to fit in 80 columns, you can continue it onto the next
lines, with whitespace at the beginning of the following lines. Example:
Subject: this is a long........
subject line
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.
You can place additional RFC-like headers after the Subject, such as
"From:", "Date:" etc. Again, these headers should start in column
one. There should be no blank lines in the entire set of headers
in a section.
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
one or two global edit commands.
------------------------------
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. The intent of using exactly the same strings as the subjects is
so that users can use search mechanisms to find specific sections. If the
subject line is too long to fit in a table of contents line, it is suggested
that you truncate it at a convenient point - the search will still work.
------------------------------
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. If you want to refer to a directory,
leave a trailing "/".
This string can be anywhere in the document, inline with text or whatever.
Similarly, for html (hypertext markup language)-compatible documents,
use http://<inet>:/<str>/<str>
[What other conventions should I suggest?]
------------------------------
Subject: 7. Where Do I need to Look for Other Information?
[These seemed relevant, but I need descriptions!]
http://www.cis.ohio-state.edu/hypertext/usenet/faq-format/www/faq.html,
http://www.cis.ohio-state.edu/hypertext/faq/usenet/faq-format/top.html
http://www.cis.ohio-state.edu/hypertext/faq/usenet/technical-notes/faq.html
John E. Godwin's "Elements of E-Text Style, Version 1.0, 9 August 1993:
ftp://mrcnext.cso.uiuc.edu:/etext/etext93/estyle10.txt
-- 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 Latest psroff: FTP://ftp.uunet.ca/distrib/chris_lewis/psroff3.0pl17/*
[
Usenet Hypertext FAQ Archive |
Search Mail Archive |
Authors |
Usenet
]
[
1993 |
1994 |
1995 |
1996 |
1997
]
© Copyright The Landfield Group, 1997
All rights reserved