.Open Formatting . Introduction MATHS is not a mark-up language. Marking up a text for publication should be a service provided by a MATHS support environment. However recent research has shown that source code documentation (1) organized in a book like structure (chapters, sections,...Close, (2) Printed with italics or boldface indicating defined terms, and (3) not laid out in the traditional indented style is significantly easier to understand than the norm for source code .See [BaeckerMarcus90] .See [OmanCook90] .See [VanWyk86-88]. Similarly it clear that documentation is best represented not as a linear text accessed sequentially but as a data base or a set of hypertext files. The Software Engineering Institute(SEI) has rediscovered the importance of document analysis and design (with outlines, user reviews, testing, and revision) and stresses the need for internal tables of contents, extensive headings and subheadings, and generous whitespace (SEI Bridge December 1992 Sidebar page 13]. Minimally an author needs to be able to indicate the structure of a document and to name the parts. Ideally this should be a simple and natural task. Others need to be able to refer to these parts and subject to copyright and plagiarism rules reuse them[Ted Nelson]. ODA (Offfice Document Architecture) provides this facility and explicitly divorces the "look and fell" of the document from its logical structure[CCITT T.410, ECMA-101(1985)) . ODA is defined by using SGML. SGML (Standard Generalized Mark-up Language) is general way to let new document structures be defined and manipulated [ISO 8613(July 1988)]. In turn SGML has been used to define the rich text format for Internet mail (MIME text/richtext). Therefore MATHS lets the user indicate the format, structure and content of a piece of documentation by using `directives`. Information about these named parts, their scope etc is produced during lexical analysis as a contents list for the document. Each item in the contents list comes from a directive and has the level, an identifier and a position in the text (by line and character numbers, or a unique tag ). Access to the parts is as if it is via such a contents list. However the enormous number of existing ways in which a piece of documentation can be written, named, used, etc makes designing a stable solution very difficult. A possible way forward is to assume that directives name the processes to be applied to the text on input and/or presentation. Thus a piece of a document might have the attribute of being written in PostScript. Another might be a piece TeX. A directive would indicate that PostScript or TeX can be invoked to interpret these pieces of input. Another example might be to indicate that a section opens here and continues to a matching closer. Most word processors can produce plain text ASCII with a loss of structure but also provide a way to re-encode the document in DCA-RFT(IBM's Document Content Architecture - Revisable Form Text). The WAISindex has half-dozen-forms including a file with records divided by a line of dashes, or records separated by blank lines, ... .Open Formats Formats describe a desired high-level `look` of parts of the text but do not specify particular fonts, layouts, etc. The formats can be removed to abstract an outline. These formats contribute to the readability of MATHS without changing its formal meaning. Users can use tools to automatically generate a first draft. Local software can be developed to translate formats plus syntax analysis into TEX, nroff/troff, Postscript, and SGML in the `house style`. The set of formats can be given for a piece of text - thus indicating inclusion of multiple views of the same data. A formatting directive can be put in front of a definition to indicate a desirable presentation. Some formats also define formulae: lists, sets and tables have formal interpretations as vectors, sets, and relations. .Open Formatted definitions . Introduction Long definitions can take a number of different forms. They all let you attach a name to a formatted piece of semi-formal text. The form of the text can be a box, table, list, section, set, or the more specialized nets o definitions and lets used to prove things. Each $form_of_closed_definition has a format, a start tag and an end tag as described by the following table. form_of_closed_documentation::Sets=following, .Table Format Tag End-Tag Purpose Likely Type .Row list ".List" ".Close.List" Represents an ordered list or sequence .Item #(...) .Row set ".Set" ".Close.Set" An unordered (mathematical) set .Item @(...) .Row table ".Table" ".Close.Table" Present relations, databases, functions,... .Item @(..., ..., ...) .Row subsection ".Open" ".Close" Organize a text into sections and subsections. .Row box ".Box" ".Close.Box" Place set of formula etc in a box .Row let ".Let" ".Close.Let" Used in proofs .Row net ".Net" ".Close.Net" Collects definitions, axioms, theorems etc. together. .Close.Table Notice that the above is an example of such a named piece of documentation that defines the Format, Tag, and End-Tag of the defined forms of closed documentation. . Syntax DC::=http://www/dick/maths/notn_13_Docn_Syntax.html. (DC)|- definition::= $short_definition | $long_definition. (DC)|- short_definition::=optional_shorthand defined_term definer (expression | structure | summary_form ). (DC)|- long_definition::= term definer "following," $closed_piece_of_documentation. (DC)|- closed_piece_of_documentation::= list | set | table | box | net | section | ... . closed_piece_of_documentation::= | [ f:form_of_closed_documentation]( f.Tag EOLN piece_of_documentation EOLN f.EndTag EOLN). A long definition introduces another level into the document. The difference from a named section is that the defined term can be used in a well-formed-formula or definition, whereas a section name can not. .Close Formatted definitions . Missing Closing Formats A Maths document never spreads over several files. Thus any missing closing directives (.Close....) are assumed to be added at the end of the file. Optionally, but helpful, if a nested part is not terminated before the closing of an out part, then it would be nice (but not necessary) to insert the missing closing directive just before the present one. A precedent for this approach is Ada. For example: .As_is .Open A .As_is ... .As_is .Net .As_is ... .As_is .Close A means the same thing as .As_is .Open A .As_is ... .As_is .Net .As_is ... .As_is .Close.Net .As_is .Close A Any form of error message is to be avoided unless the user asks for it! Note. Current translators tend to avoid error messages but let browsers handle the malformed HTML that are generated by closing incorrectly or omitting a closer. . Standard Road Signs MATHS has a special directive .As_is .Hole and .As_is .Hole description which generates a symbol indicating a place where something can fill in the details. A place to plug things in. Rather than a traditional "person digging a hole" the current icon represents an American three pin electrical socket .Image hole.gif :o The following directives are standard but undefined. There appearance will be varied from one country to another. There are a lot more possibilities. Dangerous Bend Road Works ahead Fork Watch-out for a surprise . Added Comments and notes A reviewer can add sections or paragraph to a document. The system should insert this header: .Reviewer_comment