Documenting formal mathematics

• Formal mathematics := computer-verified mathematics
• Much like computer programs, less so like mathematics.
  • But structured like mathematical documents (definition, lemma, …).
• Documentation for various reasons:
  • Explanation,
  • Education (Pierce et al. – Software Foundations),
  • Publication (ITP proceedings).

Problem: documentation is hardly supported

• Documentation is informal: narration structured differently than code.
• Informal narratives: informal descriptions alternated with ‘islands’ of formal code.
• Existing workflows:
  • Literate proving: requires adapted workflow
  • In-source documentation (Coqdoc): no break from formal structure for narrative
  • Hyperlinking: no juxtaposability (code and explanation side by side)
  • Separate documentation (include formal snippets into LaTeX): fiddly

Goal: tool support for authoring documentation

• Mix-in syntax (into a host syntax) for writing references to formal elements.
• Annotation framework for formal proofs: as automated as possible
  • take advantage of proof assistant's internal knowledge
  • allow for user input (e.g. links to Wikipedia)
• Host syntax for now: Wikipedia-style markdown, in our own Wiki system.
• Demo at http://mws.cs.ru.nl/agora/cicm_sandbox

Referring to formal objects: a syntax

• Merge Wiki-like links ([[link]]) with LaTeX-style inclusion.
• Different syntax, to prevent confusion: @{type link} (compare Isar's antiquotation)
  • Typed pointer to object (for disambiguation).
  • Formal object referred to by “link” in the rendered page.
• The syntax is:
  • Simple.
  • Readable (in the source).

Annotations: signposts for inclusion

• Refer to all kinds of things: lemmas, theorems, …, include proofs too.
• Not one specific system, but any proof assistant.
• Options for finding the objects:
  • Ad hoc: include a search mechanism per system.
  • Assume uniform framework that points to items of formal text – by their canonical identifier and item type.

Uniform semantic exchange format: HTML with RDFa

• Information on canonical identifiers (URIs), types and links embedded into HTML
• Type annotation:
  • Need a type vocabulary (ontology) – we use the OMDoc ontology about mathematical objects/relations
  • Provides ‘sign posts’ for finding a particular item (e.g. using XPath)
• Content annotation (pointing to related content):
  • Need suitable target datasets (with canonical identifiers) – e.g. linked open datasets such as DBpedia
• Example:

<div typeof="oo:Theorem" about="#T15">
  <span rel="owl:sameAs" resource="http://dbpedia.org/resource/
    Brouwer_Fixed_Point_Theorem_for_Disks_on_the_Plane"/>
  ... actual HTML content of the theorem ...
</div>

Annotating formal text

• Annotations should be included in the HTML for a formal text.
• Either ‘internally’, by generating the HTML, including annotations, from the source
  • Implemented for Mizar.
• Or ‘externally’, post-processing HTML generated by other tools
  • Implemented for Coq, using the Coqdoc-generated HTML.
  • Can be done on the fly, for a single document.

Summary

• We presented …
  • a syntax for including formal islands into informal texts
  • portable annotations for marking these islands in the formal source
• We implemented …
  • inclusion as part of Agora (http://mws.cs.ru.nl/agora)
  • portable annotations (HTML+RDFa export) for Mizar and Coq; feasible for other systems in a similar way
• Document formal mathematics without premature commitment to one workflow or toolchain
• Future improvements:
  • Reference not just by URI but by query: “a proof that proves Lemma 1 using …”
  • Editing with auto-completion: “@{oo:Theorem Fermat#L …” (possible with a SPARQL query over RDF)
  • Coping with name changes: assign stable internal IDs, plus human-readable names
• @CICM chairs: Use Agora for future papers about formalisations