OCAMAWEB

From LiteratePrograms

Jump to: navigation, search

This program is under development.
Please help to debug it. When debugging
is complete, remove the {{develop}} tag.


A new version of Ocamaweb is under development. Its alpha version will be programmed in Matlab. It will be named Ocamaweb2. At this stage its only (but usefull) feature is to be able to export Matlab programs to literateprograms.org.
Enlarge
sample page (TOC)
Enlarge
sample page
OCAMAWEB is a literate programming tool written in Ocaml. It was at first dedicated to target the Matlab programming language, but has now a lot of different configuration files, allowing it to target a lot of other languages (it can be used with any language using a character to mark begining of comment lines).

It's current binary distribution is available on sourceforge.

Feel free to upgrade this code, any significant upgrade will be integrated in next Ocamaweb version.

I put it here to begin its refactoring. It is based on my first parser in ocaml, which was not very efficient... It needs an old version of Xml light, from Motion-Twin.

Some sections have to be translate in english...

Contents

History

version 6.0
  • The character choice comment: open to all languages without comment block
version 5.51
  • correction of an oversight on ocamawebfilename
version 5.5
  • taking into account the dynamic changes in keywords ocamaweb.xml
  • Integration regexp ocamaweb.xml (TODO)
version 5.4
  • ocamaweb.sty modified to not be run multiple times
version 5.31
  • small debugging
version 5.3
  • other generators pdf / ps
version 5.2
  • keywords matlab in ocamaweb.xml
version 5.1
  • the macro definition is replaced by ocamawebdefinition (for JL)
version 5.0
  • use ocamaweb.xml
version 4.43
  • bug fix typo (thank you JB)
version 4.42
  • authorization apostrophes in special fields (title, etc.)
version 4.41
  • fixed a bug resulting from 4.4: order of processing files (thank you JL)
version 4.4
  • deletion of the file path Treaty (to JFL)
version 4.3
  • correction of bug starrification the first level title
version 4.1-2
  • corrections \\ TeX \\ to Jerome L.
version 4.0
  • Fixed various bugs (default of special keys)
version 3.9
  • Correction about the \"latexifications\" and \"pdfications\"
  • More robust environment variables
version 3.8
  • Layout improvements (to ocamaweb.sty and directly in the code)
version 3.7
  • inclusion of the road to ocamaweb.sty in the \\ LaTeX \\
version 3.6
  • version with a single command line argument: sending output to the directory OCAMAWEB_DEST
version 3.5
  • version included with LaTeX compilation
version 3.4
  • compiled version
version 3.3
  • Online edition of a \"use\" / \"is used by\" the bottom of each section
version 3.2
  • Update ocamaweb.sty
  • Availability of \"starring\" sections
version 3.1
  • Recovery System \"key global\" (Section \\ ref {sec: keys: glob})
version 3.0
  • Outsourcing LaTeX style
  • numbering blocks
version 2.2
  • formatter of mldoc recompiled by me (option key added)
  • Problem: I do not retrieve% of the comments section of code
  • Attention: I manage my own backslash in \\ LaTeX \\
version 2.1
  • Using an environment variable
  • \"Significant problem\" of 1.0 circumvented: the son of the first level are reversed
version 2.0
  • solving a problem parsing the first line
version 1.0
  • Significant problem: in enpilage meaning \"opposite\" sections of high
  • Attention to the evaluation of recursive types"
  • final choice of tree structure

TODO list

  • If there is no section title: Crash String.sub
  • At the beginning of the file, everything is put in the code as the first \"%%\" is not met (problem code comments?)
  • must be checked {} String.sub Problems' in the logs
  • Can not Use '{pipes}' in a title
  • Comments after the code (regexp)
  • Incorporate the lists of fathers and son in the tree
  • \"Break up\" code:
    • n object for parsing: an object \"abstract\" that is independent of the type of comment (by rows or by blocks) + an implementation for MATLAB
    • an object for pretty printing with an implementation for LaTeX
    • outsource some settings in a'.ini': special keys, replacement symbols, etc..
  • improve the handling of strings (for LaTeX)
  • slight problem: the replacements are performed in strings of characters (for example, become $ = $ $ \\ leftarrow $)

OCAMAWEB Compilation

To compile OCAMAWEB: 

 set OCAMLLIB=%OCAML_HOME%/lib
 set PATH=%OCAML_HOME%/bin;%PATH%
 %OCAML_HOME%/bin/ocamlc Str.cma -o ocamaweb.exe ocamaweb.ml

