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.
sample page (TOC)
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

[edit] History (fr)

version 6.0
  • possibilité de choisir le charactère de commentaire : ouverture à tous les langages sans commentaires de bloc
version 5.51
  • correction d'un oubli sur ocamawebfilename
version 5.5
  • prise en compte dynamique de la modification des mots clefs dans ocamaweb.xml
  • intégration des regexp dans ocamaweb.xml (TODO)
version 5.4
  • modification de ocamaweb.sty pour ne pas être lancé plusieurs fois
version 5.31
  • petit débug
version 5.3
  • autres générateurs de pdf / ps
version 5.2
  • mots clef matlab dans ocamaweb.xml
version 5.1
  • la macro definition est remplacée par ocamawebdefinition (pour JL)
version 5.0
  • recours à ocamaweb.xml
version 4.43
  • correction d'un bug de typo (merci JB)
version 4.42
  • autorisation des apostrophes dans les champs spéciaux (title, etc)
version 4.41
  • correction d'un bug issu de 4.4 : ordre de traitement des fichiers (merci JL)
version 4.4
  • suppression du chemin du fichier traité (pour JFL)
version 4.3
  • correction du bug de starrification du premier niveau de titre
version 4.1-2
  • corrections \TeX\ pour Jérôme L.
version 4.0
  • correction de divers "bugs" (défault de special keys)
version 3.9
  • correction de l'ordre des "latexifications" et "pdfications"
  • gestion plus robuste des variables d'environnement
version 3.8
  • améliorations de mise en page (vers ocamaweb.sty et directement dans le code)
version 3.7
  • inclusion du chemin jusqu'à ocamaweb.sty dans le fichier \LaTeX\
version 3.6
  • version avec un seul argument en ligne de commande : envoi des sorties dans le répertoire OCAMAWEB_DEST
version 3.5
  • version avec compilation LaTeX incluse
version 3.4
  • version compilée
version 3.3
  • édition d'une ligne "utilise" / "est utilisé par" en bas de chaque section
version 3.2
  • mise à jour de ocamaweb.sty
  • disponibilité de l'"étoilage" des sections
version 3.1
  • système de récupération de "clefs globales" (section \ref{sec:keys:glob})
version 3.0
  • externalisation de la feuille de style LaTeX
  • numérotation des blocs
version 2.2
  • mise au format de mldoc recompilé par mes soins (option key ajoutée)
  • problème: je ne récupère pas les % des commentaires de la section de code
  • attention: je dois gérer mes propres backslash en \LaTeX\
version 2.1
  • utilisation d'une variable d'environnement
  • "problème notable" de 1.0 contourné : les fils de 1er niveau sont inversés
version 2.0
  • résolution d'un problème de parsing de la première ligne
version 1.0
  • problème notable : enpilage en sens "inverse" des sections de haut niveau
  • attention à l'évaluation récursive des types
  • choix définitif de la structure d'arbre

[edit] TODO list (fr)

  • si il n'y a pas de titre de section : plantage String.sub
  • au début du fichier, les tout est mis dans le code tant que le premier "%%" n'est pas rencontré (problème des commentaires de code?)
  • il faut vérifier les '{String.sub problems}' dans les logs
  • impossible d'utiliser les '{pipes}' dans un titre
  • commentaires après du code (regexp)
  • incorporer les listes de pères et fils dans l'arbre
  • "morceler" le code :
    • un objet pour le parsing : un objet "abstrait" qui soit indépendant du type de commentaire(par lignes ou par blocs) + une implémentation pour MATLAB
    • un objet pour le pretty printing avec une implémentation pour LaTeX
    • externaliser certains paramétrages dans un .ini : clefs spéciales, remplacements de symbols, etc.
  • améliorer le traitement des chaînes de caractères (pour LaTeX)
  • léger problème : les remplacements sont effectués dans les chaînes de charactères(par exemple les $=$ deviennent des $\leftarrow$)

[edit] 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

[edit] 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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] Needed LaTeX macro (fr)

  • \refcode{#1} qui référencie un bloc (avec une \ref{#1} dedans)
  • \sectitle{#1} qui positionne un titre (avec un \label{#1} dedans)
  • \comments{#1} qui positionne un commentaire (pour ceux isolés sur une ligne)
  • \bs{} un backslash
  • \stringc{str} un string
  • \bcodesymbol le symbol d'avant le code
  • \bsecsymbol le symbol d'avant la section
  • \refangles pour pointer sur les sections utilisées et / où utilisant la version en cours
  • \ocamawebstart appelée en début de fichier
  • \ocamawebend appelée en fin de fichier

[edit] Associated LaTeX style files (fr)

La feuille de style ocamaweb.sty doit être dans le PATH LaTeX. D'autre part, les section doivent être référencées par \{refcode:#}. Elle contient en outre diverses définition correspondant aux opérateurs (=, etc).

[edit] 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.

[edit] 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 '

[edit] OCAMAWEB Sources

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

Download code
hijacker
hijacker
hijacker
hijacker