Literate Programming declarations and cross links, exporter action for MoinMoin. See OlegKobchenko, download at ParserMarket at MoinMoin.
![/!\](/jwiki/moin_static194/modernized/img/alert.png "/!\")
Note: Literate Wiki Tool assumes familiarity with Literate process (see references here and on Literate page). This documentation focuses on specifics of the Wiki variety.
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'
code here ...
«target»
...
}}}
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
Download: As Archive, main.ijs, 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
More test
test part 2
}}
test closing
This is an included code fragment.
other operations
over
and out
This is an example of script, as suggested by the name of the fragment looking as a file name.
main begins 7
«test»
....^
main ends
Aux Module
This is another code module
sub begins «no caption» ..^ almost done ...
which is continued here
bye sub ends
This is a dummy block.
other operations
over
and out
This is a block without caption.
no caption operations «test» ^ no caption out «more code»
This an additional page to be included in the main page.
this is
«more code»
....^
other page
Another fragment.
more code here ...
Files in different format.
MS-DOS bat file
more code here ...
C file
more code here ...
Unknown file
more code here ...
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.
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