Home| superdarn| rfc| RFC0001

RFC: 0001

Title

SuperDARN Request for Comments Document Specification

Author

R.J.Barnes

Summary

To further the discussion of software issues within the SuperDARN community, it has been decided to adopt an approach similar to the "Request For Comments" documents that define the Internet. A document describing proposed software changes will be posted for review and comment prior to implementation.This document describes the proposed format of SuperDARN Request for Comments.

Description

1. Introduction

The SuperDARN Request for Comments documents are modeled after the widely known Internet Request for Comments (RFCs). The purpose of the documents is to discuss any aspect of the software that may be of interest to the wider SuperDARN community.

The purpose of this document is to define the format of SuperDARN RFCs and a mechanism for maintaining and distributing them.

2. Document Format

SuperDARN RFCs will be stored using the XML format already used by the rest of the SuperDARN documentation. There are several principal benefits to this:

  • Sections of the document can be easily marked out making searching and databasing easy.
  • The extensible nature of XML means that new features can be added to the format as they become necessary.
  • The presentation of the document is independent of its content, ie. The XML document can be used to produce plain ASCII text, HTML or even PostScript.
2.1 Rules for Constructing an RFC Document

For convenience, each RFC will reside in a separate XML file. The root element of an RFC is marked using the <rfc> tag. The child elements delineate the various sections of the RFC. In addition to the body of the text the RFC must have an identifier (number), author, title, summary, and revision history.

The elements of the the RFC are defined below:

<rfc>Root element of the RFC.
<id>RFC numerical identifier.
<title>Title of the RFC.
<author>Author of the RFC.
<summary>A brief summary of the RFC topic.
<body>The main body of the RFC text.
<revision>Revision history. (one element per revision).

The body text and summary of an RFC can include HTML tags for markup, but the author must ensure that these tags do not violate any XML grammar rules, so all tags must have an accompanying closing tag.

2.2 The Revision History

The RFC must include a revision history in the form of one or more <revision> elements. Each revision should have a separate element pair. The text should list the date of the revision and a brief statement as to the reason for the revision:

<revision>2004/06/01 Initial revision.</revision>
<revision>2004/06/02 Addded specifications for author name.</revision>

3. Managing the Documents

RFCs are stored in the ${CODEBASE)/rfc directory and are maintained under RCS. The RFCs are distributed either as a self-contained package or as part of a larger software set.

4. Producing HTML versions of RFCs

Scripts within the ${CODEBASE}/doc directory convert the XML RFCs to an HTML web page. The process involves extracting the elements from the XML document and substituting them into an HTML outline script to produce the final static web page.

An automated script called ${CODEBASE}/doc/script/mkrfc will convert all the RFC documents to web pages and build a simple index page. The pages are installed in the directory ${WWWPATH)/rfc.

5. An Example RFC document

<?xml version="1.0" encoding="ISO-8859-1"?>
<rfc>
<id>0001</id>
<title>An Example RFC</title>
<author>J.Smith</author>
<summary><p>A simple example of an RFC document.
</p></summary>
<body><p>The body text of the RFC goes here and can include HTML tags.
</p></body>
<revision>2004/06/01 Initial Revision</revision>
</rfc>

References

None

History

2004/06/01 Initial Revision.