Argot – version 1.0

Introduction

Argot is an enhanced html generator for the ocamldoc comment-extraction tool for the Objective Caml language¹. Its name stems from the following acronym: Argot is a Raised Generator for the Ocamldoc Tool.
Argot, in its 1.0 version is designed to work with version 3.12.1 of Objective Caml. Argot is released under the gpl version 3. This licensing scheme should not cause any problem, as documentation generation will not contaminate code.
Bugs and requests for enhancement should be reported either at http://bugs.x9c.fr, or directly to argot@x9c.fr.

Building Argot

Argot can be built from sources using make (in its GNU Make 3.81 flavor), and Objective Caml version 3.12.1. No other dependency is needed. Following the classical Unix convention, the build and installation process consists in these three steps:

1. sh configure
2. make all
3. make install

During the first step, one can specify elements if they are not correctly inferred by the ./configure script; the following switches are available:

• -ocaml-prefix to specify the prefix path to the Objective Caml installation (usually /usr/local);
• -ocamlfind to specify the path to the ocamlfind executable (notice that the presence of ocamlfind² is optional, and that the tool is used only at installation if present);
• -no-native-dynlink to disable the build of the native version of the generator, even if native dynamic linking is available.

During the third and last step, according to local settings, it may be necessary to acquire privileged accesses, running for example sudo make install.

Running Argot

Through direct call to ocamldoc

Once installed, using Argot is as simple as switching from:

to:

where argot-path is ‘ocamlfind query argot‘ when installed through ocamlfind, and to either:

if not installed through ocamlfind.

Through ocamlbuild

First, one needs to create a modules.odocl file containing the list of modules to generate documentation for. Then, the following line should be added to the _tags file:

To handle the argot flag, it is necessary to define an ocamlbuild plugin, like the one presented by code sample 1. Finally, it is possible to call ocamlbuild. It may be necessary to specify an ocamldoc version compatible with the generator; to this end,one can pass the -ocamldoc /path/to/ocamldoc command-line switch (e.g.  in order to ensure that this is the bytecode version of ocamldoc that will be actually called by ocamlbuild).

Code sample 1: Example of ocamlbuild plugin.

open Ocamlbuild_plugin
open Ocamlbuild_pack

