The Dawn project

For more comprehensible documents

Introduction

• I would like to begin with this aphorism:

  Scientia potentia est.
  (Knowledge is power.)

• We developed our world by this power.

• In order to develop further, we have to gain more power.

• Can we acquire more knowledge more efficiently?

Comprehensibility, the virtue

• One of main methods for acquiring knowledge is reading documents.
• Documents have some sort of quality: comprehensibility.
• With comprehensible documents, we can acquire more knowledge.
• Unfortunately, not all documents are comprehensible.
  And it seems the authors, not readers, are to blame.
• How can we compose comprehensible documents?

What's a comprehensible doc?

• According to my experience, a comprehensible document is a well structured system,
• that is, a comprehensible document
  1. shows connections between each partial statement clearly
  2. is composed of easily understandable statements
• Of cource, these may not be necessary and sufficient conditions for the comprehensibility. Nevertheless, I believe these conditions cover great extent of comprehensibility.

Depicting the structure of a doc

• A typical case, that premise 1 and premise 2 concludes conclusion, can be depicted as such.
• The white ovals represent notions, and the black dot represents an explanation.
• Of cource, the conclusion can be a premise of another explanation and the structure gets larger.

Graphical structure of a doc

• This picture is nothing but a graph in the graph theory.
• I call this graph a dawn graph.
• A dawn graph is,
  • a directed graph
  • composed of two kinds of nodes, ovals and dots (ovals represent statements, notions, knowledge etc.) (dots represent explanations, inferences, association etc.)
• i.e. a dawn graph is a directed bipartite graph.

Comprehensibility & dawn graph

• The comprehensibility conditions mentioned before can be summarized as:

  A comprehensible document shows a clear dawn graphical structure of which nodes are all easily understandable.

• The Dawn project attempts to compose comprehensible documents based on the dawn graph.

Making use of computers

• We live in the era of computers. There are no good points to refuse using computers in this project.
• The Dawn project provides computer tools to compose documents based on the dawn graph.
• Besides, by the formal simplicity of dawn graphs, one may formally analyze dawn graphs with computers. For example:
  • By following precedessors, one can find axiomatic statements.
  • By calculating a centrality of a dawn graph node, one can quantify the importrance of the statement associated to the dawn graph node formally.
  • By cluster analysis of the dawn graph, one can formally classify sub-theories.

Dawn package

• To enable ones to compose documents on the dawn graph, the Dawn project offers a Python package, Dawn.
• The Dawn package tries to make full use of existent software.
  (i.e. standing on the shoulders of giants)
• The Dawn package enables ones to
  • write documents based on the dawn graph
  • generate dawn graph data in formats specified by the existent software (e.g. generate gv files to make Graphviz draw static image files of the dawn graph)

Document format

• The dawn graphs is an embodiment of THE structure of a document, which is usually not explicitly shown.
• To embody THE structure, put markups into documents.
  (markup is something like editorial comments for document structures)
• It is preferable to make use of existent markup languages.
• For this project, I want to use extended reStructuredText format, for it is easily extensible and based on Python language.
• However, LaTeX (or TeX) is the most familiar format for most of people writing somewhat so deliberate documents that the concept of the dawn graph exerts its power.
• Thus the Dawn package offers LaTeX package, eos, to enable ones to embed dawn graphical structure in their LaTeX documents.

What's reStructuredText?

• reStructuredText (often abbreviated as rst) is mainly used for documentating python programs but is capable of writing normal documents.
• reStructuredText is categorized as lightweight markup language. It is something like a wiki markup language.
• Texts written in reStructuredText format can be transformed to html or LaTeX.
• Actually, this presentation is written in reStructuredText.

Markup for the dot in rst

• The markup for the dot is the dot directive:

  .. dot:: [name (optional)]
     :dpreds: prem1 prem2
     :dsuccs: conc1 conc2
  
  Content of the dot.
  

• dpreds stands for "direct predecessors" and dsuccs stands for "direct successors".

• This directive is a start marker for the dot. An end marker is an oval directive or a section header.

Markup for the oval in rst

• The markup for the oval is the oval directive:

  .. oval:: name
     :headline: headline
  
     Content of the oval.
  
  Note that indentation is significant and
  this sentence is not part of the oval.
  

• Inline form is also present as the oval role:

  :oval:`(name) content of the oval`.
  

Markup for the dot in LaTeX

• The markup for the dot in LaTeX is the dawndot environment:

  \begin{dawndot}{dot-name}
  {dpred1 dpred2}{dsucc1 dsucc2}
  Content of the dot.
  \end{dawndot}
  

• {dot-name} argument can be blank to give the dot name automatically.

Markup for the oval in LaTeX

• The markup for the oval in LaTeX is the dawnoval environment:

  \begin{dawnoval}{oval-name}
  \headline{headline of the oval}
  Content of the oval.
  \end{dawnoval}
  

• Inline form is also present as an inlineoval command:

  \inlineoval{oval-name}{Content of the oval.}
  

Extracting dawn graphical data

• The Dawn package offers a program named dawn, which extracts dawn graphical data from a document and save the data to a file in a specified format.
• For example
  $ dawn -f dot document.tex -o dawngraph.gv
  extracts dawn graphical data from document.tex and save the data to dawngraph.gv in Graphviz DOT format.
• Afterwards, running
  $ dot -Tgif dawngraph.gv -o dawngraph.gif
  generates an image file visualizing the dawn graphical structure of the document.

Suggested Practice

• Note that dawn graphical structure is just additional to the traditional documents.
• Suggested practice is:
  1. Write a small part of a document (maybe some paragraphs to some sections) without any consideration for dawn graphical structures.
  2. Afterwards, embed dawn graphical structures by putting directives or environments etc..
  3. Analyze with outliner or graph visualizer.
  4. Write another small part as well.
  5. Finally, publish the organized whole content.
• Of cource, this is just one suggested procedure. You have a freedom not to obey the procedure.

The Dawn project

Thank you for listening!

Feel like writing documents with this?