specifications

Specification and standard documents
git clone git://git.finwo.net/misc/specifications
Log | Files | Refs | README | LICENSE

commit 6aad6ccb80fd35dffc6f7a0d1c18a8fb48b566cd
parent 2b7c58b1b1f0aae83474e2dc6601b67ffd9d416f
Author: finwo <finwo@pm.me>
Date:   Tue, 28 Apr 2020 11:01:07 +0200

Removed unused markdown template

Diffstat:
Dsrc/0000.md | 137-------------------------------------------------------------------------------
1 file changed, 0 insertions(+), 137 deletions(-)

diff --git a/src/0000.md b/src/0000.md @@ -1,137 +0,0 @@ -Date: 2018-08-15 -author: Robin Bron <robin@finwo.nl> -organization: Ratus B.V. -title: Specification Format - -# Convections: - -<RFC2119 - -# Character encoding - -Plain-text files for specifications MUST use the `CP437` standard with the -exclusion of character code 0x0A which represents a line feed as specified in -`RFC20`. - -# Line definition - -A line of text is a sequence of 0 or more characters followed by a line feed -character. For the sake of and clarity, the ending line feed character is -part of the line. - -Lines MUST NOT exceed 72 characters in length, including the ending line feed -character. A line is called a blank line if it consists of only a line feed -character. - -# Line numbering - -To ensure the following page dimension section is clear, we need to define -how lines are numbered. - -Assuming a document is in digital format and has a length of greater than -0 bytes, the first character in the document is part of line 0. Numbering -lines from 0 instead of 1 gives us an advantage of clarity in the next -section. - -# Pages - -A page is a sequence of 60 lines. That means for every line number n, the -line is the start of a new page when $$ n mod 60 = 0 $$. - -## Page header - -The first line of a page SHOULD consist of a left-aligned spec number -indicator, a centered (short) document title and a right-aligned publishing -date (see [Document header][document header]). The second line of a page MUST -always be blank, excluding the first page of the document. - -## Page footer - -The last line of a page MUST consist of a left-align last name of the author -and a right-aligned page number between square brackets. The second-to-last -line of a page must be blank, just like the second line of a page. - -# Paragraphs - -A paragraph is a sequence of consecutive lines containing characters other -than only a line feed. Paragraphs are separated by either a blank line or a -page break. Paragraphs MUST NOT span multiple pages, limiting their size to -56 lines. - -# Document header - -The first lines of the first page of a specification document SHALL always -contain left-aligned description headers (see -[Descriptive header][descriptive header]) and right-aligned author -identification and a right-aligned publishing date. - -After the initial lines (see [Descriptive header][descriptive header] through -[Publish date][publish date]), the document title is REQUIRED to be written -on the first page of the document. For it's specification, see section -[document title][document title]. - -Further information on the first page should give a quick description of the -contents of the document. - -## Descriptive header - -Each descriptive header is made up of a key and a value. Whitespace is not -allowed in both the key and the value. Whitespace can only be included in the -value by wrapping the value in quote characters. - -The key of the header consists of all characters of the line up to the first -semicolon, excluding the semicolon itself and omitting all white-space -characters. - -The value of the header starts at the first non-whitespace character after -the first semicolon of the line. If the first character is a quote, the value -ends at the next quote in the line. If the first character is not a quote, -the value ends at the next whitespace character. - -## Short author identification - -In order to allow authors to take some credit and to track who has written -what, the author's name MUST be added right-aligned on the first line of the -first page of the document. To prevent mixing notations between documents, -the names SHOULD be written as only the first letters of all given names in -capitals, separated by dots, a space and the Family name starting with a -capital. When written by a group with a name, the short author identification -string SHOULD state the group's name. - -## Publish date - -Because a document is unlikely to have been written within a day, a publish -date is simply the month's name starting with a capital followed by the year, -both following the Gregorian calendar. - -# Document footer - -The document SHOULD close, starting on a new page, with all informative -resources which were used to write the document, noting their keyword and -document title. When possible, a URL to the resource SHOULD be included. - -After the informative resources, the document SHOULD end with one or several -pages dedicated to the information of the author(s) and if possible their -contact information. - -# Section titles - -Section titles SHOULD be a short text about the subject the section -describes. Whether it is simply the keyword of what it explains, a problem -statement or other type of text is up to the author as long as it's relevant -to the section's body. - -A section title MUST start with a capital character & MUST NOT contain any -other capital letters, excluding where they are required in names or -abbreviations. - -# Document title - -The title of the document should clearly state the main subject of the -document and it's contents. Each word of the document title must start with a -capital character when noted as the title of the document. - -On the first page of the document, the title should be centered horizontally -and have at least 2 blank lines both above and below it. The document title -SHOULD be as close to the document's descriptive headers as possible. -