let () =
  dispatch begin function
    | After_rules ->
        flag ["argot"] (S[A"-i"; A"+custom"; A"-g"; A"argot.cmo"]);
        let myocamldoc tags =
          Ocaml_tools.ocamldoc_l_dir (tags -- "extension:html") in
        rule "ocamldoc: argot"
          ~prod:"%.docdir/index.html"
          ~dep:"%.odocl"
          ~stamp:"%.docdir/html.stamp"
          ~insert:`top
          (Ocaml_tools.document_ocaml_project ~ocamldoc:myocamldoc
             "%.odocl"
             "%.docdir/index.html"
             "%.docdir")
    | _ -> ()
  end

Using Argot

Text formatting

In addition to the already available {b ...} (for bold), {i ...} (for italic), and {e ...} (for emphasized), Argot provides the following text formatting modifiers:

• {s ...} for stroke;
• {u ...} for underline;
• {h ...} for highlight.

Tables

In order to define tables, the following elements can be used:

• {table ...} to actually define a table;
• {caption ...} to define its associated caption;
• {row ...} to add a row to the table;
• {header ...} to add an header cell to the row;
• {data ...} to add a data cell to the row;
• {span n ...} (where n should be a positive integer) to add a data cell spanning n columns to the row.

Here is an example of a complete table definition:

{table {caption the caption}
       {row {header key} {header value}}
       {row {data key1}  {data {i data1}}}
       {row {data key2}  {data {i data2}}}
       {row {span 2 summary}}}

Token substitution

Token substitution allows one to use the value of either an environment variable or a command-line switch into an html page. This may for example be useful to insert insert the current date, or to specify the path of an element at documentation generation time:

  {token DATE}
  file {token FILE_PATH}/file.ext

The value of a token is first searched in -define id value switches passed to the ocamldoc tool, and then searched among the environment variables.
Instead of passing multiple -define switches, it is also possible to load a bunch of definitions from a file through the -definitions file switch. Each line should have the following form: id=value, where the # character introduce comments (ending with the end of the line). Lines that do not conform to the given format are ignored.
Finally, it is possible to refer to other variables when defining a new one (as long as this does not create a circular definition). As an example, the following file could be passed to the -definitions switch:

BASE=/path/to # prefix
NAME=file
FILE=$(BASE)/$(NAME).txt

Images

It is possible to include images into the generated pages through {image path}. The image data will be directly embedded into the page using base64 format, in such a way that no external link remains in the generated html. There is thus no need to package the image along with the html pages.
To avoid to use the full path to the image, it is possible to use the aforementioned token substitution inside the image formatter:

  {image {token IMAGE_PATH}/img.png}

Then, one has to specify the value for IMAGE_PATH on the command-line through the -define switch seen above:

  ocamldoc -define IMAGE_PATH /path/to/images ...

Folding

When some explanation, albeit useful, is long and/or may appear as a digression, it is possible to fold it. It means that the texte inside a {fold digression} will appear as an ellipsis (i.e. ...) and will be unfolded (that is revealed) when the ellipsis will be clicked. At the opposite, clicking on the ellipsis while the foldable text is visible will make it disappear. Any formatting instruction can be used in the digression.

Additional tags

Argot also defines a bunch of new tags that can be used to enhance documentation. Some of these tags come with image icons; these have been designed by Mark James, released under the Creative Commons Attribution 2.5 License, and are available at http://www.famfamfam.com/lab/icons/silk/.
The additional tags are:

• @obvious, a bare placeholder;
• @typevar, to document type variables in the same way @param is used for parameters;
• @copyright and @license to be used along with the @author parameter;
• @alias, @synonym, and @equivalent, to define synonyms or equivalences;
  
• @todo, or @unimplemented, to mark an implementation-in-progress;
• @todoc, or @docme, to mark a documentation-in-progress;
• @tofix, or @fixme, to mark a fix-in-progress;
  
• @stateful, to mark that a given function relies on a state;
• @threadsafe, to mark that a given function can be used in a multithread context;
• @threadunsafe, to mark that a given function cannot be used in a multithread context;
  
• @attention, to introduce text by the icon;
• @bug, to introduce text by the icon;
• @error, to introduce text by the icon;
• @info, to introduce text by the icon;
• @new, to introduce text by the icon;
• @note, to introduce text by the icon;
• @remark, to introduce text by the icon;
• @warning, to introduce text by the icon.

The @license tag will only print its argument if it does not recognize the license, but will create a link to the actual webpage of the license otherwise. The list of predefined licenses is the following (the recognition being case insensitive):

• gpl, gpl1, and gplv1 will point to http://www.gnu.org/licenses/old-licenses/gpl-1.0.html
• gpl2, and gplv2 will point to http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
• gpl3, and gplv3 will point to http://www.gnu.org/licenses/gpl.html
• lgpl, and lgplv2 will point to http://www.gnu.org/licenses/old-licenses/lgpl-2.0.html
• lgpl21, lgpl2.1, lgpl2_1, lgplv21, lgplv2.1, and lgplv2_1 will point to http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
• lgpl3, and lgplv3 will point to http://www.gnu.org/licenses/lgpl.html
• agpl will point to http://www.gnu.org/licenses/agpl.html
• bsd will point to http://www.freebsd.org/copyright/license.html
• mit will point to http://www.opensource.org/licenses/mit-license.php
• apache will point to http://www.apache.org/licenses/
• qpl will point to http://doc.trolltech.com/3.0/license.html
• cecill, and cecill-a will point to http://www.cecill.info/licences/Licence_CeCILL_V2-en.html
• cecill-b will point to http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
• cecill-c will point to http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html

Search

Argot is able to embed search facilities into the generated pages when passed the -search command-line switch. The search window can then be opened by clicking on the magnifying glass (i.e.  ) that appears on the index.html page as well as on each module page.
The ability to open the search window from its icon, and to perform an actual search, needs JavaScript to be available and enabled on the browser used to consult the documentation.
The search window is composed of two parts: the upper part allowing to select search criteria, and the lower part displaying results. Clicking on a search result will make the main window point to the clicked element.
Three search modes are provided:

• search by exact name ;
• search by regular expression over names ;
• search by type.

Search by name

can be made on simple names as well as on fully qualified names. Moreover, all names can be used : values, types, modules, constructors, etc.

Search by regular expression

is akind to search by name except that all names matching the passed regular expression are returned. The regular expression should be written using the JavaScript syntax³. As an example, it is possible to retrieve all the elements starting with fold by using the following regular expression: fold.*.

Search by type

allows to search for a value by giving its type. It is based on the ideas put forward by Roberto Di Cosmo (in particular the ocamlsearch tool for CamlLight). This means that the search does not retrieve values with exactly the same type, but with values whose types are isomorphic⁴. Practically this means that for example:

• int -> float -> int, float -> int -> int, and float * int -> int are isomorphic (because the differences are only in the way and order parameters are passed);
• string and unit -> string are isomorphic (because one always has a unit value at hand);
• ’from list -> (’from -> ’to) -> ’to list and (’a -> ’b) -> ’a list -> ’b list are isomorphic (because type variables can be renamed, and parameters reordered).

As of version 1.0, type-based search is experimental and does not support the following features: objects, polymorphic variants, and labels.

1

The official Caml website can be reached at http://caml.inria.fr and contains the full development suite (compilers, tools, virtual machine, etc.) as well as links to third-party contributions.

2

Findlib, a library manager for Objective Caml, is available at http://projects.camlcity.org/projects/findlib.html

3

See http://www.w3schools.com/jsref/jsref_obj_regexp.asp for reference.

4

See http://www.dicosmo.org/ResearchThemes/ISOS/ISOShomepage.html for more information.

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