Literate/Wiki Tool

Literate Programming declarations and cross links, exporter action for MoinMoin. See OlegKobchenko, download at ParserMarket at MoinMoin.

{{{1}}}

This is an example of Literate programming style, where the code fragments are explained to the humans in the order as it fits to the explanation. The hypertext linking allows to track the relationships between fragments and then also to assemble the code units fit to be executed by a computer.

J Language Wiki features Literate programming style as a combination of an Wiki action and a parser.

Usage

Code fragments are marked with literate format, specifying anchor name and optional caption, which produces the fragment declaration «anchor»=.

#!``literate ` '''`name='anchor'`''' ` caption='Optional caption' for='optional.ijs'` <<BR>>
 `  code here ...` <<BR>>
 '''`  «target»`''' <<BR>>
 `  ...` <<BR>>
 `
}}}` <<BR>>

The following parameters are used:

name:: fragment name, an anchor or a file name caption:: short visible comment about the fragment, optional for:: only include the fragment in that script file, optional

The body of a fragment can contain links to other fragments marked with target anchor name in angle double quotes «target», or guillemet (pronounced [ˈgij:me]). When the sources are tangled into code the target fragments are inserted in place of the link recursively. Clicking on the link will navigate to the target fragment.

The fragment name in the header is a clickable link. Regular fragment name navigates to a link in a referring fragment. If the fragment name looks like file (contains a dot .) then the fragment is treated as the top level of a separate file. Clicking on the name downloads this individual file.

Fragments with the same name are merged in the order as they appear in the document.

The menu of Wiki Actions contains action Literate, which creates and offers to download a zip file with all the files in the document with literate.txt summary file. The zip is cached as attachment and updated if page changes.

For convenience this action can be made into a link on the page with the syntax <<Action(Literate)>>.

Literate Example

[http:?action=Literate&target=. Merged]

This is an example of a code fragment which uses another fragment. The other fragment is linked and included in the generated code unit. (Make the browser window smaller to see how links, backlinks and Back button work.)

Main Program

[{{#file: "test"}} Download script: test ]

  test opening
        «other»
  1.....^
        «other»
  2.....^

More test [{{#file: "test"}} Download script: test ]

        test part 2
        }}
  test closing

This is an included code fragment. [{{#file: "other"}} Download script: other ]

    other operations
    over
    and out

This is an example of script, as suggested by the name of the fragment looking as a file name. [{{#file: "main.ijs"}} Download script: main.ijs ]

  main begins 7
      «test»
  ....^
  main ends

Aux Module

This is another code module [{{#file: "test.ijs"}} Download script: test.ijs ]

sub begins
  «no caption»
..^
  almost done ...

which is continued here [{{#file: "test.ijs"}} Download script: test.ijs ]

  bye
sub ends

This is a dummy block. [{{#file: ""}} Download script: ]

    other operations
    over
    and out

This is a block without caption. [{{#file: "no caption"}} Download script: no caption ]

  no caption operations
  «test»
  ^
  no caption out
  «more code»

/OtherPage

Running Literate Scripts

Literate pages are especially convenient to readily download and execute the script presented with it. Often, the test snippets of the code module are given at the bottom of the script in the Note block. [{{#file: "runnable.ijs"}} Download script: runnable.ijs ]

   a=: 2
   b=: 3
   add=: +

Note 'Test'
   a add b
)

Here's how to run it:

• click on <<runnable.ijs>>= link, open the file and copy contents
• open new IJS script window, paste contents
• in IJS window, run window (Ctrl+W)
• at bottom of script, select the whole Note inner contents
• execute lines (Ctrl+E)

See Also

• Programs to Read, lots of CWEB programs by Donald E. Knuth himself
• How to write an article, LiteratePrograms
• http://en.wikipedia.org/wiki/Literate_programming
• http://www.literateprogramming.com/
• http://www.google.com/search?q=literate+programming