OCaml — now with on-line help

I’m happy to tell you that the on-line help system for the OCaml toplevel has just been committed to our new  git repository.

So what does this mean?

Let’s take a look at a sample session:

$ rlwrap ocamlfind batteries/ocaml

        Objective Caml version 3.10.2

----------------------------------------------
|                                            |
|     This is OCaml, Batteries Included.     |
|                                            |
|                                            |
|      If you need help, type '#help;;'      |
|                                            |
----------------------------------------------

        Camlp4 Parsing version 3.10.2

We can type “#help“? Well, that’s new. Let’s type “#help;;“.

# #help;;
Welcome to OCaml, Batteries Included.

You are currently using the Toplevel of OCaml. You can think of it as
a powerful graphics calculator, or as a command-line comparable to
that of your operating system. It is also a nice way of learning OCaml
and of testing your algorithms and programs.

Notice character '#', at the start of some lines? That's called the
"prompt", it means that the Toplevel is waiting for your
orders.

Orders can take the form of value definitions, type definitions,
evaluations or directives. Value definitions let you teach OCaml new
tricks. Type definitions let you teach OCaml how to understand new
kinds of values informations and how to check that you're not making
mistakes when using your definitions. Evaluations let you actually do
something with your definitions, such as computing the result of your
algorithm, but also doing more complex things such as opening
applications, modifying files, or even creating websites. Any program
is composed of value definitions, type definitions and evaluations.

Finally, directives are not part of any program. They just let you
interact with the Toplevel, for instance by loading other programs,
reading the documentation, asking the Toplevel for information on
existing programs, etc. Directives are easy to spot, they also start
with character '#'. So, when you wrote "#help;;", that was a directive.

At this point, you may be interested in the following directives:
 #quit;;                   (*Use this to quit OCaml.            *)
 #use "some_file.ml";;     (*Use this to load another program.  *)
 #require "some_package";; (*Use this to load a library installed
                             on your computer.                  *)
 #help;;                   (*Well, you just used that one.      *)
 #man "some subject";;     (*Read the manual on some subject.   *)

Oh, don't forget: each order you give to the Toplevel should end with
";;".  That's how the Toplevel understands that you're done
writing. Otherwise, no matter how much you write, the Toplevel assumes
that you still intend to write more.

If you are new to programming, now is time to write
 #man "the tutorial";;

If you already know some other programming language, you should probably write
 #man "for programmers";;

Let’s take a look at this tutorial.

# #man "the tutorial";;
Opening help on language construction "the tutorial" (OCaml Batteries Included)

My web browser opens the tutorial at http://www.cs.jhu.edu/~scott/pl/lectures/caml-intro.html.

# #man "print_endline";;
Opening help on value "print_endline" (OCaml Batteries Included)

My web browser now displays the ocamldoc-generated help of Pervasives.print_endline.

# #man "input";;
Several definitions exist for "input".
This item exists as a method. For more information on "input" as a method, you may use
  #man_method "input";;

Item "input" also exists as a type. For more information on "input" as a type, you may use
  #man_type "input";;

Item "input" also exists as a value, with several possibilities. For more information on "input" as a value, you may use
  #man_value "Util.Digest.input";;
  #man_value "System.IO.input";;
  #man_value "Standard.input";;
  #man_value "Meta.Marshal.input";;

etc.

Nice, isn’t it?
We hope that this feature, together with the extended documentation provided with OCaml Batteries Included will prove useful for beginners and veterans alike.