<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<page name="report">
<title>Report</title>
<side>
<page-toc><en>On this page:</en><fr>Sur cette page:</fr></page-toc>
<p class="center"><a href="report.png"><img src="report_small.png" alt="Report, the XML template designer" title="Report, the XML template designer"/></a></p>
</side>

<section name="report:whatis">
<title><en>What is Report ?</en><fr>Qu'est-ce que Report ?</fr></title>
<p>
<en>The Report tool aims to make generation of XML documents from OCaml
applications easier. The main idea is to separate the structure of the
document from the information computed by the application and placed
in the document. For example, in the following document:
</en>
<fr>L'outil Report vise  rendre la gnration de documents XML en OCaml
plus facile. L'ide principale est de sparer la structure du document
des informations calcules par l'application et places dans le document.
Par exemple, dans le document suivant:
</fr>
</p>
<sample>
<![CDATA[<h1>Crpes</h1>
<list>
  <item>flour</item>
  <item>eggs</item>
  <item>sugar</item>
</list>]]>
</sample>
<en>the document structure is</en>
<fr>la structure du document est</fr>
<sample>
<![CDATA[<h1> </h1>
<list>
  <item> </item>
  <item> </item>
  <item> </item>
</list>]]>
</sample>
<en>while computed information is </en>
<fr>tandis que l'information calcules est </fr>
"Crpes", "flour", "eggs" and "sugar".
<p>
<en>To build our XML document, we must therefore describe its structure
as well as the way to fill it with information. Then, at runtime, the
application will use this description to generate the final XML document.
</en>
<fr>Pour construire notre document XML, nous devons donc dcrire sa structure
et la faon de la remplir d'information. Ensuite,  l'excution,
l'application utilisera la description pour gnrer le document XML final.
</fr>
</p>
<p>
<en>In practice, Report allows to graphically describe the document
(structure + information), and then to generate OCaml code which uses the
Report library. In particular, this library contains a function which computes
a document description to produce the final XML document. An important point
is that the way to compute the information needed in the document is given
in the form of OCaml code.
</en>
<fr>En pratique, Report permet d'diter graphiquement le document
(structure + information), et de gnrer le code OCaml qui utilise la
bibliothque Report. En particulier, cette bibliothque contient une
fonction qui "value" une description de document pour produire le document
XML final. Un point important est que l'information  mettre dans le
document est donne sous forme de code OCaml.
</fr>
</p>
</section>

<section name="report:library">
<title><en>The library</en><fr>La bibliothque</fr></title>

<section name="report:library:types">
<title><en>Types</en><fr>Types</fr></title>
<p>
<en>The </en><fr>Le module </fr><tt>Report</tt>
<en> module defines the types used to describe a document
</en>
<fr> dfinit les types utiliss pour dcrire un document
</fr>:
</p>
<sample>
<![CDATA[(** A report element. *)
type 'a report_ele =
  | Leaf of (unit -> string)
  | Tag of 'a tag
  | List of 'a liste
  | Cond of 'a cond
  | Sub of 'a sub

(** A tag. *)
and 'a tag = {
    mutable tag : string ;
    mutable atts : (string * (unit -> string)) list ;
    mutable tag_subs : 'a report_ele list
  }

(** A list of substructures. *)
and 'a liste =
    { mutable list_subs : ('a -> 'a report_ele list) ;
      mutable f : (unit -> 'a list) ;
    }

(** Conditional *)
and 'a cond =
    { mutable cond : unit -> bool ;
      mutable subs_then : 'a report_ele list ;
      mutable subs_else : 'a report_ele list ;
    }

(** Subreport *)
and 'a sub =
    {
      mutable sub_rep : unit -> 'a report ;
    }

(** A report description is a list of report elements. *)
and 'a report = {
    mutable rep_eles : 'a report_ele list ;
  } ]]>
</sample>
<en>The type </en><fr>Le type </fr><code>report_ele</code>
<en> is the type of the tree nodes</en>
<fr> reprsente les noeud de l'arbre</fr>:
<ul>
<li><code>Leaf</code>
<en> is used for the leafs of the tree and needs the code of a function taking </en>
<fr> est utilis pour les feuilles de l'arbre et requiert le code OCaml
d'un fonction prenant en paramtre </fr>
<code>()</code>
<en> and returning a string. While computing the document description, </en>
<fr> et retournant une chaine. Pendant l'valuation de la description du document, </fr>
<code>()</code>
<en> will be applied to this function in order to obtain the string to insert
into the final XML document. This way of hiding OCaml code "under"
</en>
<fr> sera pass  cette fonction afin d'obtenir la chaine  insrer dans le
document XML final. Cette faon de cacher le code OCaml "sous" </fr>
<code>fun () -&gt; </code>
<en> allows not to compute the result until the computation of the leaf,
thus allowing to use values computed "above" the leaf.
</en>
<fr> permet de ne pas calculer le rsultat avant l'valuation de la feuille,
ce qui permet d'utiliser des valeurs calcules "au-dessus" de la feuille.
</fr>
</li>

