v0.4.1/spec.txt			v0.4.2/spec.txt
f	1	Identify requirements within plain-text specifications	f	1	Identify requirements within plain-text specifications
	2			2
	3	Status of This Memo		3	Status of This Memo
	4			4
	5	This document is not an Internet Standards Track specification; it is		5	This document is not an Internet Standards Track specification; it is
	6	published for examination, experimental implementation, and		6	published for examination, experimental implementation, and
	7	evaluation.		7	evaluation.
	8			8
	9	Abstract		9	Abstract
	10			10
	11	Plain-text specifications are readable and many follow [RFC 2119]		11	Plain-text specifications are readable and many follow [RFC 2119]
	12	when phrasing requirements.  This specification introduces a syntax		12	when phrasing requirements.  This specification introduces a syntax
	13	to augment such requirements with identifiers for easy reference.		13	to augment such requirements with identifiers for easy reference.
	14			14
	15	§1 Introduction		15	§1 Introduction
	16			16
	17	Being able to reference a requirement within a large document aids		17	Being able to reference a requirement within a large document aids
n	18	many stakeholders within projects.  Author and reviewer while the	n	18	many stakeholders.  Author and reviewer while the specification is
	19	specification is being written and discussed.  The developer during		19	being written and discussed.  The developer during implementation and
	20	implementation and testing.  Customer while accepting the final		20	testing.  Customer while accepting the final product.
	21	product.
	22			21
	23	A test suite could e.g. use the wording of a requirement verbatim if		22	A test suite could e.g. use the wording of a requirement verbatim if
	24	it fails, by parsing the referenced requirement.  Having a way to		23	it fails, by parsing the referenced requirement.  Having a way to
	25	easily index all requirements and reference them elsewhere keeps the		24	easily index all requirements and reference them elsewhere keeps the
	26	requirements at it's source.		25	requirements at it's source.
	27			26
	28	§1.2 Requirements		27	§1.2 Requirements
	29			28
	30	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",		29	The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
	31	"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this		30	"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
	32	document are to be interpreted as described in [RFC 2119].		31	document are to be interpreted as described in [RFC 2119].
	33			32
	34	§2 Requirement Identifier Syntax		33	§2 Requirement Identifier Syntax
	35			34
	36	Requirement identifiers MUST(R1) be placed directly after keywords as		35	Requirement identifiers MUST(R1) be placed directly after keywords as
	37	defined by [RFC 2119].  Requirement identifiers SHOULD(R2) be written		36	defined by [RFC 2119].  Requirement identifiers SHOULD(R2) be written
	38	within parenthesis and start with 'R' followed by a number.  This		37	within parenthesis and start with 'R' followed by a number.  This
	39	combination is less likely to conflict with normal wording and use of		38	combination is less likely to conflict with normal wording and use of
	40	parenthesis within a document.  Requirement identifiers MUST(R3) be		39	parenthesis within a document.  Requirement identifiers MUST(R3) be
	41	unique within one specification.		40	unique within one specification.
	42			41
	43	Example;		42	Example;
	44			43
	45	"... MUST NOT(R1) .." ok		44	"... MUST NOT(R1) .." ok
n			n	45	"... SHOULD\nNOT(R1)" ok, keyword split over two lines
				46
				47	the following examples are wrong
				48
	46	"... SHOULD ..."      missing identifier		49	"... SHOULD ..."     missing identifier
	47	"... MAY (R1) ..."    error spacing after keyword		50	"... MAY (R1) ..."   spacing after keyword
	48	"... SHOULD\nNOT(R1)" ok when keyword split over two lines		51	"... MAY\n(R1) ..."  new line between keyword and identifier
				52
	49			53
	50			54
	51	It is RECOMMENDED(R4) that authors do not use identifier series for		55	It is RECOMMENDED(R4) that authors do not use identifier series for
	52	grouping, e.g. identifiers within the R100 series are used for		56	grouping, e.g. identifiers within the R100 series are used for
	53	feature X and R200 series for feature Y.  It is also RECOMMENDED(R5)		57	feature X and R200 series for feature Y.  It is also RECOMMENDED(R5)
t	54	that authors not change identifiers for one requirement over time.	t	58	that authors not change identifiers for one requirement once a
	55	This is however likely to happen more during authoring and reviewing		59	specification is published.  This is however likely to happen during
	56	phase but should be avoided once a specification is published.		60	authoring and reviewing phase.  Assign identifiers late in the
				61	process.
	57			62
	58			63
	59			64
	60	[RFC 2119]: https://www.ietf.org/rfc/rfc2119		65	[RFC 2119]: https://www.ietf.org/rfc/rfc2119

Legends
Colors  Added  Changed Deleted	Links (f)irst change (n)ext change (t)op