then to use OCAMAWEB: 

 ocamaweb sinuso.m first.tex

A short User Guide

 This section contains a small guide to OCAMAWEB, a software in ocaml allowing

literate programming for MATLAB or any programming language with one sign at begining of the line for comment (VB, SAS, awk, etc). This software can be easily generalized to other programming languages. Its goal is to become a generic literate programming tool, called OCAXXWEB.

Literate programming

The first version of this documentation was produced my a modified version of mldoc which is a literate programming tool for ocaml. It's now migrating to noweb on LP.org.

The principle of literate programming is to allow inclusion of comments into software sources so that the given sources can be compiled to produce a clear documentation for the software.

The produced documentation is a technical one (explaining the code and the algorithms used) but can include some informations to deliver to the final user of the software.

The key concept in literate programming is the use of "sections" of code.

Section of code. A section of code is a given part of a software code with a title, and an explanation of the features of the code. Sections can be imbricated.

The power of the literate programming tools is that the order the section into the documentation produced has not to be their order into the code.

Example. In MATLAB the comments are marked with the character % : 

<<a_lot_of_PCAs.m>>=
function [M, v, l] = a_lot_of_PCAs(n, p, nb)
%< checking the argument number
% there can be 2 or 3 arguments
if nargin < 3
  nb = 1
