commit 1cef21c8ea70ae599639d94f3f8e8a7035486fcc
parent 0e62fca0deda4e41966070305c5fb5d4ab09c371
Author: finwo <finwo@pm.me>
Date: Thu, 4 Jun 2020 20:59:00 +0200
Draft 0003, not done yet
Diffstat:
| A | src/0003.txt | | | 449 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 449 insertions(+), 0 deletions(-)
diff --git a/src/0003.txt b/src/0003.txt
@@ -0,0 +1,449 @@
+Specification: 0000 R. Bron
+ June 2020
+
+Obsoletes: 0000
+
+
+ Specification Style Guide
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Abstract
+
+ This document describes the fundamental and unique style conventions and
+ editorial policies currently in use for the Specification Series. It offers
+ guidance regarding the style and structure of a Specification.
+
+Copyright Notice
+
+ This document is licensed under a
+ Creative Commons Attribution 4.0 International License
+
+ You should have received a copy of the license along with this work. If not,
+ see <http://creativecommons.org/licenses/by/4.0/>
+
+Bron [Page 1]
+SPEC 0003 Specification Style Guide June 2020
+
+Table of Contents
+
+1. Introduction
+2. Key Words
+ 2.1. MUST
+ 2.2. MUST NOT
+ 2.3. SHOULD
+ 2.4. SHOULD NOT
+ 2.5. MAY
+ 2.6. Guidance in the use of these Imperatives
+ 2.7. Security Considerations
+3. Specification Syle Conventions
+ 3.1. Language
+ 3.2. Punctuation
+ 3.3. DNS Names and URIs
+ 3.4. Capitalization
+ 3.5. Citations
+ 3.6. Abbreviation Rules
+4. Structure of a Specification
+ 4.1. First-Page header
+ 4.1.1. Author/Editor
+ 4.1.2. Organization
+ 4.1.3. Updates and Obsoletes
+ 4.2. Full Title
+ 4.3. Abstract Section
+ 4.4. Table of Contents Section
+ 4.5. Body of the Specification
+ 4.5.1. Introduction Section
+ 4.5.2. Requirements Language Section
+ 4.5.3. Internationalization Considerations Section
+ 4.5.4. Security Considerations Section
+ 4.5.5. References Section
+ 4.5.5.1. URIs in Specifications
+ 4.5.5.2. Referencing Specifications
+ 4.5.5.3. Referencing Other Standards Development Organizations
+ 4.6. Appendices Section
+ 4.7. Acknowledgements Section
+ 4.8. Contributors Section
+ 4.9. Author's Information Section
+5. Security Considerations
+6. References
+ 6.1. Normative References
+ 6.2. Informative References
+
+---
+
+1. Introduction
+
+ The ultimate goal of the Specification publication process is to produce
+ documents that are readable, clear, consistent, and reasonably uniform. The
+ basic formatting conventions for Specifications were established in August
+ 2018. This document describes the fundamental and unique style conventions
+ and editorial policies currently in use for the Specification Series. It is
+ intended as a stable, infrequently updated reference for authors, editors,
+ and reviewers.
+
+ The world of technical publishing has generally accepted rules for grammar,
+ punctuation, capitalization, sentence length and complexity, parallelism,
+ etc.
+
+ All Specifications begin as Drafts, and a well-written and properly
+ constructed Draft provides a strong basis for a good Specification.
+
+2. Key Words
+
+ In many standards track documents several words are used to signify the
+ requirements in the specification. These words are often capitalized. This
+ document defines these words as they should be interpreted in Specification
+ Documents. Authors who follow these guidelines should incorporate this
+ phrase near the beginning of their document:
+
+ 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 SPEC0003.
+
+ Note that the force of these words is modified by the requirement level of
+ the document in which they are used.
+
+2.1. MUST
+
+ This word, or the terms "REQUIRED" and "SHALL", mean that the definition is
+ an absolute requirement of the specification.
+
+2.2. MUST NOT
+
+ This phrase, or the phrase "SHALL NOT", mean that the definition is an
+ absolute prohibition of the specification.
+
+2.3. SHOULD
+
+ This word, or the adjective "RECOMMENDED", mean that there may exist valid
+ reasons in particular circumstances to ignore a particular item, but the full
+ implications must be understood and carefully weighed before choosing a
+ different course.
+
+2.4. SHOULD NOT
+
+ This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist
+ valid reasons in particular circumstances when the particular behavior is
+ acceptable or even useful, but the full implications should be understood
+ and the case carefully weighed before implementing any behavior described
+ with this label.
+
+2.5. MAY
+
+ This word, or the adjective "OPTIONAL", mean that an item is truly
+ optional. One vendor may choose to include the item because a particular
+ marketplace requires it or because the vendor feels that it enhances the
+ product while another vendor may omit the same item. An implementation
+ which does not include a particular option MUST be prepared to interoperate
+ with another implementationn which does include the option, though perhaps
+ with reduced functionality. In the same vein an implementation which does
+ include a particular option MUST be prepared to interoperate with another
+ implementation which does not include the option (except, of course, for the
+ feature the option provides).
+
+2.6. Guidance in the use of these Imperatives
+
+ Imperatives of the type defined in this section must be used with care and
+ sparingly. In particular, they MUST only be used where it is actually
+ required for interoperation or to limit behavior which has potential for
+ causing harm (e.g., limiting retransmissions). For example, they must not
+ be used to try to impose a particular method on implementors where the
+ method is not required for interoperability.
+
+2.7. Security Considerations
+
+ These terms are frequently used to specify behavior with security
+ implications. The effects on security of not implementing a MUST or SHOULD,
+ or doing something the specification says MUST NOT or SHOULD NOT be done
+ may be very subtle. Document authors should take the time to elaborate the
+ security implementations of not following recommendations or requirements
+ as most implementors will not have had the benefit of the experience and
+ discussions that produced the specification.
+
+3. Specification Style Conventions
+
+ This Style Guide does not use the terminology as defined in section 2.
+
+3.1. Language
+
+ The Specification publication language is English. Spelling may be either
+ American or British, as long as an individual document is internally
+ consistent. Where both American and British English spelling are used within
+ a document or cluster of documents, the text will have to be modified to be
+ consistent with American English spelling.
+
+3.2. Punctuation
+
+ - No overstriking (or underlining) is allowed.
+
+ - When a sentence ended by a period is immediately followed by another
+ sentence, there must be two blank spaces after the period.
+
+ - A comma is used before the last item of a series, e.g.,
+
+ "TCP service is reliable, ordered, and full duplex"
+
+ - When quoting literal text, punctuation is placed outside quotation marks,
+ e.g.,
+
+ Search for the string "Error Found".
+
+ When quoting general text, such as general text from another Specification,
+ punctuation may be included within the quotation marks.
+
+ Quotation marks are not necessary when text is formatted as a block
+ quotation.
+
+3.3. DNS Names and URIs
+
+ Angle brackets are strongly recommended around URIs, e.g.,
+
+ <http://example.org/>
+
+3.4. Capitalization
+
+ - Capitalizationn must be consistent within the document and ideally should
+ be consistent with related specifications. Refer to the online table of
+ decisions on consistent usage of terms in Specifications.
+
+ - Per CMOS guidelines, the major words in Specification titles and section
+ titles should be capitalized (this is sometimes called "title cases").
+ Typically, all words in a title will be capitalized, except for internal
+ articles, prepositions, and conjunctions.
+
+ - Section titles that are in sentence form will follow typical sentence
+ capitalization.
+
+ - Titles of figures may be in sentence form or use title case.
+
+3.5. Citations
+
+ - References and citations must match. That is, there must be a reference
+ for each citation used. and vice versa.
+
+ - Citations must be enclosed in square brackets (e.g., "[CITE1]").
+
+ - A citation/reference tag must not contain spaces.
+
+ Example: "[SPEC0003]" rather than "[SPEC 0003]"
+
+ However, the proper textual naming of a Specification contains a space.
+
+ Example: "See SPEC 0003 for more information."
+
+ - Cross-references within the body of the document and to other documents
+ must use section numbers rather than page numbers, as pagination may change
+ per format and device.
+
+3.6. Abbreviation Rules
+
+ Abbreviations should be expanded in document titles and upon first use in the
+ document. The full expansion of the text should be followed by the
+ abbreviation itself in parenthesis. The exception is an abbreviation that is
+ so common that the readership of Specifications can be expected to recognize
+ it immediately; examples include (but are not limited to) TCP, IP, SNMP, and
+ HTTP. Some cases are marginal, and the author should make the final
+ judgement, weighing obscurity agains complexity.
+
+4. Structure of a Specification
+
+ A published Specification will largely contain the elements in the following
+ list. Some of these sections are required, as noted. Sections are allowed
+ to contain nothing but subsections. The rules for each of these elements are
+ described in more details below.
+
+ First-page header [Required]
+ Title [Required]
+ Abstract [Required]
+ Copyright Notice [Required]
+ Table of Contents [Required]
+ Body of the Memo [Required]
+ 1. Introductionn [Required]
+ 2. Requirements Language
+ 3. ...
+ MAIN BODY OF THE TEXT
+ 6. ...
+ 7. Internationalization Considerations
+ 8. Security Considerations [Required]
+ 9. References
+ 9.1. Normative References
+ 9.2. Informative References
+ Acknowledgements
+ Contributors
+ Author's Information [Required]
+
+ Within the body of the document, the order shown above is strongly
+ recommended. Exceptions may be questioned. Outside the body of the
+ document, the order above is required. The section numbers above are for
+ illustrative purposes; they are not intended to correspond to required
+ numbering in a Specification.
+
+4.1. First-Page header
+
+ Headers will follow the format described in "RFC Streams, Headers, and
+ Boilerplates" [RFC5741] and it's successors. In addition, the following
+ conventions will apply.
+
+4.1.1. Author/Editor
+
+ The determination of who should be listed as an author or editor on a
+ Specification is made by the stream.
+
+ The author's name (initial followed by family name) appears on the first line
+ of the heading. Some variation, such as additional initials or
+ capitalization of family name, is acceptable. Once the author has selected
+ how their name should appear, they should use that display consistently in
+ all of their documents.
+
+ The total number of authors or editors on the first page is generally limited
+ to five individuals and their affiliations. If there is a request for more
+ than five authors, the stream-approving body needs to considor if one or two
+ editors should have primary responsibility for this document, with the other
+ individuals listed in the Contributors or Acknowledgements section. There
+ must be a direct correlation of authors and editors in the document header
+ and the Authors' Information section. These are the individuals that must
+ sign off on the document and respond to inquiries.
+
+4.1.2. Organization
+
+ The author's organization is indicated on the line following the author's
+ name.
+
+ For multiple authors, each author name appears on its own line, followed by
+ that author's organization. When more than one author is affiliated with the
+ same organization, the organization can be "factored out", appearing only
+ once following the corresponding Author lines. However, such factoring is
+ inappropriate when it would force an unacceptable reordering of author names.
+
+ If an author can not or will not provide an affiliation for any reason,
+ "Independent", "Individual Contributor", "Retired", or some other term that
+ appropriately describes the author's affiliation may be used. Alternatively,
+ a blank line may be included in the document header where no affiliation is
+ provided.
+
+4.1.3. Updates and Obsoletes
+
+ When a Specification obsoletes or updates a previously published
+ Specification or Specifications, this information is included in the document
+ header. For example:
+
+ "Updates: nnnn" or "Updates: nnnn, ..., nnnn"
+
+ "Obsoletes: nnnn" or "Obsoletes: nnnn, ..., nnnn"
+
+ If the document updates or obsoletes more than one document, numbers will be
+ listed in ascending order.
+
+4.2. Full Title
+
+ The title must be centered below the rest of the heading, preceded by two
+ blank lines and followed by one blank line.
+
+ Choosing a good title for a Specification can be a challenge. A good title
+ should fairly represent the scope and purpose of the document without being
+ either too general or too specific and lengthy.
+
+ Abbreviations in a title must generally be expanded when first encountered
+ (See section 3.6 for additional guidance on abbreviations).
+
+ It is often helpful to follow the expansion with the parenthesized
+ abbreviation, as in the following example:
+
+ Encoding Rules for the
+ Common Routing Encapsulation Extension Protocol (CREEP)
+
+4.3. Abstract Section
+
+ Every Specificationn must have an Abstract that provides a concise and
+ comprehensive overview of the purpose and contents of the entire document, to
+ give a technically knowledgeable reader a general overview of the function of
+ the document.
+
+ Composing a useful Abstract generally requires thought and care. Usually, an
+ Abstract should begin with a phrase like "This memo ..." or "This document
+ ...". A satisfactory Abstract can often be constructed in part from material
+ within the Introduction section, but an effective Abstract may be shorter,
+ less detailed, and perhaps broader in scope than the Introduction. Simply
+ copying and pasting the first few paragraphs of the Introduction is allowed,
+ but it may result in an Abstract that is both incomplete and redundant. Note
+ also that an Abstract is not a subsitute for an Introduction; the
+ Specification should be self-contained as if there were no Abstract.
+
+ Similarly, the Abstract should be complete in itself. It will appear is
+ isolation in publication announcements. Therefore, the Abstract must not
+ contain citations.
+
+4.4. Table of Contents Section
+
+ A Table of Contents (TOC) is required in all Specifications. It must be
+ positioned after the Copyright Notice and before the Introduction.
+
+4.5. Body of the Specification
+
+ Following the TOC is the body of the document.
+
+ Each Specification must include an Introduction section that (among other
+ things) explains the motivation for the Specification and (if appropriate)
+ describes the applicability of the document, e.g., whether it specifies a
+ protocol, provides a discussion of some problem, is simply of interest to the
+ Internet community, or provides a status report on some activity. Thebody of
+ the document and the Abstract must be self-contained and separable. This may
+ result in some duplication of text between the Abstract and the Introduction;
+ this is acceptable.
+
+4.5.1. Introduction Section
+
+ The Introduction section should always be the first section following the
+ TOC. While "Introduction" is recommended, authors may choose alternate
+ titles such as "Overview" or "Background". These alternates are acceptable.
+
+4.5.2. Requirements Language Section
+ 4.5.3. Internationalization Considerations Section
+ 4.5.4. Security Considerations Section
+ 4.5.5. References Section
+ 4.5.5.1. URIs in Specifications
+ 4.5.5.2. Referencing Specifications
+ 4.5.5.3. Referencing Other Standards Development Organizations
+ 4.6. Appendices Section
+ 4.7. Acknowledgements Section
+ 4.8. Contributors Section
+ 4.9. Author's Information Section
+5. Security Considerations
+6. References
+ 6.1. Normative References
+ 6.2. Informative References
