[Skip Navigation] [CSUSB] / [CNS] / [CSE] / [R J Botting] / [ MATHS ] / notn_5_Form
[Contents] [Source Text] || [Notation] || [Copyright] || [Contact] [Search ]
Fri Feb 22 11:47:57 PST 2013

Contents


    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 [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
          FormatTagEnd-TagPurposeLikely 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

        RFC 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 :o

        Bibliography A document can end with the

         .Bibliography
        directive and have it indexed, placed in the Contents list and specially formatted in the rndered forms.

        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, Tex, uuencode, VDM, Z.

        Currently

         		.As_is
        and
         		.Tex
        are implemented in the mth2html tool that renders MATHS into HTML. "As_is" indicates that the rendered HTML looks like the input line, and "Tex" uses the Google Charts API to render the ΤΕΧ string as a graphic image with alternate text copying the line.

        Notations

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

        Waisindex Formats

        Source: e Krol92 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

        Here is a list of directives that can insert relevant materials in rendered forms of a MATHS document:

        Author, Author_signoff, Author_signature, Author_portrait, Address, EMail, Index, 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), JSON, MIME, Net CDF, PICT (macintosh bit-maps), PostScript, SDTS(Spatial Data Transfer Standard), TIFF(Tagged Image File Format), ...

        MIME Content Types/Subtypes (Circa 1993)

        Source: 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,

        Source: RFC1314 image/ief

        MIME Registered Application Subtypes

        Source: Baker93 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.

            Source: deBono78

            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

        Stephen E. Toulmin has fundamentally rethought the classical Aristotlean form of an argument into 6 distinct headings
        • . 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, ...

        Note the MATHS language formalizes arguments like this:

         		(data and warants)|-(label): claim.
        where the data and warrants are labels of previously introduced claims.

        Rebuttals appear in the proof of the argument

         . Proof of label
         .Let data... warrants
         	steps
         .Close.Let
         .But
         	Rebuttal
         .Close.But

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

      To Be Done -- Other structures and notations for arguments

      1. GSN::=Goal Structuring Notation. [click here [socket symbol] GSN if you can fill this hole]
      2. CAE::="Claims-Argument-Evidence". [click here [socket symbol] CAE if you can fill this hole]

        OMG Unifying these to give:


        1. ARM::="Argumentation Metamodel", [ http://www.omg.org/spec/ARM/ ] [click here [socket symbol] ARM if you can fill this hole]
        2. SAEM::="Software Assurance Evidence Metamodel", [ http://www.omg.org/spec/SAEM/ ] [click here [socket symbol] SAEM if you can fill this hole]
        3. SACM::= "Structured Assurance Case Metamodel". [click here [socket symbol] SAEM if you can fill this hole]

        [ spec ]

      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 [socket symbol] if you can fill this hole]

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

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

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



    References


    (Baker93): Stephen Baker, UNIX review (June 1993)p28
    (deBono98): Edward de Bono 78, Edward de Bono, Opportunities, Penguin Books(UK) 1978, pp197-201
    (Krol92): Ed Krol, The Whole Internet User's Guide and Catalog, O'Reilly & Assoc, Sebastopol CA 1992, (p226, table 12-1)
    (RFC1314): Request For Comment 1314
    (RFC1341): Request For Comment 1341

    Notes on MATHS Notation

    Special characters are defined in [ intro_characters.html ] that also outlines the syntax of expressions and a document.

    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 might be described by Net{radius:Positive Real, center:Point, area:=π*radius^2, ...}.

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

    Notes on the Underlying Logic of MATHS

    The notation used here is a formal language with syntax and a semantics described using traditional formal logic [ logic_0_Intro.html ] plus sets, functions, relations, and other mathematical extensions.

    For a more rigorous description of the standard notations see

  1. STANDARD::= See http://www.csci.csusb.edu/dick/maths/math_11_STANDARD.html

    Glossary

  2. above::reason="I'm too lazy to work out which of the above statements I need here", often the last 3 or 4 statements. The previous and previous but one statments are shown as (-1) and (-2).
  3. given::reason="I've been told that...", used to describe a problem.
  4. given::variable="I'll be given a value or object like this...", used to describe a problem.
  5. goal::theorem="The result I'm trying to prove right now".
  6. goal::variable="The value or object I'm trying to find or construct".
  7. let::reason="For the sake of argument let...", introduces a temporary hypothesis that survives until the end of the surrounding "Let...Close.Let" block or Case.
  8. hyp::reason="I assumed this in my last Let/Case/Po/...".
  9. QED::conclusion="Quite Easily Done" or "Quod Erat Demonstrandum", indicates that you have proved what you wanted to prove.
  10. QEF::conclusion="Quite Easily Faked", -- indicate that you have proved that the object you constructed fitted the goal you were given.
  11. RAA::conclusion="Reducto Ad Absurdum". This allows you to discard the last assumption (let) that you introduced.

( End of document ) <<Contents | Top