end;
%>
figure; hold on;
%< performing ACPs
% the number of PCAs to be preformed is nb
for i=1:nb
  %< randomized input
  % I will perform a PCA on a gaussian n X p matrix
  M     = randn(n,p);
  %>
  %< PCA
  % I use eig but I could used SVD too
  [v,l] = eig(M' * M);
  l     = diag(l);
  csl   = cumsum(l);
  %>
  plot(csl/csl(end));
end;
%>

Here we have 4 sections : 

<<SECTION 1>>=
%< PCA
% I use eig but I could used SVD too
[v,l] = eig(M' * M);
l     = diag(l);
csl   = cumsum(l);
%>

<<SECTION 2>>=
%< randomized input
% I will perform a PCA on a gaussian n X p matrix
M     = randn(n,p);
%>

<<SECTION 3>>=
%< performing ACPs
% the number of PCAs to be preformed is nb
for i=1:nb
    SECTION 2
    SECTION 1
    plot(csl/csl(end));
end;
%>

<<SECTION 4>>=
%< checking the argument number
% there can be 2 or 3 arguments
if nargin < 3
   nb = 1
end;
%>

And finally the function can be written: 

<<a_lot_of_PCAs_.m>>=
function [M, v, l] = a_lot_of_PCAs(n, p, nb)
SECTION 4
figure; hold on;
SECTION 3

As one can see, if you replace the section by their titles, the code is very simple...

A literate programming software allows to reorganize your code in such a more "readable" way.

OCAMAWEB syntax

The OCAMAWEB syntax is inspired of the CWEB one. The comment character for MATLAB is "%", so all the lines adressed to OCAMAWEB will begin by a "%".

Section definition. The sections will began with "%%" or "%<". The sections begining with "%%" will be called "global sections" and the section begining with "%<" will be called "arbitrary sections". The strings "%%" and "%<" are called "section marks".

Global sections. Global sections begin with "%%" and end with the next "%%" or the end of the file.

Arbitrary sections. Arbitrary sections begin with "%<" and end with "%>". Arbitrary sections can be nested.

Section title. The title of a section is the text between the section mark and the first "." (dot) or the end of the line :

code title comment
%% alpha beta. gamma alpha beta gamma
%% alpha beta alpha beta
%< alpha beta. gamma alpha beta gamma
%< alpha beta alpha beta

Section captions. The section captions will be printed in LaTeX; the section comment is :

  • the text after the first " ." (dot) on the line of section mark,
  • each comment line after the line of the section mark,
  • each comment line after a caption line.


For instance :

code caption
%% alpha beta. gamma & gamma
% blah blah & blah blah
<empty line : end of this section caption>
% blah blah <nothing : this is regular comments>

or:

code caption
%< alpha beta. gamma gamma
% blah blah blah blah
for i=1:n <end of this section caption>
% blah blah <nothing : this is regular comments>

Section code. All the source code between the end of the section caption and the end of the section are in the "code" part of the section. If an section is defined into a code part then only a reference to this section will be written and the complete section will be put after the current one.

Levelized sections. Any section can be "levelized" : that means that the section mark will contain a special character like "*N" (where N is a number) or "**".

Section with "*}" will have an higher level than classical ones, and section with "*N" will have a "N" times higher level than "**" ones.

The more a section has an high level, the more it is important.

OCAMAWEB LaTeX macro

Some LaTeX macro are defined into the ocamaweb.sty file that is included for compilation of outputs of OCAMAWEB. They can be used in the comment part of the source files.

As with CWEB, you can use the macro 'pipe' | to "quote" some code into your comments, but actually the "piping" is not allowed into the section titles.

Warning: do not use tabbing into your code but only spaces if you want to have a pretty print.

Needed LaTeX macro

  • \\ {# 1} refcode that references a block (with \\ ref {# 1} in)
  • \\ # 1} {sectitle that positions a title (with a \\ label {# 1} in)
  • \\} {# 1 comments that positions a comment (for those isolated on one line)
  • \\ Bs {} a backslash
  • \\ Str} {stringc a string
  • \\ Bcodesymbol the symbol before code
  • \\ Bsecsymbol the symbol before the section
  • \\ Refangles to point to the sections used and / or using the current version
  • \\ Ocamawebstart called at the beginning of file
  • \\ Ocamawebend called at end of file

Associated LaTeX style files

The stylesheetocamaweb.sty must be in PATHLaTeX. On the other hand, the section should be referenced by \\ refcode {#}. It also contains various definitions for operators (=, etc.).

Install and use

To install OCAMAWEB, just put the ocamaweb.exe, ocamlrun.exe and dllstr.dll in your PATH, and define two variables :

  • OCAMAWEB to specify where the ocamaweb.log file (the log file) has to been put and where the ocamaweb.sty file is,
  • OCAMAWEB_DEST to specify where the transformed files have to been put by default.

Those two variables contain directory names and must end by the file separator \ for Windows and / for Unixes.

The use of OCAMAWEB is : 

ocamaweb matlab_file.m [destination_file.tex]

if the destination file is ommitted, it is named after the input file (matlab_file.tex) and put into the OCAMAWEB_DEST directory and in this case the .tex file is produced and processed with LaTeX and dvipdfm (see the customization section).

When the second argument is specified, the .tex file is produced and nothing else is done.

Customization of OCAMAWEB

The versions 5.0 and after of OCAMAWEB allow its parametrization of the software using an xml file : <<ocamaweb.xml>>. It allow to change the tags used by OCAMAWEB to recognize keywors as version, author's name and email, etc.

Another section of the xml file if dedicated to the declaration of MATLAB keywords (that are sent to the ocamawebdefinition LaTeX macro). 

<<ocamaweb.xml>>=
   <ocamaweb>
   <pdfgenerator file="dvipdfm" ext=".dvi"/>
   <keypatterns>
      <keypattern name="author" key="node.author" before="'" after="'"/>
      <keypattern name="author" key="% author" before="'" after="'"/>
      <keypattern name="author" key="% auteur" before="'" after="'"/>
      <keypattern name="title" key="% title" before="'" after="'"/>
      <keypattern name="title" key="% titre" before="'" after="'"/>
      <keypattern name="project" key="% project" before="'" after="'"/>
      <keypattern name="project" key="% projet" before="'" after="'"/>
      <keypattern name="mailto" key="node.mailto" before="'" after="'"/>
      <keypattern name="mailto" key="% mailto" before="'" after="'"/>
      <keypattern name="date" key="node.date" before="'" after="'"/>
      <keypattern name="date" key="% date" before="'" after="'"/>
      <keypattern name="version" key="% version" before="'" after="'"/>
      <keypattern name="version" key="VERSION" before="=" after=";"/>
   </keypatterns>
   <matlabwords>
      <keyword name="function"/>
      <keyword name="while"/>
      <keyword name="continue"/>
      <keyword name="try"/>
      <keyword name="catch"/>
      <keyword name="for"/>
      <keyword name="end"/>
      <keyword name="persistent"/>
      <keyword name="switch"/>
      <keyword name="case"/>
      <keyword name="if"/>
      <keyword name="else"/>
      <keyword name="elseif"/>
      <keyword name="return"/>
      <keyword name="break"/>
      <keyword name="otherwise"/>
   </matlabwords>
   <info/>
   </ocamaweb>

That means for instance that the author's name it recongnized as :

  • anything on the same line as 'node.author', between ' and '
  • or anything on the same line as '% author', between ' and '
  • or anything on the same line as '% auteur' (french version), between ' and '

OCAMAWEB Sources

The last stable full distribution of OCAMAWEB can be downloaded at SourceForge (with some binaries releases too).

Download code
Retrieved from "http://literateprograms.org/OCAMAWEB"
Views