| *------------------------------- REQUEST #2 ---------------------------------*
help: Manual
*------------------------------- RFC-INFO RESPONSE #2 -----------------------*
Request For Comments Document Server (RFC-INFO)
-----------------------------------------------
1. RFC-INFO OVERVIEW
RFC-INFO provides support for RFC query and retrieval for users
over electronic mail (e-mail, such as MILNet, MCImail, and
Tele-mail).
RFC-INFO users will be able to request lists of available
documents (RFCs and FYIs) and the retrieval of full documents
using RFC-INFO facilities.
In addition, authorized personnel may post new RFCs to the system.
Posted RFCs will be handled manually by the RFC-INFO manager to
ensure that proper formats are being issued to RFC-INFO.
2. ACCESS
There are three e-mail addresses which are used by the RFC-INFO
system. Each address is used to handle a different aspect of the
system.
[email protected]:
The RFC-INFO address will handle all RFC-INFO transactions as
defined in this document.
[email protected]:
This account is handled manually, and will handle all system
maintenance and special needs.
The RFC-MANAGER address is a manned mailbox used to get
information about exceptional cases involving RFC-INFO. Users
will send messages to RFC-MANAGER if they believe that there is
some error in the RFC-INFO transactions that is clearly a bug and
not a misunderstanding of the system.
[email protected]
This is the address which RFC-INFO 'signs' its messages with.
3. EXAMPLES
The following examples are designed to give a sense of the kinds
and nature of RFC-INFO requests. While the examples are neither
exhaustive nor overly complicated, they do show virtually all of
the RFC-INFO facilities.
(a) LIST: RFC
(b) LIST: RFC
KEYWORD: routing
(c) LIST: RFC
DATED-AFTER: 10/12/91
DATED-BEFORE: 12/31/91
(d) LIST: RFC, FYI
KEYWORDS: internet, arpanet, %net, ?AN
STATUS: standards-track
ORGANIZATION: USC/ISI, Ntework Working Group
(e) LIST: KEYWORDS
These five RFC-INFO requests are examples of the LIST request.
The LIST request is used to get a listing of the attributes of all
documents in the system that fit certain criteria (see section 8.2
for more information about the LIST request). The full text of a
document is not returned by LIST; to get the full text of a posted
document, you would use the RETRIEVE request (see section 8.3 for
more information about the RETRIEVE request).
Example (a) requests a listing of all RFCs in the system.
Example (b) requests a listing of all the RFCs about routing
(specified by the KEYWORD) in the system.
Example (c) requests a listing of all RFCs in the system which
were posted between OCT-12-1991 and DEC-31-1991.
Example (d) requests a listing of all RFCs and FYIs that contain
any combination of the following keywords "internet", "arpanet",
any keyword that matches "%net" (e.g., both of the keywords just
provided, as well as "net", "milnet", "planet", "coronet", etc.),
and any text that matches "?AN" (e.g., LAN, WAN, man, can, fan,
dan, pan, etc.), provided that the document is on the standards
track (as specified by the STATUS attribute), and one of the
issuing organizations was USC/ISI or the Network Working Group (or
both).
Example (e) requests a listing of all keywords currently in use by
the system.
(f) RETRIEVE: RFC
DOC-ID: RFC1025
Example (f) is a sample of the RETRIEVE request. The RETRIEVE
request is used to request that the entire text of a document be
sent to the requester via e-mail. The RFC to be sent is specified
by its unique document ID (DOC-ID).
**NOTE: Currently, DOC-ID's of RFCs are of the form: RFCXXXX (always
4 digits following the RFC. For example, RFC-128 is RFC0128)
(g) HELP: HELP
(h) HELP: MANUAL
(i) HELP: TOPICS
These three RFC-INFO requests are examples of the HELP request.
The HELP request is used to get help about various elements of the
system (see section 8.1 for more information about the HELP
request).
Example (g) is requesting help about the HELP request itself.
Example (h) is requesting that a copy of the RFC-INFO manual be
sent via e-mail.
Example (i) is requesting that a list of the available HELP topics
be sent via e-mail.
4. SUPPORTED DOCUMENTS
RFC-INFO will support the following types of documents:
RFC (Request For Comments)
FYI (Special Case of the above)
5. REQUEST OVERVIEW
Users may use the following requests (as described in detail in
section 8) in RFC-INFO:
HELP - to get instructions about how to use RFC-INFO
LIST - to get lists of documents and other items
RETRIEVE - to retrieve entire documents
Following is a short description of each of these requests. A
more detailed description of requests may be found in section 8.
HELP is used for getting directions on how to use the system.
LIST is used to find out about the available documents and about
available types. It returns the attributes of the specified
documents as qualified (filtered) with subsets. It is also used
to get various lists, such as the list of currently used keywords.
RETRIEVE is used to get entire documents. These documents are
returned via e-mail. Some documents may be too large to be sent
via e-mail. These documents will be sent via ftp or rcp. Unlike
LIST, the RETRIEVE request returns complete documents.
6. ATTRIBUTES
RFC-INFO Attributes are used to further identify the request and
the transaction. The following are the attributes of RFCs and
FYIs.
AUTHOR(S) (The authors or editors of the document)
ORGANIZATION (Name or symbol of the organization issuing the
document, e.g., USC, ISI, etc.)
TITLE (title of the document)
DOC-ID (the unique ID of this document)
FYI-ID (the FYI number of the document, for FYIs)
STATUS (the 'track' this RFC is on, e.g., 'standard-track')
DATE (date of document)
FORMAT(S) (formats in which the document is available or
requested, e.g., ASCII, PS)
KEYWORD(S) (e.g., "printers, ADP" and "air")
NOTES (Notes about the document or file)
OBSOLETES (DOC-IDs of documents made obsolete by current doc)
OBSOLETED-BY (DOC-IDs of document making current doc obsolete)
SEE-ALSO (DOC-IDs of other possibly relevant documents)
UPDATES (DOC-ID of document which current doc updates)
UPDATED-BY (DOC-ID of document which updates current doc)
AUTHOR(S) is used to identify the author(s) or editor(s) of the
document or file.
ORGANIZATION (or ORG-ID) is used to identify organizations
associated with a document.
TITLE is used to specify the title of the submission. When used
with LIST or RETRIEVE, it allows users to show only those
documents with a title matching this expression.
DOC-ID is used to give each transaction or document a unique
identification number. These IDs will allow easy identification
of document type and linking of related documents, where possible.
FYI-ID is the FYI number of an FYI document. This number, unlike
DOC-ID, is not unique. Successive FYIs on the same topic make the
previous ones obsolete. Each FYI will have a unique DOC-ID (its
RFC number) as well as a not-necessarily-unique FYI-ID.
STATUS identifies the "track" that this document is on. There are
currently three possible values: STANDARDS-TRACK, FYI,
INFORMATION. If an RFC is neither standards-track nor an FYI, it
is INFORMATION.
DATE is the date of the document. This can be separate from the
date of posting, or, if not specified, defaults to the date of
posting.
FORMAT is used to define the format or type of data submitted.
KEYWORDs are used to identify the topics addressed in the
document.
In order to avoid long lines, the KEYWORD attribute may be
repeated within the same request. All keywords will be merged
into a single set.
NOTE(S) is used to specify any meta-information about the document
which does not belong in the document itself.
In order to avoid long lines, the NOTES attribute may be repeated
within the same request. All keywords will be merged into a
single set.
OBSOLETES is used to specify the DOC-IDs of any document(s) which
are rendered obsolete by the current document.
OBSOLETED-BY is used to specify the DOC-IDs of any document(s)
which render obsolete the current document.
SEE-ALSO is the DOC-ID(s) of any other RFC-INFO files which might
be of interest to the person interested in the current document.
UPDATES is the DOC-ID(s) of any document(s) which the current
document updates.
UPDATED-BY is the DOC-ID(s) of any document(s) which update the
current document.
7. USING FILTERS
Both the LIST and RETRIEVE requests (see sections 8.2 and 8.3,
below) require that you specify, in some level of detail, the kind
of document you wish to list (or retrieve). This is done in
RFC-INFO by the use of filters.
Filters are used to specify a selection of documents stored in the
RFC-INFO system.
Since both LIST and RETRIEVE use filters (although in slightly
different ways, as we see below), it is appropriate to discuss
them as a separate topic.
When used in the LIST request, the filters match some subset of
the documents currently stored in RFC-INFO. Then the LIST request
returns a list of these documents in a form amenable to further
use by RFC-INFO (see section 8.2 below).
When used in a RETRIEVE request, the filters must narrow the
selection down to a single document. If it does not, then the
RETRIEVE request is instead treated as a LIST request. When a
single document has been specified, that document is returned to
the respondent via e-mail.
The idea is that respondents will use the LIST request to discover
the DOC-ID of the document desired, then use this value to specify
the document to be retrieved with the RETRIEVE request.
Both LIST and RETRIEVE require a TYPE filter on the Request line
which specifies the type(s) of documents desired to be selected.
This specification is done as follows:
LIST: <TYPE> or RETRIEVE: <TYPE>
Where <TYPE> is the document type, one of the types defined in
section 4, e.g., "RFC". (The "LIST: TYPES" command returns all
the document types currently in use by RFC-INFO -- see section
8.2.ii below.) It is possible to use wildcards in this TYPE
specification to match several document types. For example:
LIST: %
Will match every document of every type currently in the system.
In order to focus the returned lists to a desired area the request
line may be followed by several filter lines. (These filter lines
-- together with the TYPE filter -- are known collectively as a
filter set).
A document is considered to match a filter set if it satisfys all of
the filters in the filter set. (That is, there is an implicit
boolean "AND" between each of the filter lines in a query.)
The filter lines may appear in any order.
In general, one can supply any of the attributes described in
section 6 (above) as filters.
If you supply a plain-text value, then documents which contain
that text as their value (or one of their values, if multiple
values were supplied with the document, e.g., KEYWORDS) for the
specified attribute (called the target attribute) will be defined
as matching that filter.
If you supply a value for a filter which contains wildcard
characters (see section 11.10), then documents which contain any
text which can be matched by that wildcard pattern in the target
attribute will be defined as matching that filter.
In addition to the wildcard characters described in section 11.10,
a simple boolean "or" can be applied to a filter by separating the
elements to be matched by commas (",") or vertical bars ("|"). If
the target attribute matches any of the items supplied, then it is
defined as matching for that filter. For example, "KEYWORDS: air,
pressure" will match any document with either the "air" keyword or
the "pressure" keyword (or both).
In addition to all of the attributes defined in section 6 above,
there are certain filters which do not have a direct analog to a
single attribute. These special filters -- as well as possibly
unusual applications of normal filters -- are described below.
DOC-ID: XX, YY
To match only documents with those DOC-IDs.
TITLE: XXX
To match only those documents with a title matching this
expression.
KEYWORD: XX,YY
To match only documents having at least one of these keywords
in either the KEYWORDS or TITLE attribute's value (or both).
In order to avoid long lines, the KEYWORD request may be
repeated within the same request. All the keywords will be
merged into a single set.
That is, if two KEYWORD lines are supplied in a query, one
containing the text "repair, refitting" and the other
containing the text "sales", it would be the same as one
KEYWORD line containing the text "repair, refitting, sales"
(which means match any one or more of the keywords provided).
ORGANIZATION: YY
To match only documents issued by the organizations with names
matching the given expression.
OBSOLETES: XX, YY
OBSOLETED-BY: XX, YY
To list the documents which make obsolete or are made obsolete
by) documents with DOC-IDs XX and YY.
UPDATES: XX, YY
UPDATED-BY: XX, YY
To list the documents which update (or are updated by)
documents with DOC-IDs XX and YY.
SEE-ALSO: XX
To list documents which make reference to DOC-ID XX in their
SEE-ALSO attribute.
The special date filters which do not have a direct analog in the
attributes section:
DATED-BEFORE: YYMMDD
DATED-AFTER: YYMMDD
To match only those documents with a DATE that is before or
after (and including) the specified date. YYMMDD is a date in
any of the allowed formats (see section 9 for more
information on date formats).
In the following examples of filters, the LIST request is used for
simplicity's sake. Any of these filters can be used with the
RETRIEVE request as well.
LIST: RFC
ORGANIZATION: USC%
This request will list all posted RFCs which were issued by any
USC organization (assuming all USC organizations adhere to a
"USC/XXX" naming scheme when POSTing).
LIST: RFC
DATED-AFTER: 10/12/91
DATED-BEFORE: 12/31/91
This request will list all RFCs which have are dated between
OCT-12-1991 and DEC-31-1991.
LIST: RFC
KEYWORDS: *network*, packet*, internet, %-area-network, /
?AN
This request will list all RFCs with any of the following in their
TITLE or KEYWORDS attributes (this list is not complete):
network, network administrator, networks, networking,
internetwork, non-network, packets, packet-switch,
packet-switcher, internet, local-area-network,
wide-area-network, LAN, WAN, PAN, MAN, fan, can, tan, etc.
8. REQUESTS
In the following description of the various requests upper case is
used to demonstrate the requests and lower case for the
explanations.
8.1 The HELP request.
The HELP request is used to get help about some aspect of the
RFC-INFO system. These requests may be in any of the following
formats.
HELP: HELP - Brief help on how to use the system
HELP: TOPICS - A list of currently available help topics.
HELP: LIST - How to use the LIST request
HELP: RETRIEVE - How to use the RETRIEVE request
HELP: MANUAL - To retrieve the user manual
Messages that RFC-INFO fails to parse are replied to with initial
information for using the system and a list of available help
topics (i.e., "HELP: HELP" and "HELP: TOPICS"). It is recommended
for all new users to submit the "HELP: MANUAL" request.
8.2 The LIST request
There are two modes of using the LIST request:
(i) listing documents in the system.
(ii) listing the codes in use by the system (e.g., all the
keywords in use by the system), as explained below.
In the former mode (i), the parameter of LIST is a document type
(such as <RFC> or <FYI>), as defined in section 4). In the latter
mode, (ii), that parameter is the name of that parameter, as
explained below.
8.2.i LISTING DOCUMENTS
The first line of this request is:
LIST: <TYPE>
Where <TYPE> is the document type, one of the types defined in
section 4, e.g., "RFC". (The "LIST: TYPES" command returns all
the document types currently in use by RFC-INFO -- see section
8.2.ii below.)
In order to focus the returned lists, this request may be followed
by a filter set (as shown in section 7).
Here are some examples of this use of the LIST request:
LIST: RFC
This request will list all RFCs in the system.
LIST: RFC
DATED-AFTER: 04/30/91
DATED-BEFORE: 9/30/91
This request will list all RFCs which are dated between
APR-30-1991 and SEP-30-1991.
LIST: RFC
KEYWORD: Arpanet, Protocols, gateway, TOS
This request will list all RFCs which contain any combination of
the keywords "Arpanet", "Protocols", "gateway", or "TOS". (Note
that the commas "," in the keyword list indicate a boolean "or" in
the request.)
The LIST request returns a list of all the documents that match
the filter set. The returned lists contain the attributes of the
listed documents.
These matching files are returned in a format that can be used by
RFC-INFO to uniquely specify each file (e.g., for use in a
RETRIEVE request). For example:
LIST: RFC
DATED-AFTER: 5/1/91
might return the following 3 matching documents:
DOC-ID: RFC1010
TITLE: Sample RFC Document
DATE: 01/17/91
DOC-ID: RFC1019
TITLE: High Speed Local Area Networks
DATE: 07/10/91
OBSOLETES: RFC1017, RFC0002
DOC-ID: RFC1099
TITLE: Neural Net Simulations
DATE: 10/12/91
UPDATES: RFC0976
These entries could each be used in a RETRIEVE request to uniquely
identify a file for retrieval. For example, the first RFC listed
could be retrieved by simply prepending a "RETRIEVE: RFC" request
line to the entry:
RETRIEVE: RFC
DOC-ID: RFC1010
Since the DOC-ID uniquely identifies the RFC, the other filter
lines are redundant.
8.2.ii LISTING THE CODES IN USE BY THE SYSTEM
LIST: TYPES To list all the document types in RFC-INFO
LIST: KEYWORD To list all the keywords used in RFC-INFO.
LIST: ORGANIZATION To retrieve the list of all the
organizations that are associated
with RFCs in RFC-INFO.
LIST: FORMATS To list the document formats
available in RFC-INFO.
These retrieved lists include explanations about their use, and
the meaning of the various items.
8.3 The RETRIEVE request
RETRIEVE returns entire documents, unlike LIST that returns only
attributes. It is expected that user will use LIST to learn about
documents and then RETRIEVE to get selected documents in their
entirety, using their DOC-ID as a "handle". It is also expected
that users will retrieve first RFCs, and then will also retrieve
any documents referred to in that RFC's SEE-ALSO attribute (if
any).
Retrieve requests start with "RETRIEVE: <TYPE>", where <TYPE> is a
document type (as defined in section 4).
The RETRIEVE request is similar to the LIST request and uses the
same filters to specify documents (see section 7 for more
information about using filters).
If a single document matches all the filters, it is retrieved in
its entirety. Otherwise, the attributes of all matching documents
are returned, just as with LIST (see section 8.2).
Because some documents may be available in various online formats
the following parameter may be added to the RETRIEVE request:
FORMAT(S): XX, YY, ...
to define the formats acceptable by the user, in the order of
preference. Examples for these formats are ASCII and PS (for
drawings). If no FORMAT is provided only ASCII is assumed.
If the document is not available in any of the specified formats,
a message will be returned to the user advising about the formats
available for that document.
The LIST command will also return always the list of the formats
in which the specified documents are available.
Only formats that are embedded in ASCII will be e-mailed to assure
smooth operation over the various e-mail systems.
The FORMAT parameter will hold from where it is defined to the end
of the message, unless is is overridden by a later FORMAT
parameter.
Here are some examples of the RETRIEVE request:
RETRIEVE: RFC
DOC-ID: RFC1245
FORMAT: ASCII
This is a request to retrieve the RFC with the unique identifier
RFC1245. This DOC-ID probably was gotten earlier by the use of a
LIST request. The RFC is requested in standard ASCII format, and
will be e-mailed to the requester.
RETRIEVE: RFC
DOC-ID: RFC1247
FORMAT: PS
This is a request for an RFC. The RFC's DOC-ID has been
discovered earlier, probably by the use of the LIST request. The
RFC is being requested in PS format (possibly because of drawings
in the RFC), and will be e-mailed to the requester.
A shortcut form of the RETRIEVE request is to place the DOC-ID of
the document to be retrieved in the TYPE filter location. That
is:
RETRIEVE: <DOC-ID>
where <DOC-ID> is a valid RFC-INFO DOC-ID. If it is not, RFC-INFO
may misinterpret this request as a retrieval request for all
documents of type <DOC-ID>, which, if it led to multiple matches,
would be treated like a LIST request. If, on the other hand,
there was a single document of type <DOC-ID>, that document would
be retrieved, even though it was not the document that was
requested.
9. DATES
RFC-INFO can parse dates in essentially any reasonable format.
Examples of supported formats are as follows:
OCT-12-1991
10/12/91
Oct 12 91
12 October, 1991
1991, October 12
12-oct-91
10 12 91
91/10/12
oct. 12 1991
1991 12 octob
10-12-91
oct 1991
10/91
1991
In the case of ambiguous definitions (such as 4-2-91) specified in
a filter, the system will use the interpretation which includes
more dates, i.e., the earlier dates for AFTER and the later dates
for BEFORE. For example "DATED-BEFORE: 4/2/91" is interpreted as
"DATED-BEFORE: APR-2-91" but "DATED-AFTER: 4/2/91" as
"DATED-AFTER: 4-FEB-91".
The preferred (unambiguous) format for dates is: MMM-DD-YYYY or
DD-MMM-YYYY, where DD is a number defining the day within a month,
and MMM defines the month (alphabetically), and YYYY is the year
in 4 digit format). RFC-INFO always uses the MMM-DD-YYY format
for dates.
10. MESSAGE FORMAT
Each e-mailed RFC-INFO message has a header and a body. RFC-INFO
ignores the entire e-mail header except for the sender's return
address to which it replies. Note that the subject is ignored.
However, RFC-INFO may include the date and the subject in its
replies, to help users associate replies with requests. The body
of the message should follow the format and the style specified
here. The message body contains the user's request(s) and
parameters for these requests as needed.
RFC-INFO is a multilayered process. The first layer is the
command (called a request) with a type modifier. The request
identifies the function to be accomplished; the modifier
identifies the specific task to be accomplished. The request and
modifier are separated by a colon (i.e., ":") and optional
whitespace.
For example, HELP is a request used to obtain assistance on the
use of RFC-INFO. When the HELP request is used with the HELP
modifier (i.e., "HELP: HELP"), RFC-INFO will provide a brief
summary of how to use the system and how to obtain further help.
The second layer is a list of attribute-value pairs, which modify
or supply more detail about the request. Like requests and their
modifiers, attributes and values are separated by a colon and
optional whitespace.
For example:
LIST: RFC
KEYWORDS: networks, packet-switch
The request (LIST) has a modifier of "RFC", which says that a list
of posted RFCs is being requested. The attribute list consists of
a single attribute (KEYWORDS) which has values of "network" and
"packet-switch". The KEYWORD attribute more narrowly defines the
list of posted RFCs being requested.
11. STYLE RULES
11.1 RFC-INFO is case-independent.
11.2 RFC-INFO treats all spaces, tabs and sequences thereof as a
single space (except within BEGIN-TEXT: ... END-TEXT:
attributes).
11.3 Blank lines and indentations are ignored (except within
BEGIN-TEXT: ... END-TEXT: attributes).
11.4 If the first word in a line is followed by a colon (":") then
that word is treated as a request or a parameter (except within
BEGIN-TEXT: ... END-TEXT: attributes).
11.5 Requests are terminated by the next request or by the end of the
message.
11.6 Any line starting with the word "END:" terminates the message.
(It is considered to be an END request.) Following text, if
any, is ignored.
11.7 Several requests may be combined in a single message.
11.8 All RFC-INFO "lines" (i.e., request lines and attribute lines)
are terminated by the EOL. In other words, each request and
attribute line occupies only a single (possibly long) line.
There are two exceptions to this rule. The first exception is
that all lines are accepted verbatim and unparsed when
encountered within BEGIN-TEXT: and END-TEXT: attributes.
The second exception to this rule is if the last non-whitespace
character in a line is the slash "/", then the following line is
used as a "continuation line". The "continuation line" is
considered to be part of the preceding line, and the trailing
slash "/" is stripped off of the preceding line.
For example, the lines:
KEYWORDS: router, DIXIE, MIB, IESG, /
X.400, IRSG, protocol
are considered exactly the same as the line
KEYWORDS: router, DIXIE, MIB, IESG, X.400, IRSG, protocol
11.9 Commas are used to separate items in sets.
11.10 Wildcard characters may be used in LIST and RETRIEVE requests
to allow arbitrary matching of attribute parameters. The
following wildcards are supported:
"%" matches any sequence (including none) of non-whitespace
"?" matches any single non-whitespace character
"#" matches any sequence (including none) of whitespace
"*" matches any sequence (including none) of any character.
To match one of the wildcard characters literally, simply precede
the character with a backslash "\" like so:
"\%" matches the asterisk character "%"
"\?" matches the question mark character "?"
"\#" matches the pound sign "#"
"\*" matches the percent sign "*"
"\\" matches the backslash character "\"
12. MISCELLANEOUS
* New users should request "HELP: MANUAL". This will provide them
with the user's manual and with the up-to-date lists of
categories, organizations and their symbols, types of documents
and the codes for the SPECIAL field.
* RFC-INFO "signs" its messages from a different address
(RFC-INFO-SERVER) than it uses to receive messages (in order to
avoid auto-mailer-loops).
* Filters and parameters are valid only in the request in which they
are defined, except for the FORMAT parameter, which stays valid
for the rest of the message (but may be redefined.)
* The implementation actually allows much more flexibility than what
is defined here. For the most part, any unique abbreviation of an
attribute or request will be recognized.
13. FUTURE ENHANCEMENTS
* User Profiles: Users will be able to "register" their areas of
interest by specifying a filter set. If any new submissions match
the filter set, the user will be notified (or a copy will be
automatically sent).
* US Mail: RFCs may be able to be requested via US Mail, rather than
e-mail.
* FAX: RFCs may be able to be requested via FAX, rather than e-mail.
* Abstracts: Users will be able to retrieve abstracts of potentially
interesting RFCs without having to get the whole file.
* Automated Posting: Any authorized user will be given a password
which allows them to post new RFCs automatically to RFC-INFO.
[end]
|