Literate Programming

Literate programming is the art of preparing programs for human readers.

Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. -Donald Knuth

• http://www-cs-faculty.stanford.edu/~knuth/lp.html
• http://www.literateprogramming.com

History

• Donald Knuth authored WEB for Pascal/TeX
• Silvio Levy developed CWEB for C/TeX
• CTANGLE converts CWEB to C
• CWEAVE converts CWEB to TeX
• Many derivatives are available

Software Costs

• There are two familiar variants of the documentation problem
• You write all the internal documentation that you know you need and you pay a terrible price for it
• You don't write all the internal documentation you need and you pay a terrible price for that.

Common Documentation Problems

• Poor organization
• Boring to write, boring to read
• Confusing and inconsistent terminology
• End of project myopia
• Keeping docs synchronized with source code

Conventional Programing and Documentation Flow

Literate Programming Flow

Related Tools

• Doxygen
• RoboDoc
• Leo

Literate Editor with Outlines (LEO)

• authored by Edward K. Ream
• file editor
• hierarchical outlining editor
• literate programming editor
• uses XML as a file format
• written in Python, fully scriptable with Python
• uses Tk graphical toolkit
• its open (Python License)
• its cross-platform
• easy to install
• easy to use
• leverages the power of plain text
• allows for cloned nodes
• plays well with others
• good example of Python/Tk programming

LEO Screenshot

Leo Help

• LeoDocs.leo - built in self documentation
• LeoPlugins.leo - optional plugins
• excellent online tutorial
• all available from Help menu within Leo

What Leo Does - Literate Programming

Example - ToDo List

ToDo List LEO example XML data file

<?xml version="1.0" encoding="UTF-8"?>
  <leo_file>
    <leo_header file_format="2" tnodes="0" max_tnode_index="0" clone_windows="0"/>
    <globals body_outline_ratio="0.5">
      <global_window_position top="20" left="20" height="600" width="800"/>
      <global_log_window_position top="0" left="0" height="0" width="0"/>
    </globals>
    <preferences/>
    <find_panel_settings/>
    <vnodes>
      <v t="gwhiteman.20050406104511"><vh>personal</vh></v>
      <v t="gwhiteman.20050406104511.1" a="E"><vh>work</vh>
      <v t="gwhiteman.20050406104511.2" a="E"><vh>projects</vh>
      <v t="gwhiteman.20050406104511.3"><vh>project_a</vh></v>
      <v t="gwhiteman.20050406104511.4"><vh>project_b</vh></v>



      </v>
      <v t="gwhiteman.20050406104511.5"><vh>assigned tasks</vh></v>
      <v t="gwhiteman.20050406104511.6" a="ETV"><vh>meeting notes</vh></v>
      </v>
    </vnodes>
    <tnodes>
      <t tx="gwhiteman.20050406104511"></t>
      <t tx="gwhiteman.20050406104511.1"></t>
      <t tx="gwhiteman.20050406104511.2"></t>
      <t tx="gwhiteman.20050406104511.3"></t>
      <t tx="gwhiteman.20050406104511.4"></t>
      <t tx="gwhiteman.20050406104511.5"></t>
      <t tx="gwhiteman.20050406104511.6">@nocolor
 
      I fell asleep...ZZZZZZZZZZZZZZZZZZ</t>
    </tnodes>
  </leo_file>
...

Installing Leo

• Download and install Python (if necessary)
• http://www.python.org
• http://www.activestate.com
• Download Leo
• http://sourceforge.net/projects/leo/
• unzip leo4.2final
• su
• ./install

Leo Limitations

• not good for really, really big files
• does not handle graphics
• care must be taken with revision control systems
• very different way of doing development

Leo Directives

@doc, or @
@code, or @c
@nocolor, @nocolor
@language 
@silent
@ignore

Derived files using @root

• Tangled and Untangled manually
• sections must be referenced using <<section_name>>

Derived files using @file

• Tangled and Untangled automatically
• links derived file to file system
• may use @others reference
• file contents reside in XML data file (.leo)
• sentinels allow file to be edited externally
• sentinels disabled by @filenosent
• files may be imported directly from file system

Importing with @file

choose File -> Import -> Import to @file

• Leo understands the syntax of several languages (Python, Java, etc.)
• Leo understands the structure of several languages
• The imported file is initially marked with @ignore
• protects the file from being overwritten by Leo
• remove @ignore to have Leo (re)generate file

Cloned Headlines

• Clones - same data appears in multiple locations
• Clones are good for managing tasks
• Special clone indicator

Exporting

• outline to CWEB/noweb
• flattened outline
• headlines