<li><code>Tag</code>
<en> is used to define an XML node of the final XML document. It needs the
tag name, eventually a list of attributes and values, as well as subtrees of the
node. Values of attributes are OCaml code too, as for the leafs.
</en>
<fr> est utilis pour dfinir un noeud XML du document final. Il faut indiquer
un nom de tag, ventuellement une list d'attributs et de valeurs, ainsi que
les sous-arbres du noeud. Les valeurs des attributs sont, comme pour les feuilles,
du code OCaml.
</fr>
</li>

<li><code>List</code>
<en> allows to insert, while computing the final document, a list of subtrees for
each element in a list. The field </en>
<fr> permet d'insrer, pendant l'valuation du document, une list de sous-arbres
pour chaque lment de la liste. Le champs </fr>
<code>f</code>
<en> contains the OCaml function returning the list of elements to iterate on.
The field </en>
<fr> contient la fonction OCaml retournant la liste des lments sur lesquels itrer.
Le champs </fr>
<code>current</code>
<en> is used to store the current element while walking through
the subtrees. This way, the value of the field </en>
<fr> est utilis pour stocker l'lment courant pendant la descente dans les sous-arbres.
De cette faon, la valeur du champs </fr>
<code>current</code>
<en> can be used in the functions which appear in the subtrees of the node.</en>
<fr> peut-tre utilise dans les fonctions qui apparaissent dans les sous-arbres du noeud.</fr>
</li>

<li><code>Cond</code>
<en> allows to use one list of subtrees or another, depending on the boolean value
returned by the given function.
</en>
<fr> permet d'utiliser une liste de sous-arbres ou une autre, selon la valeur boolenne
renvoye par la fonction donne.
</fr>
</li>

<li><code>Sub</code>
<en> is used to insert another document in the current one. The given
function returns a document description which is computed too.
</en>
<fr>
</fr> est utilis pour insrer un autre document dans le document courant. La fonction
donne retourne une description de document qui est value  son tour.
</li>
</ul>
<p>
<en>The document example of the introduction could be described as in following section.
</en>
<fr>Le document en exemple de l'introduction peut-tre dcrit comme dans la section suivante.
</fr>
</p>
</section>

<section name="report:code-example">
<title><en>Code example</en><fr>Exemple de code</fr></title>
<sample><![CDATA[let rec report  =
  ({
   rep_eles = [
     Tag { tag = "h1" ; atts = [] ;
           tag_subs = [
             Leaf (fun () -> "Crepes");
           ] } ;
     Tag { tag = "list" ; atts = [] ;
           tag_subs = [
             ( let rec ing =
                 { f = (fun () -> ing_of_recipe "Crpes") ;
                   current = (Report.coerce 0) ;
                   list_subs = [
                     Tag { tag = "item" ; atts = [] ;
                           tag_subs = [ Leaf (fun () -> ing.current.ing_name) ] }
                   ] }
                in
                List (Report.coerce ing))
           ]
          }
    ]
   } : int report)
]]>
</sample>
<p>
<en>The call to </en>
<fr>L'appel  </fr>
<code>Report.coerce</code>
<en> is necessary to force the type but type constraints are already satisfied
 (notably the use of the </en>
<fr> est ncessaire pour forcer le type mais les contraintes de type sont dj
satisfaites (notamment l'utilisation du champs </fr>
<code>current</code>
<en> field) at this point.</en>
<fr> )  cet endroit.</fr>
</p>
<p>
<en>As we can see, this structure can quickly become a pain to define and read.
To solve this problem, the </en>
<fr>Comme on peut le voir, cette structure peut rapidement devenir difficile
 crire et  lire. Pour pallier  ce problme, l'outil
</fr>
<tt><local href="report:gui-invocation">report_gui</local></tt>
<en> tool allows to graphically define the document
 description and the </en>
<fr> permet de dfinir graphiquement la description de document tandis que l'outil
</fr>
<tt><local href="report:generator-invocation">report</local></tt>
<en> tool generates the OCaml code of this structure.
</en>
<fr> permet de gnrer le code OCaml correspondant au document dcrit.
</fr>
</p>
<p>
<en>Moreover, the </en><fr>De plus, la valeur </fr>
<code>report</code>
<en> value could have had parameters; this is a way to
parametrize the final XML document.
</en>
<fr> pourrait avoir des paramtres; c'est une faon de paramtrer
le document XML final.
</fr>
</p>
</section>

