= OCaml Task Force Policy area =

== OCamldoc API Ref ==

=== Why ? ===

Since ocaml is shipped with ocamldoc, most of documentation can be generated out of *.mli/*.ml files. This possiblity is very interesting, since it should help ocaml programmer to have a consistent bookshelf of OCaml library.

=== How ? ===

==== HTML ====

HTML generation is the most easy to handle. There is no name clash possibility and we can share date through the Applications/Programming section of doc-base (integrated bookshelf tools of debian). 

Most of the package can generate ocamldoc HTML data (since it is a common way to share this kind of information).

This is a first step toward generating a consistent HTML based documentation.

==== Man ====

Manpages are quite common in C/Perl programming languages. Generating ocamldoc manpages is possible -- but not done for most of the package.

There is a high probability of name clash (just because there is a high possibility that a C function with the same name exists). One way to avoid name clash is to have a specific man section (just as Perl with .3pm).

=== Tools ===

==== ocamldoc-api-ref-config ====

This tool handle data that should be useful to generate required file to comply with coming OCaml Documentation policy. This tool behaves like *-config script.

Quick command line argument summary:

Usage:

ocamldoc-api-ref-config [--html-directory|--doc-base-generate] PACKAGE

Options:

||--html-directory||Output the directory name where the generated ocamldoc generated file should go||
||--doc-base-generate||Generate debian/PACKAGE.doc-base.ocamldoc-apiref and output file created||
||--manpages||Generate debian/PACKAGE.manpages (possible extension)||

Example:

$> ocamldoc-api-ref-config --html-directory libzip-ocaml-dev

/usr/share/doc/libzip-ocaml-dev/html/api

$> ocamldoc-api-ref-config --doc-base-generate libzip-ocaml-dev

debian/libzip-ocaml-dev.doc-base.ocamldoc-apiref

CDBS integration:

@OCamlDocApiRef@ is substitued in debian/*.in file by the $(shell ocamldoc-api-ref-config --html-directory $(pkg))
(maybe this will need to redesign the loop of *.in file in the CDBS file to check to what package belongs the *.in file)

This can be used in *.install.in to install documentation in the good directory.

The dependency for compiling the documentation (-I flags) must include all the directory generated in every package which are under the OCAML_STDLIB_DIR. A OCAML_OCAMLDOC_OCAMLFIND_FLAGS variable will allow to use ocamlfind to solve external dependency when invoking ocamldoc. 

A rule will generate the .doc-base.ocamldoc-apiref for all packages defined in OCAML_OCAMLDOC_PACKAGES_DOCBASE variable.

A rule will generate the documentation and the .doc-base.ocamldoc-apiref for all packages defined in OCAML_OCAMLDOC_PACKAGES variable.