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 [BaeckerMarcus90] [OmanCook90] [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, ...

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.

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.
1. form_of_closed_documentation::Sets=following,
   Table

   Format	Tag	End-Tag	Purpose	Likely Type
   list	".List"	".Close.List"	Represents an ordered list or sequence	#(...)
   set	".Set"	".Close.Set"	An unordered (mathematical) set	@(...)
   table	".Table"	".Close.Table"	Present relations, databases, functions,...	@(..., ..., ...)
   subsection	".Open"	".Close"	Organize a text into sections and subsections.
   box	".Box"	".Close.Box"	Place set of formula etc in a box
   let	".Let"	".Close.Let"	Used in proofs
   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

2. DC::= See http://cse.csusb.edu/dick/maths/notn_13_Docn_Syntax.html.
3. (DC) |- definition::= short_definition | long_definition.
4. (DC) |- short_definition::=optional_shorthand defined_term definer (expression | structure | summary_form ).
5. (DC) |- long_definition::= term definer "following," closed_piece_of_documentation.
6. (DC) |- closed_piece_of_documentation::= list | set | table | box | net | section | ... .

7. 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.

. . . . . . . . . ( end of section Formatted definitions) <<Contents | End>>

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:

	.Open A

 	  ...

 	.Net

 		...

 	.Close A

means the same thing as

	.Open A

 	  ...

 	.Net

 		...

 	.Close.Net

 	.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

 	.Hole

and

 	.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

The following directives are standard but undefined. There appearance will be varied from one country to another. There are a lot more possibilities.

1. Dangerous Bend
2. Road Works ahead
3. Fork
4. 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:
5. .Reviewer_comment <name of reviewer> <date> <time>

   Insertion Directives

   A directive can also indicate the need to collect, generate and include information in place of the directive.

   The ideal support system for MATHS will include automatic content lists, and outlines, plus indexes and cross-reference lists of definitions and declarations. In interactive mode it will allow selective searching and viewing of documents as an outline and with hypertext links. It will automatically prepare readable hardcopy in the "house style" while preserving the hidden ASCII code.

   The List insertion has a special form:

   1. .List #format Thus
   2. .Figures is short for
   3. .List Figure and .Equations for
   4. .List Equations The List directive implies that the published list has names and page numbers inserted in it.

   . . . . . . . . . ( end of section Insertion Directives) <<Contents | End>>

Sample Attributes

Purposes

Abstract, Because, Chapter_heading, Code, Conclusion, Evidence, Example, Exercise, Experiment, History, Hypothesis, Head_line, Interview, Joke, Keywords, Motivation, Name, Note, Observation, Outline, Paragraph, Precedent, Quote, Reference, Remark, Requirement, Reviewer_comment, See, Specification, Subject, Summary, Theory, Therefore, Title.

Desired Appearance

As-is, Box, Digraph, Diagram, DFD, Endnote, Equation, ERD, Figure, Footnote, Graphic, List, Matrix, SADT, StateChart, Table, uuencode, VDM, Z.

Notations

Ada, APL, C, COBOL, FORTRAN, LaTeX, MIME, nroff, PostScript, Pascal, RTF, SGML, TeX, MSWord, WordPerfect.

Waisindex Formats

Krol 92(p226, table 12-1) [Krol92, Ed Krol, The Whole Internet User's Guide and Catalog, O'Reilly & Assoc, Sebastopol CA 1992, nuts@ora.com ] text, bibtex, bio, cmapp, dash, dvi, emacsinfo, first_line, gif, irg, mail_digest, mail_or_rmail, medline, mh-bboard, netnews, nhyp, one_line, para, pict, ps, refer, rn, server, tiff, ftp.

Insertions

Author, Author_signoff, Author_signature, Author_portrait, Address, EMail, Index, Bibliography, By_line, Contents, Copyrighter, Cross_references, Company_Logo, Date_line, Directives, Disclaimer, Equations, Figures, File, List, Location, Owner, Readers, Reviewers, See, Tables,..., Time_stamp, Used_by, Uses, . . .

Common Data Formats

CDF(Common Data Format), CGM(Computer Graphics Metafile), FITS (Flexible Image Transport System), DHDF (Hierarchical Data), MIME, Net CDF, PICT (macintosh bit-maps), PostScript, SDTS(Spatial Data Transfer Standard), TIFF(Tagged Image File Format), ...

MIME Content Types/Subtypes (Circa 1993)

RFC1341 text/plain, text/richtext, text/simplemail, multipart/mixed, multipart/alternative, multitype/parallel, multipart/digest, message/rfc822, message/partial, message/External-body, image/jpeg, image/gif, audio/basic, application/octet-stream, application/ODA, application/PostScript, RFC1314 image/ief

MIME Registered Application Subtypes

Baker 93, Stephen Baker, UNIX review June 1993 page 28 atomicmail, andrew-inset, slate, WITA, DEC-DX, DCA-RFT, activemail

Road signs

Bourbaki puts a Z-bend sign in the margin of his/her/their books next to arguments that seem to be unusually fine, difficult, or complex, or are easily misunderstood. Hence we can study the idea of other Road Signs. For example a common road sign in many counties indicates that the road is being work on and extra care may be needed when navigating it. For example - the next part of the text is under development and it needs a road sign indicating that it is not complete.

.Road_Work_Ahead

Other possibilities

Common Road Signs

• Hazards to driver
  • Dangerous Bend
  • Slippery Road
• Choices
  • Cross Roads/Junction
  • Fork
  • Dual Carriage Way/Divided Highway
• Don'ts
  • Give Way/Yield
  • Stop
  • Culdersack/No Thru Road
  • No Entry
  • Wrong Way
• Things in Road
  • Road Works
  • Children
  • Animals
  • Rock Slide Area
  • Sudden Noise

Connections between Ideas

Edward de Bono (debono) has formalized the following operations and proposed icons to represent them:
• No Entry
• Build Upon
• Make Practical
• Use as a Stepping Stone
• Extract a Function
• Incorporate a Function
• Examine the Assumptions
• Focus/Select a Target
• Challenge
• Expand
• Contract
• Show Evidence
His idea is that these would be added to a document by a reviewer to help the development of better ideas and opportunities. pp197-201, de Bono 78, Edward de Bono, Opportunities, Penguin Books (UK) 1978

He has also supported the development (by CoRT = the Cognitive Research Trust) of frameworks that include:

PMI framework

1. . Plus
2. . Minus
3. . Interesting

TEC framework

1. . Target
2. . Expand
3. . Contract

PISCO framework

1. . Purpose
2. . Input
3. . Solutions
4. . Choice
5. . Operations
De Bono also invented a word (po) with a symbolic form(\po) which permits an idea to be introduced and examined in any context - regardless of its relevance, truth, or goodness of fit. It also indicates a request to stop, pause and look around before continuing. This kind of deliberately illogical step is a part of a larger packet of attitudes and steps which he labelled "Lateral Thinking". This in turn is a part of "creativity".
1. debono::= See http://www.debono.ws.

   Bringing ideas together

   Logical/Mathematical/Vertical

   • conjunction, disjunction, conditional, equivalence
   • Quotation/Tautology
   • Analogy, similarity, morphism, mapping
   • Abstraction
   • Refinements: Cases, Sequences, Components,...
   • Dialectic (thesis, antithesis, synthesis)
   • Analyze-synthesize
   • GiGO - Givens, Goals, Operations
   • Assumption of opposite and reduction to absurdity
   • Mathematical Induction, Symmetry, Without loss of generality,

   Lateral/Creative

   • Force fit - constructing an analogy with an inappropriate model
   • Shuttle - translating the idea into a different form or media
   • Quota
   • Reversal
   • Extremes
   • Embed
   • Build on
   • Make practical
   • Exlexics (map both, extract a positive, reconstruct)
   • Generalization

   . . . . . . . . . ( end of section Bringing ideas together) <<Contents | End>>

. . . . . . . . . ( end of section Formatting) <<Contents | End>>

Popular Informal Frameworks

Reviewer_comment

• . Who
• . When
• . Where
• . What

Scientific Paper

• . Title
• . Abstract
• . History
• . Theory
• . Therefore
• . Experiment
• . Observation
• . Threats
• . Conclusion

Problem Report

• . Summary
• . Quote
• . Problem
• . Solutions
• . Choice

Toulmin Arguments and Rationales

• . Claim
• . Data -- for the claim
• . Warrant -- connects the data to the claim
• . Backing -- for the worrant
• . Rebuttal -- evidence against the claim
• . Qualifier -- possibly, probably, certainly, ...

. . . . . . . . . ( end of section Popular Informal Frameworks) <<Contents | End>>

Output

troff...

Here is the typical form of the output from a MATHS pre-processor into the UNIX 'tbl' pre-processor for nroff/troff:
1. Named_documentation::tbl_input=following,
   

    ".ce"

    Name EOLN

    ".TS" EOLN

    "center box ;" EOLN

    "aw(50n) ." EOLN

    #(

       ( short & (declaration | definition | assertion | comment) EOLN

       | long &

         ( "T{" EOLN

            (declaration | definition | assertion | comment)

          & #{line EOLN}

           "T}" EOLN

         )

      )

    ".TE" EOLN.

   
   

2. short::={s:#ASCII.char || len(s)<80},
   
3. (def)|-short = /len o /< (80),
4. long::= #ASCII.char~short,
5. line::= short & #(ASCII.char~EOLN).

. . . . . . . . . ( end of section troff...) <<Contents | End>>

HTML

[ mth2html ]

. . . . . . . . . ( end of section HTML) <<Contents | End>>

TeX

[ comp.lang.TeX.html ]

. . . . . . . . . ( end of section TeX) <<Contents | End>>

XML

[click here if you can fill this hole]

. . . . . . . . . ( end of section XML) <<Contents | End>>

. . . . . . . . . ( end of section Output) <<Contents | End>>

Proofs follow a natural deduction style that start with assumptions ("Let") and continue to a consequence ("Close Let") and then discard the assumptions and deduce a conclusion. Look here [ Block Structure in logic_25_Proofs ] for more on the structure and rules.

The notation also allows you to create a new network of variables and constraints. A "Net" has a number of variables (including none) and a number of properties (including none) that connect variables. You can give them a name and then reuse them. The schema, formal system, or an elementary piece of documentation starts with "Net" and finishes "End of Net". For more, see [ notn_13_Docn_Syntax.html ] for these ways of defining and reusing pieces of logic and algebra in your documents. A quick example: a circle = Net{radius:Positive Real, center:Point}.

For a complete listing of pages in this part of my site by topic see [ home.html ]

Notes on the Underlying Logic of MATHS

For a more rigorous description of the standard notations see