<section name="report:library:functions">
<title><en>Functions</en><fr>Fonctions</fr></title>
<p>
<en>The </en><fr>Le module </fr><code>Report</code>
<en> module contains the following functions
</en>
<fr> contient les fonctions suivantes
</fr>:
</p>
<sample>
<![CDATA[(** Coerce report elements. *)
val coerce : 'a -> 'b

(** Compute a report and print it to the given formatter. *)
val compute : ?html: bool -> Format.formatter -> 'a report -> unit

(** Compute a report and print it in a file. *)
val compute_file : ?html: bool -> string -> 'a report -> unit]]>
</sample>
<p>
<en>The </en><fr>La fonction </fr><code>coerce</code>
<en> function is used to insert a </en>
<fr> est utilise pour insrer un </fr>
<code>'a report_ele</code>
<en> into the node of a </en>
<fr> dans le noeud d'un </fr>
<code>'b report_ele</code>,
<en> when </en>
<fr> quand </fr>
<code>'a</code>
<en> cannot be used as </en>
<fr> ne peut tre utilis comme </fr>
<code>'b</code>.
<en> This function must only be used for this purpose, as in the example above.</en>
<fr> Cette fonction ne doit tre utilise qu' cet effet, comme dans l'exemple ci-dessus.</fr>
</p>
<p>
<en>The </en><fr>La fonction </fr><code>compute</code>
<en> function takes a formatter and a document description and computes this description to
generate the final XML document in the given formatter. The </en>
<fr> prend en paramtre un formatter et une description de document et value cette
description pour gnrer le document XML final dans le formatter donn.
Le paramtre optionnel </fr>
<code>html</code>
<en> optional parameter allows not to close some tags (like </en>
<fr> permet de ne pas fermer certains tags (comme </fr>
<tt>br</tt>
<en> ) to generate HTML compliant documents.</en>
<fr> ) pour gnrer du HTML correct.</fr>
</p>
<p>
<en>The </en><fr>La fonction </fr><code>compute_file</code>
<en> function acts like </en>
<fr> agit comme la fonction </fr>
<code>compute</code>
<en> but writes in the given file instead of a formatter.</en>
<fr> mais crit dans le fichier donn au lieu d'un formatter.</fr>
</p>

</section>

</section>

<section name="report:gui-invocation">
<title><en>Invocation of the graphical editor</en><fr>Lancement de l'diteur graphique</fr></title>
<p>
<en>The </en><fr>L'outil </fr><tt>report.gui</tt>
<en> tool allows to describe a document (structure + code to fill it with information),
as well as the parameters of this document (these parameters become parameters of the
</en>
<fr> permet de dcrire un document (structure + code pour le remplir d'information),
ainsi que les paramtres de ce document (ces paramtres deviennent des paramtres
de la valeur </fr>
<code>report</code>
<en> value in the </en>
<fr> dans l'</fr>
<local href="report:code-example"><en>code example</en><fr>exemple de code</fr></local>).
<en> The document is describe through a graphical user interface with a tree oriented view.
</en>
<fr> Le contenu du document est dit dans une vue arborescente reprsentant la structure du document.</fr>
</p>
<p>
<en>The grapical editor is launched by the following command:</en>
<fr>L'diteur graphique est lanc par la commande suivante:</fr>
</p>
<command-line>
report.gui.{x,byte} [options] file [file2 [file3 ...]]
</command-line>
</section>

<section name="report:generator-invocation">
<title><en>Invocation of code generator</en><fr>Lancement du gnrateur de code</fr></title>
<p>
<en>The </en><fr>L'outil </fr><tt>report</tt>
<en> tool generates the OCaml code of the document description,
using the types defined in the </en>
<fr> gnre le code OCaml de la description de document, en utilisant les types dfinis
dans la </fr>
<local href="report:library"><en>Report library</en><fr>bibliothque Report</fr></local>.
</p>
<p>
<en>The code generator is launched by the following command:</en>
<fr>Le gnrateur de code est lanc par la commande suivante:</fr>
</p>
<command-line>
report.{x,byte} [options] file
</command-line>
<p>
<en>The following options are supported:
</en>
<fr>Les options suivantes sont supportes:
</fr>
</p>
<ul>
<li><b>-gen</b>
<en> generate code to (chop_extension &lt;file&gt;).ml
</en>
<fr> gnre le code dans le fichier (chop_extension &lt;file&gt;).ml
</fr>
</li>

<li><b>-o <i>file</i></b>
<en> generate the OCaml code in file </en>
<fr> gnre le code OCaml dans le fichier </fr>
<b><i>file</i></b>,
<en> instead of the default file, when the </en>
<fr> au lieu du fichier par dfaut, quand l'option </fr>
<b>-gen</b>
<en> option is given.</en>
<fr> est donne.</fr>
</li>
</ul>


</section>

<!--
<section name="report:using">
<title><en>Using Report</en><fr>Utiliser Report</fr></title>
<p>
<en>
</en>
<fr>
</fr>
</p>
<p>
<en>
</en>
<fr>
</fr>
</p>
<p>
<en>
</en>
<fr>
</fr>
</p>
<p>
<en>
</en>
<fr>
</fr>
</p>
<p>
<en>
</en>
<fr>
</fr>
</p>
</section>
-->
</page>