35.15 Literate Programming

The BEE does not provide real Literate Programming. The reason is that we think that when editing documentation we want to benefit the full power of context-sensitive editors and we don’t want to edit the documentation is the same editor mode as the one we use when editing source code. Nevertheless it is possible to place anchors within the source file to the corresponding documentation file. Then, by the means of simple mouse clicks, it becomes possible to edit the documentation of peace of codes. The current BEE literate programming system only supports the Texinfo file format.

For that purpose three anchors are available: path, node and deffn. All anchor have to be delimited with @ characters.

• path: this anchor set the path to the file containing the documentation. Thus,

  (module foo
     ;; @path manuals/foo.texi@
     ...)
  

  Tells the BEE that the documentation for the module foo is located in the file named manuals/foo.texi.

• node: sets the name of the node that documents this particular source file code.

  (module foo
     ;; @path manuals/foo.texi@
     ;; @node Foo@
     ...)
  

• deffn: each variable binding may point to its documentation. For that, it suffices to use the deffn anchor just before the variable definition or within the s-expression that defines the variable.

  ;; @deffn foo@
  (define (foo . chars)
     ...)
  

  or

  (define (foo . chars)
     ;; @deffn foo@
     ...)
  

  When clicking on that anchor, the BEE will search the documentation file named by the path anchor and within that file, will search for a texinfo deffn command that defines the variable named in the anchor.

This document was generated on March 31, 2014 using texi2html 5.0.