[Tinyos-2-commits] CVS: tinyos-2.x/doc/html tep1.html,1.7,1.8
Phil Levis
scipio at users.sourceforge.net
Tue May 29 15:23:57 PDT 2007
Update of /cvsroot/tinyos/tinyos-2.x/doc/html
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv2590/html
Modified Files:
tep1.html
Log Message:
Recommended changes to TEP 1.
Index: tep1.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep1.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** tep1.html 21 Apr 2007 07:04:39 -0000 1.7
--- tep1.html 29 May 2007 22:23:55 -0000 1.8
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>TEP Structure and Keywords</title>
<meta name="author" content="Philip Levis" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>TEP Structure and Keywords</title>
<meta name="author" content="Philip Levis" />
***************
*** 284,287 ****
--- 284,288 ----
</head>
<body>
+ <div class="document" id="tep-structure-and-keywords">
<h1 class="title">TEP Structure and Keywords</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 311,315 ****
</tbody>
</table>
- <div class="document" id="tep-structure-and-keywords">
<div class="note">
<p class="first admonition-title">Note</p>
--- 312,315 ----
***************
*** 318,329 ****
improvements. Distribution of this memo is unlimited.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This memo describes the structure all TinyOS Extension Proposal (TEP)
documents follow, and defines the meaning of several key words in
those documents.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>In order to simplify management, reading, and tracking development,
all TinyOS Extension Proposals (TEPs) MUST have a particular
--- 318,329 ----
improvements. Distribution of this memo is unlimited.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo describes the structure all TinyOS Extension Proposal (TEP)
documents follow, and defines the meaning of several key words in
those documents.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>In order to simplify management, reading, and tracking development,
all TinyOS Extension Proposals (TEPs) MUST have a particular
***************
*** 333,355 ****
describes and follows both.</p>
</div>
! <div class="section" id="keywords">
! <h1><a name="keywords">2. Keywords</a></h1>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in TEP 1.</p>
<p>Note that the force of these words is modified by the requirement
! level of the document in which they are used.</p>
! <div class="section" id="must">
! <h2><a name="must">2.1 MUST</a></h2>
<p>MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the
definition is an absolute requirement of the specification.</p>
</div>
! <div class="section" id="must-not">
! <h2><a name="must-not">2.2 MUST NOT</a></h2>
<p>MUST NOT: This phrase, or the phrase "SHALL NOT", mean that the
definition is an absolute prohibition of the specification.</p>
</div>
! <div class="section" id="should">
! <h2><a name="should">2.3 SHOULD</a></h2>
<p>SHOULD: This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
--- 333,357 ----
describes and follows both.</p>
</div>
! <div class="section">
! <h1><a id="keywords" name="keywords">2. Keywords</a></h1>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in TEP 1.</p>
<p>Note that the force of these words is modified by the requirement
! level of the document in which they are used. These words hold their
! special meanings only when capitalized, and documents SHOULD avoid using
! these words uncapitalized in order to minimize confusion.</p>
! <div class="section">
! <h2><a id="must" name="must">2.1 MUST</a></h2>
<p>MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the
definition is an absolute requirement of the specification.</p>
</div>
! <div class="section">
! <h2><a id="must-not" name="must-not">2.2 MUST NOT</a></h2>
<p>MUST NOT: This phrase, or the phrase "SHALL NOT", mean that the
definition is an absolute prohibition of the specification.</p>
</div>
! <div class="section">
! <h2><a id="should" name="should">2.3 SHOULD</a></h2>
<p>SHOULD: This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
***************
*** 357,362 ****
carefully weighed before choosing a different course.</p>
</div>
! <div class="section" id="should-not">
! <h2><a name="should-not">2.4 SHOULD NOT</a></h2>
<p>SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED" mean that
there may exist valid reasons in particular circumstances when the
--- 359,364 ----
carefully weighed before choosing a different course.</p>
</div>
! <div class="section">
! <h2><a id="should-not" name="should-not">2.4 SHOULD NOT</a></h2>
<p>SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED" mean that
there may exist valid reasons in particular circumstances when the
***************
*** 365,370 ****
before implementing any behavior described with this label.</p>
</div>
! <div class="section" id="may">
! <h2><a name="may">2.5 MAY</a></h2>
<p>MAY: This word, or the adjective "OPTIONAL", mean that an item is
truly optional. One implementer may choose to include the item
--- 367,372 ----
before implementing any behavior described with this label.</p>
</div>
! <div class="section">
! <h2><a id="may" name="may">2.5 MAY</a></h2>
<p>MAY: This word, or the adjective "OPTIONAL", mean that an item is
truly optional. One implementer may choose to include the item
***************
*** 379,384 ****
course, for the feature the option provides.)</p>
</div>
! <div class="section" id="guidance-in-the-use-of-these-imperatives">
! <h2><a name="guidance-in-the-use-of-these-imperatives">2.6 Guidance in the use of these Imperatives</a></h2>
<p>Imperatives of the type defined in this memo must be used with care
and sparingly. In particular, they MUST only be used where it is
--- 381,386 ----
course, for the feature the option provides.)</p>
</div>
! <div class="section">
! <h2><a id="guidance-in-the-use-of-these-imperatives" name="guidance-in-the-use-of-these-imperatives">2.6 Guidance in the use of these Imperatives</a></h2>
<p>Imperatives of the type defined in this memo must be used with care
and sparingly. In particular, they MUST only be used where it is
***************
*** 390,418 ****
</div>
</div>
! <div class="section" id="tep-structure">
! <h1><a name="tep-structure">3. TEP Structure</a></h1>
<p>TEPs have two major parts, a header and a body. The header states
! document metadata, for management and status. The body contains the
content of the proposal.</p>
! <p>All TEPs MUST follow the TEP docutils template, and conform to
! reStructuredText standards <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>, to enable translation from
! reStructuredText to HTML and Latex.</p>
! <div class="section" id="tep-header">
! <h2><a name="tep-header">3.1 TEP Header</a></h2>
<p>The TEP header has several fields which MUST be included, as well as
! others which MAY be included. The first six header fields MUST be
included in all TEPs, in the order stated here.</p>
<p>The first field is "TEP," and specifies the TEP number of the
! document. A TEP's number is unique.. This document is TEP 1. The
! TEP type (discussed below)
! determines how a number is assigned to it. Generally, when a document
! is ready to be a TEP, it is assigned the smallest available number.
! BCP TEPs start at 1 and all other TEPs (Documentary, Experimental,
! and Informational) start at 101.</p>
<p>The second field states the name of the working group that produced
the document. This document was produced by the Core Working Group.</p>
<p>The third field is "Type," and specifies the type of TEP the document
is. There are four types of TEP: Best Current Practice (BCP),
! Documentary, Informational, and Experimental. This document is Best
Current Practice.</p>
<p>Best Current Practice is the closest thing TEPs have to a standard: it
--- 392,421 ----
</div>
</div>
! <div class="section">
! <h1><a id="tep-structure" name="tep-structure">3. TEP Structure</a></h1>
<p>TEPs have two major parts, a header and a body. The header states
! document metadata, for management and status. The body contains the
content of the proposal.</p>
! <p>All TEPs MUST conform to reStructuredText standards <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a> and follow
! the docutils template, to enable translation from reStructuredText
! to HTML and LaTeX.</p>
! <div class="section">
! <h2><a id="tep-header" name="tep-header">3.1 TEP Header</a></h2>
<p>The TEP header has several fields which MUST be included, as well as
! others which MAY be included. The TEP header MUST NOT include headers
! which are not specified in TEP 1 or supplementary Best Current
! Practice TEPs. The first six header fields MUST be
included in all TEPs, in the order stated here.</p>
<p>The first field is "TEP," and specifies the TEP number of the
! document. A TEP's number is unique.. This document is TEP 1. The
! TEP type (discussed below) determines TEP number assignment. Generally,
! when a document is ready to be a TEP, it is assigned the smallest
! available number. BCP TEPs start at 1 and all other TEPs
! (Documentary, Experimental, and Informational) start at 101.</p>
<p>The second field states the name of the working group that produced
the document. This document was produced by the Core Working Group.</p>
<p>The third field is "Type," and specifies the type of TEP the document
is. There are four types of TEP: Best Current Practice (BCP),
! Documentary, Informational, and Experimental. This document's type is Best
Current Practice.</p>
<p>Best Current Practice is the closest thing TEPs have to a standard: it
***************
*** 422,426 ****
<p>Documentary TEPs describe a system or protocol that exists; a
documentary TEP MUST reference an implementation that a reader can
! easily obtain. Documentary TEPs simplify interoperability when
needed, and document TinyOS service implementations.</p>
<p>Informational TEPs provide information that is of interest to the
--- 425,429 ----
<p>Documentary TEPs describe a system or protocol that exists; a
documentary TEP MUST reference an implementation that a reader can
! easily obtain. Documentary TEPs simplify interoperability when
needed, and document TinyOS service implementations.</p>
<p>Informational TEPs provide information that is of interest to the
***************
*** 431,442 ****
<p>Experimental TEPs describe a completely experimental approach to a
problem, which are outside the TinyOS core and will not necessarily
! become part of it. Unlike Documentary TEPs, Experimental TEPs may
describe systems that do not have a reference implementation.</p>
<p>The fourth field is "Status," which specifies the status of the TEP.
A TEP status can either be "Draft," which means it is a work in
! progress, "Final," which means it is complete and will not change.
! Once a TEP has the status "Final," its body MUST NOT change.
! The values of its header fields MUST NOT change. The header of a
! Final TEP MAY have an "Obsoleted By" field added.</p>
<p>The "Obsoletes" field is a backward pointer to an earlier TEP which
the current TEP renders obsolete. An Obsoletes field MAY have multiple
--- 434,444 ----
<p>Experimental TEPs describe a completely experimental approach to a
problem, which are outside the TinyOS core and will not necessarily
! become part of it. Unlike Documentary TEPs, Experimental TEPs may
describe systems that do not have a reference implementation.</p>
<p>The fourth field is "Status," which specifies the status of the TEP.
A TEP status can either be "Draft," which means it is a work in
! progress, "Final," which means it is complete and will not change.
! Once a TEP has the status "Final," the only change allowed is the
! addition of an "Obsoleted By" field.</p>
<p>The "Obsoletes" field is a backward pointer to an earlier TEP which
the current TEP renders obsolete. An Obsoletes field MAY have multiple
***************
*** 464,468 ****
another TEP. The purpose of this field is to denote when a TEP represents
an addition to an existing TEP. Meeting the requirements of a TEP with an
! Extends field requires also meeting the requirements of all TEPs listed
in the Extends field.</p>
<p>If a TEP is a Draft, then four additional fields MUST be included:
--- 466,470 ----
another TEP. The purpose of this field is to denote when a TEP represents
an addition to an existing TEP. Meeting the requirements of a TEP with an
! Extends field requires also meeting the requirements of all TEPs listed
in the Extends field.</p>
<p>If a TEP is a Draft, then four additional fields MUST be included:
***************
*** 475,480 ****
have these fields, which are for Drafts only.</p>
</div>
! <div class="section" id="tep-body">
! <h2><a name="tep-body">3.2 TEP Body</a></h2>
<p>The first element of the TEP body MUST be the title of the document. A
TEP SHOULD follow the title with an Abstract, which gives a brief
--- 477,482 ----
have these fields, which are for Drafts only.</p>
</div>
! <div class="section">
! <h2><a id="tep-body" name="tep-body">3.2 TEP Body</a></h2>
<p>The first element of the TEP body MUST be the title of the document. A
TEP SHOULD follow the title with an Abstract, which gives a brief
***************
*** 486,508 ****
"Implementation," which instructs the reader how to obtain the
implementation documented.</p>
! <p>If a TEP is Best Current Practices, it MUST have a section entitled
"Reference," which points the reader to one or more reference uses of
the practices.</p>
! <p>The last section of a TEP (but before citations, if there are any),
entitled "Author's Address" or "Author's Addresses" MUST contain
detailed author contact information.</p>
</div>
</div>
! <div class="section" id="reference">
! <h1><a name="reference">4. Reference</a></h1>
<p>The reference use of this document is TEP 1 (itself).</p>
</div>
! <div class="section" id="acknowledgments">
! <h1><a name="acknowledgments">5. Acknowledgments</a></h1>
<p>The definitions of the compliance terms are a direct copy of
definitions taken from IETF RFC 2119.</p>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
--- 488,512 ----
"Implementation," which instructs the reader how to obtain the
implementation documented.</p>
! <p>If a TEP is Best Current Practic, it MUST have a section entitled
"Reference," which points the reader to one or more reference uses of
the practices.</p>
! <p>The last numbered section of a TEP (but before citations, if there are any),
entitled "Author's Address" or "Author's Addresses" MUST contain
detailed author contact information.</p>
+ <p>A TEP MAY have appendices after its Author section. Unlike regular sections,
+ appendices are lettered. Please refer to Appendix A for details.</p>
</div>
</div>
! <div class="section">
! <h1><a id="reference" name="reference">4. Reference</a></h1>
<p>The reference use of this document is TEP 1 (itself).</p>
</div>
! <div class="section">
! <h1><a id="acknowledgments" name="acknowledgments">5. Acknowledgments</a></h1>
<p>The definitions of the compliance terms are a direct copy of
definitions taken from IETF RFC 2119.</p>
</div>
! <div class="section">
! <h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
***************
*** 516,521 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 520,525 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
***************
*** 525,528 ****
--- 529,536 ----
</table>
</div>
+ <div class="section">
+ <h1><a id="appendix-a-example-appendix" name="appendix-a-example-appendix">Appendix A. Example Appendix</a></h1>
+ <p>This is an example appendix. Appendices begin with the letter A.</p>
+ </div>
</div>
</body>
More information about the Tinyos-2-commits
mailing list