ocamlweb: a literate programming tool
for Objective Caml

Jean-Christophe Filliâtre and Claude Marché
http://www.lri.fr/~filliatr/ocamlweb

1   Introduction

1. making a nice document with the code and its documentation;
2. generating a global index of cross-references, where each identifier is associated to the lists of sections where it is defined or used.

2   Principles

• a WEB style, where the code and documentation are displayed in sections, numbered consecutively starting from 1. A new section is started at the beginning of each file. You can also start a new section manually (see the paragraph below about controls);
  
  
• a L^AT_EX style, where you structure your document as you like, using the usual sectioning commands of L^AT_EX.

Escapings: code inside documentation and vice versa.

Controls.

(*s

 

Starts a new section. (Meaningless in L^AT_EX style.)

(*i   ...  i*)

 

Ignores all the text between those two delimiters. Such ``comments'' cannot be nested but any Caml code and comments may appear between them, included nested Caml comments. You can use those delimiters to enclose a comment that shouldn't appear in the document, but also to hide some Caml code, putting it between (*i*) and (*i*) in such a way that your code still compiles but is ignored by ocamlweb. (Notice that if you use the delimiters (*i and i*) directly, the text enclosed is commented for both Caml and ocamlweb.)

(*c

 

Tells ocamlweb that this is a real Caml comment an not a documentation text. Mainly useful is you want to insert comments after empty lines. However, this is not the spirit of ocamlweb, and you are encouraged to put the documentation in separate L^AT_EX paragraphs and not in traditional Caml comments.

(*r

 

Justifies an end-of-line comment on the right margin.

(*p   ...  *)

 

Insert some material in the L^AT_EX preamble. See also command line option -p.

Pretty-printing.

3   Hints to get a pretty document

4   Usage

Command line options

-o file, --output file

 

Redirects the output into the file `file'.

--noweb

 

In that case, there are no sections à la WEB, and the user structurates his document directly through L^AT_EX commands, like for instance \section, \subsection, etc. There is still an index, in the usual L^AT_EX sense. (Therefore, if you have introduced L^AT_EX sections and subsections, their numbers will appear in the index.)

-s , --short

 

Do not insert titles for the files. The default behavior is to insert a title like ``Module Foo'' or ``Interface for module Foo'' for each file.

--no-index

 

Do not output the index.

--dvi

 

Output in DVI format, instead of L^AT_EX format. (You need latex to be installed and present in your path.)

--ps

 

Output in PostScript format, instead of L^AT_EX format. (You need both latex and dvips to be installed and present in your path.)

--html

 

Output in HTML format, instead of L^AT_EX format. (You need both latex and hevea to be installed and present in your path.)

--hevea-option option

 

Passes the given option to hevea (to be used with the --html option). It is mainly useful to specify where the file ocamlweb.sty is to be found, when not installed in the hevea library directory, using --hevea-option "-I dir".

--extern-defs

 

Keeps the external definitions in the index i.e. the identifiers which are not defined in any part of the code. (The default behavior is to suppress them from the index, even if they are used somewhere in the code.)

--header

 

Does not skip the header of Caml files. The default behavior is to skip them, since there are usually made of copyright and license informations, which you do not want to see in the final document. Headers are identified as comments right at the beginning of the Caml file, and are stopped by any character other then a space outside a comment or by an empty line.

--no-preamble

 

Suppresses the header and trailer of the final document. Thus, you can insert the resulting document into a larger one.

-p string, --preamble string

 

Insert some material in the L^AT_EX preamble, right before \begin{document}. See also the control (*p.

--latex-option option

 

Passes the given option the L^AT_EX package ocamlweb.sty.

--impl file, --intf file, --tex file

 

Considers the file `file' respectively as a .ml file, a .mli file or a .tex file.

--files file

 

Read file names to process in file `file' as if they were given on the command line. Useful for program sources splitted in several directories. See FAQ.

--no-greek

 

Disable use of greek letters for single-letter type variables. For example, the declaration of List.hd is displayed as

List.hd : a list ® a

but with this option, it will be displayed as

List.hd : 'a list ® 'a

-q, --quiet

 

Be quiet. Do not print anything on standard error output except errors.

-h, --help

 

Gives a short summary of the options and exits.

-v, --version

 

Prints the version and exits.

5   The ocamlweb L^AT_EX style file

\usepackage[options]{ocamlweb}

noweb

 

Tells ocamlweb.sty that the document was generated with the --noweb option so that no WEB sections are used, and the index was generated by referencing the L^AT_EX sections, subsections, etc.

novisiblespaces

 

By default, spaces in strings of CAML code parts are output as . They will be output as real spaces if you select this option.

bypages / bysections

 

When not in WEB sectioning style, these options specify whether the index must refer to page numbers or section numbers. bypages is the default. In WEB sectioning style, this option has no effect.

ocwkw, ocwbt, ocwupperid, ocwlowerid, ocwtv

 

The one-argument macros to typeset keywords, base types (such as int, string, etc.), uppercase identifiers (type constructors, exception names, module names), lowercase identifiers and type variables respectively. Defaults are sans-serif for keywords and italic for all others. Some of the single-letter type variables are displayed by default as greek letters, but this behaviour can be selected by the --no-greek option.

For example, if you would like a slanted font for base types, you may insert

     \renewcommand{\ocwbt}[1]{\textsl{#1}}

anywhere between \usepackage{ocamlweb} and \begin{document}.

ocwlexkw, ocwlexident, ocwyacckw, ocwyaccident

 

Analogous macros as above, to typeset lex keywords, lex identifiers, yacc keywords and yacc identifiers respectively.

ocwinterface, ocwmodule, ocwinterfacepart, ocwcodepart

 

One-argument macros for typesetting the title of a .mli file, the title of a .ml file, the interface part of a .ml file and the code part of a .ml file, respectively. Defaults are is

\newcommand{\ocwinterface}[1]{\section*{Interface for module #1}}
\newcommand{\ocwmodule}[1]{\section*{Module #1}}
\newcommand{\ocwinterfacepart}{\subsection*{Interface}}
\newcommand{\ocwcodepart}{\subsection*{Code}}

and you may redefine them using \renewcommand.

6   FAQ

1. What about an HTML output?  
   
   Use hevea, the L^AT_EX to HTML translator written by Luc Maranget (freely available at http://pauillac.inria.fr/hevea/), with the following command-line:
   hevea   ocamlweb.sty   file.tex
   where file.tex is the document produced by ocamlweb. The package ocamlweb.sty contains the necessary support for hevea.
   
   
2. How can I customize the appearance of the final document?  
   
   You can redefine some of the L^AT_EX macros of the ocamlweb.sty style file. See Section 5. We do not recommend to modify the ocamlweb.sty file directly, since you would not be able to update easily to future versions. You should rather redefine the macros using \renewcommand. If you want to customize other parameters that are not currently customizable, please contact the developers.
   
   
3. How can I insert `usepackage' commands, or whatever else, in the L^AT_EX preamble?  
   
   Use the option -p or the corresponding control (*p.
   
   If you really want a different L^AT_EX preamble, for instance to use a L^AT_EX class other than article, then use the option --no-preamble and catenate the result with your own header and trailer (or use a \input or \include command to insert the file generated by ocamlweb in your main L^AT_EX file.)
   
   
4. How can I use square brackets in L^AT_EX, since they are reserved characters for ocamlweb?  
   
   There is no escape sequence for the moment. But there is an easy solution to this problem: define macros for your L^AT_EX notations involving square brackets and put them in the preamble or in a .tex file that you will provide on the ocamlweb command line. Then, there is no longer square brackets in your source comments, but only calls to these macros.
   
   
5. What about lexers and parsers?  
   
   There is support for ocamllex lexers and ocamlyacc parsers since version 0.9. They are recognized by their suffix on the command line (do not use option --impl anymore).
   
   
6. I would like my pattern-matching right-hand sides to be aligned. Is it possible?  
   
   No, it is not, since ocamlweb uses proportional fonts. But you can still align your pattern-matching in your source files, since ocamlweb converts multiple spaces into single ones.
   
   
7. What can I do with a large program with sources in several directories, organised as libraries?  
   
   First alternative: you can run an ocamlweb command in each directories, producing a documentation for each library. If you want to have the documentations alltogether in the same TeX file, run each ocamlweb commands with option --no-preamble to avoid generation of the L^AT_EX preamble, build by hand a master document file with the preamble you want, without forgetting the \usepackage{ocamlweb}, and input each file in each directory with the \input or the \include macro.
   
   Second alternative: the main problem with the first alternative is that you will have an separate index for each libraries. If you want a global index, you need the run only one ocamlweb command. If you don't want to put all source file names on one single command line, you can use the --files option which allows you to read the source file names from a file. Example :

       ocamlweb --files lib1/source-files --files lib2/source-files
   

   will produce documentation for files in lib1 and lib2 provided that the files source-files in each directory contain the name of the documented source files.

This document was translated from L^AT_EX by H^EV^EA.