~name codatext ~type document ~title CodaText Format Specification ~summary Specification of the text format for Coda docifier program. ~author Agnar Renolen ~version 1.3 ~date August 17th, 2001 INTRODUCTION /CodaText/ is a text format designed for documenting source code by writing the documentation as comments within the source files. The main purpose of designing this format is to provide a text format that is * easy to read * easy to write * easy to remember * fairly easy to parse However, it can also be used to write ordinary documents, such as this specification itself. In case you are reading the html-version of the spec, you are recommended to see the @{format.txt original CodaText source}. A CodaText document, document item, or /doc-item/ in snort, is divided into two sections: the /header/ and the /body/. THE HEADER The /header/ consists of a number of key - value pairs. The keys are identifyied by the initial "~" character, while the value will comprise the rest of the line. However, only one of the keys are mandatory: the "~name" key. Each key-value pair must only occupy one line of text. The following example is a replication of the header of this document: [ ~name codatext ~type document ~title CodaText Format Specification ~summary Specification of the text format for Coda docifier program. ~author Agnar Renolen ~version 1.3 ~date August 6th, 2001 ] The recognized keys are: -name: This is a mandatory key, and the value must be a string containing no spaces. If you want to reffer to a document from another document, this is the name you should reffer to. If you are documenting a class or a procedure, the name should be equal to the name of the class or procedure. Names can be set up hierarchically, by specifying sub-names separated by a /name space separator/ which is either a period (like in MyClass.MyMethod) or a double colon (like in MyClass::MyMethod). -title: For a document like this, a title is appropriate. If you are documenting a procedure, it is recommended to leave the title undefined. -summary: Gives a brief one-line summary of the document. You can add several subsequent summary keys, if you need multiple lines. -author: Specifies the author of the document. This element may be repeated multiple times in the header if there are multiple authors. -version: Specifies the version of the document. -date: Specifies the date of writing, or the date of approval of the document. -mansection: If coda is to produce output in Unix man page format (nroff\/troff), this specifies which man section the doc-item is to be put. -type: Specifies the type of document item. If this is not specified in the header, the value will be set to "item" as the default. If the type is set to "document", then coda will produce a standalone document for this item, rather than including it in a larger project. The header ends automatically by the first line that does not start with the "~" character. The text following the header is referred to as the /body/ of the document. You may add your own header items at your own discression, although these will be ignored by Coda. CodaText also allows you to provide a compact form of header containing only the name and optionally a summary: If the first non-empty line of the doc-item does not start with a key prefixed by the "~" character, the first word will be recognized as the name. The subsequent words (optionally separated from the name by one or more dash es) will be recognized as the summary. Subsequent lines will be recognized as the summary until an empty line is encountered. Hence the following syntax applies. [ [[-]

] ] SECTIONING The body can be divided into sections by headings. CodaText specifies two levels of headings. The reason for this limitation is that one doc-item may be included into another document, one section per item, and thus effectively create three sectioning levels. Moreover, whenever several CodaText items are generated into one source file, we need one header for the name ot title of the item as well. Headings are identified by a prefix [\\h1] for level 1 headings and [\\h2] for level 2 headings. If a heading requires more than two lines of text, the second line must be alligned with the first non-prefix character of the first line. As for example [ \h1 This is a heading that is written over two lines ] To make the headings stand out mor in the source, a level 1 heading is also recognized as a paragraph containing no lowercase letters. This style of headings are used in this document. If you need to write a normal paragraph in captial letters, you can do thus be prefixing the paragraph with the [\\p] paragraph prefix. PARAGRAPHS AND INDENTATION The body of the text is, apart from sections, divided into units called /paragraphs/. A paragraph is identified in either of three ways: * They are separated from other paragraphs by at least one empty line. * The first line is prefixed with one of CodaText's predifined paragraph type markers. * They are separated from other paragraphs by having different indentation. The last way of separating paragraphs allows you to make your documentation text a little more compact. For example, you don't need to insert an empty line between a heading and the subsequent paragraph if you provide different indentation: [ THIS IS A LEVEL 1 HEADING This is the first paragraph in this section. ] Note that the indentation of the text does not reckon prefixes as being a part of the text, which is illustrated in the following example: [ \h1 This is a heading This is a paragraph, and not the next line of the heading * This is an item This is not a part of the item above. * This is an item that goes over two lines ] Indentation, can also be used to create nested lists, as the subsequent section describes. LISTS CodaText provides three types of lists: /itemized lists/, /enumerated lists/ and /description lists/. The example below demonstrates itemized and enumerated lists: [ * Each list item is a paragraph marked with a prefix. The prefix in this itemized list is the asterix ("*"). * Lists can also be nested within each other by increasing the indentation of the list items: (1) The prefix of an enumerated list is the a number embeded between a pair of parenthesis. (2) A list should have at least two items. A list item can also contain several paragraphs. * Since this item has the same indentation as the previous item, we are back in the outer list. * Blank lines between the items have no effect. ] This example should produce the output: * Each list item is a paragraph marked with a prefix. The prefix in this itemized list is the asterix ("*"). * Lists can also be nested within each other by increasing the indentation of the list items: (1) The prefix of an enumerated list is the a number embeded between a pair of parenthesis. (2) A list should have at least two items. A list item can also contain several paragraphs. * Since this item has the same indentation as the previous item, we are back in the outer list. * Blank lines between the items have no effect. The items of a description list contain pairs of values: -the key: Which is a single-line paragraph prefixed with a dash ("-"), and ending in a colon ":". No other text is permitted on this line. -the description: Which is the subsequent paragraph. Usually, this should be slightly indented from the key to make it readable, although this is not required. The description can also contain several paragraphs, although you have to do that by separating them with an empty line. The description list above is produced from the following text: [ -the key: Which is a single-line paragraph prefixed with a dash ("-"), and ending in a colon ":". No other text is permitted on this line. -the description: Which is the subsequent paragraph. Usually, this should be slightly indented from the key to make it readable, although this is not required. The description can also contain several paragraphs, although you have to do that by separating them with an empty line. ] COMPUTER VOICE When documenting code, you often need to provide code examples, or output\/input into functions and procedures. For this we use /computer voice/, which is ususally presented in a monospace typewriter-style font such as Courier. If you need to provide a code example, you should use /preformated text/ as demonstrated in the following example: [ [ To provide formatted text, start with a single line containing only a left square bracket "[". A block of preformatted text is considered as one single paragraph, so empty lines or different indentation will be reproduced verbatim in the output. The indentation of the coda will be reckoned relatively from the first "[". ] ] In order to end the preformatted text, you must provide a single line containining only a right square bracket "\]", having the exact same indentation as the initial bracket. This allows the preformatted text to have lines containing a single "\]" if it has a different indentation that the initial one. As was necessary to produce the example of preformatted text above. When you need to produce computer voice in running text, embrace the text in [\[square brackets\]]. Whenever you are reffering to a metasymbol (that is, an artificial term that has meaning only when it is replaced by a value or symbol), embrace it in [\]. Metasymbols are usually presented in italic text, but to avoid confusion with ordinary emphasized terms, Coda also presents metasymbols in a monospace font. CodaText allows you to nest these markup tags into each other. The following example reproduces the synopsis of the tcl [array] command: [ [array