document.txt (9050B)
1 Specification: 0000 Robin Bron 2 Obsoleted by: 0003 August 2018 3 4 5 Specification Format 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 Copyright Notice 53 54 This document is licensed under a 55 Creative Commons Attribution 4.0 International License 56 57 You should have received a copy of the license along with this work. If not, 58 see <http://creativecommons.org/licenses/by/4.0/> 59 60 Bron [Page 1] 61 SPEC 0000 Specification Format August 2018 62 63 Table of contents 64 65 1. Conventions ........................................................... 3 66 2. Character encoding .................................................... 3 67 3. Line definition ....................................................... 3 68 3.1 Line numbering .................................................... 3 69 4. Pages ................................................................. 3 70 4.1 Page header ....................................................... 3 71 4.2 Page footer ....................................................... 3 72 5. Paragraphs ............................................................ 3 73 6. Document header ....................................................... 4 74 6.1. Descriptive header ............................................... 4 75 6.2. Short author identification ...................................... 4 76 6.3. Publish date ..................................................... 4 77 7. Document footer ....................................................... 5 78 8. Section titles ........................................................ 5 79 9. Document title ........................................................ 5 80 10. Informative resources ................................................. 6 81 11. Author information .................................................... 7 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 Bron [Page 2] 121 SPEC 0000 Specification Format August 2018 122 123 1. Conventions 124 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 126 "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 127 document are to be interpreted as described in RFC2119 when, and only when, 128 they appear in all capitals, as shown here. 129 130 2. Character Encoding 131 132 Plain-text files for specifications MUST use the UTF-8 standard. 133 134 3. Line definition 135 136 A line of text is a sequence of 0 or more characters followed by a line feed 137 character. For the sake of and clarity, the ending line feed character is not 138 part of the line. 139 140 Lines MUST NOT exceed 80 characters in length, excluding the ending line feed 141 character. A line is called a blank line if it consists of 0 characters. 142 143 3.1. Line numbering 144 145 Assuming a document is in digital format[1] and has a length of greater than 146 0 bytes, the first character in the document is part of line 1. 147 148 4. Pages 149 150 A page is a sequence of 60 lines. That means for every line number n, the 151 line is the start of a new page when n mod 60 = 1. 152 153 4.1 Page header 154 155 The first line of a page SHOULD consist of a left-aligned spec number 156 indicator, a centered (short) document title and a right-aligned short 157 publishing date (see 6.3). Line 2 of a page MUST always be blank, excluding 158 the first page of the document. 159 160 4.2 Page footer 161 162 The last line of a page MUST consist of a left-align last name of the 163 author or authors and a right-aligned page number between square brackets. 164 The second-to-last line of a page must be blank, just like line 2 of a page. 165 166 5. Paragraphs 167 168 A paragraph is a sequence of consecutive lines all of a length greater than 0 169 characters. Paragraphs are separated by either one or more blank lines or a 170 page break. Paragraphs MUST NOT span multiple pages, limiting their size to 171 56 lines. 172 173 174 175 176 177 178 179 180 Bron [Page 3] 181 SPEC 0000 Specification Format August 2018 182 183 6. Document header 184 185 The first lines of the first page of a specification document MUST always 186 contain left-aligned description headers (see 6.1) and right-aligned author 187 identification and a right-aligned publishing date. 188 189 After the initial lines (see 6.1 through 6.3), references to other 190 specifications MUST be included when the specification obsoletes or updates 191 the references specification. 192 193 After the initial lines and the references, the document title is REQUIRED to 194 be written on the first page of the document. For it's specification, see 195 section 9. 196 197 The bottom of the first page of the document MUST include a copyright notice 198 and/or license, a link to the license or the inclusion text required by the 199 license in question. 200 201 6.1. Descriptive header 202 203 Each descriptive header is made up of a key and a value. Whitespace is not 204 allowed in both the key and the value. Whitespace can only be included in the 205 value by wrapping the value in quote characters. 206 207 The key of the header consists of all characters of the line up to the first 208 semicolon, excluding the semicolon itself and omitting all white-space 209 characters. 210 211 The value of the header starts at the first non-whitespace character after 212 the first semicolon of the line. If the first character is a quote, the value 213 ends at the next quote in the line. If the first character is not a quote, 214 the value ends at the next whitespace character. 215 216 6.2. Short author identification 217 218 In order to allow the author or authors to take some credit and to track who 219 has written what, the author's name MUST be added right-aligned on the first 220 line of the first page of the document. To prevent mixing notations between 221 documents, the names SHOULD be written as only the first letters of all given 222 names in capitals, separated by dots, a space and the Family name starting 223 with an uppercase character. When written by a group with a name, the short 224 author identification string SHOULD state the group's name instead of the 225 individual authors. 226 227 6.3. Publish date 228 229 Dates contained in specification documents following the format described in 230 this document MUST follow the Gregorian calendar. 231 232 The publish date of the document MUST include a month starting with a capital 233 character and fully written year. The day of the month MAY be added on the 234 first page of the document, but MUST NOT be included in the short date on all 235 pages. 236 237 238 239 240 Bron [Page 4] 241 SPEC 0000 Specification Format August 2018 242 243 7. Document footer 244 245 The document SHOULD close, starting on a new page, with all informative 246 resources which were used to write the document, noting their keyword and 247 document title. A URI to the resource SHOULD be included. 248 249 After the informative resources, the document SHOULD end with one or several 250 pages dedicated to the information of the author or authors. 251 252 8. Section titles 253 254 Section titles SHOULD be a short text about the subject the section 255 describes. Whether it is simply the keyword of what it explains, a problem 256 statement or other type of text is up to the author as long as it's relevant 257 to the section's body and fits within a single line. 258 259 A section title MUST start with a capital character & MUST NOT contain any 260 other capital letters, excluding where they are required in names or 261 abbreviations. 262 263 9. Document title 264 265 The title of the document should clearly state the main subject of the 266 document and it's contents. Each word of the document title MUST start with a 267 capital character when noted as the title of the document. 268 269 On the first page of the document, the title should be centered horizontally 270 and have at least 2 blank lines both above and below it. The document title 271 SHOULD be as close to the document's descriptive headers as possible. 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 Bron [Page 5] 301 SPEC 0000 Specification Format August 2018 302 303 10. Informative resources 304 305 [RFC2119] RFC Key Words 306 S. Bradner 307 https://tools.ietf.org/html/rfc2119 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 Bron [Page 6] 361 SPEC 0000 Specification Format August 2018 362 363 11. Author information 364 365 Name ....... Robin Bron 366 Nickname ... Finwo 367 EMail ...... robin@finwo.nl 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 Bron [Page 7]