PR#3915 update documentation

git-svn-id: http://caml.inria.fr/svn/ocaml/trunk@9025 f963ae5c-01c2-4b8c-9fe0-0dff7051ff02

12 files changed, 927 insertions, 462 deletions

diff --git a/man/ocaml.m b/man/ocaml.m
index 09e91f291..466dd3015 100644
--- a/man/ocaml.m
+++ b/man/ocaml.m
@@ -5,7 +5,6 @@
 .SH NAME
 ocaml \- The Objective Caml interactive toplevel
 
-
 .SH SYNOPSIS
 .B ocaml
 [
@@ -40,11 +39,8 @@ terminates
 
 If one or more
 .I object-files
-(ending in
-.B .cmo
-or
-.B .cma
- ) are given, they are loaded silently before starting the toplevel.
+(ending in .cmo or .cma) are given, they are loaded silently before
+starting the toplevel.
 
 If a
 .I script-file
@@ -72,7 +68,7 @@ If the given directory starts with
 .BR + ,
 it is taken relative to the
 standard library directory. For instance,
-.B \-I +labltk
+.B \-I\ +labltk
 adds the subdirectory
 .B labltk
 of the standard library to the search path.
@@ -96,7 +92,7 @@ and labelled parameters can be given in any order.  This is the default.
 .TP
 .B \-noassert
 Do not compile assertion checks.  Note that the special form
-.B assert false
+.B assert\ false
 is always compiled because it is typed specially.
 .TP
 .B \-nolabels
@@ -154,7 +150,7 @@ See
 for the syntax of the argument.
 .TP
 .BR \-help \ or \ \-\-help
-Display a usage summary and exit.
+Display a short usage summary and exit.
 
 .SH ENVIRONMENT VARIABLES
 .TP
diff --git a/man/ocamlc.m b/man/ocamlc.m
index 04b120cac..5615392b6 100644
--- a/man/ocamlc.m
+++ b/man/ocamlc.m
@@ -1,9 +1,10 @@
+\" $Id$
+
 .TH OCAMLC 1
 
 .SH NAME
 ocamlc \- The Objective Caml bytecode compiler
 
-
 .SH SYNOPSIS
 .B ocamlc
 [
@@ -90,7 +91,7 @@ file must come before all .cmo files that refer to the unit
 Arguments ending in .cma are taken to be libraries of object bytecode.
 A library of object bytecode packs in a single file a set of object
 bytecode files (.cmo files). Libraries are built with
-.B ocamlc \-a
+.B ocamlc\ \-a
 (see the description of the
 .B \-a
 option below). The object files
@@ -192,7 +193,7 @@ In case of a type error, dump all the information inferred by the
 type-checker before the error. The
 .IR src .annot
 file can be used with the emacs commands given in
-.B emacs/caml-types.el
+.B emacs/caml\-types.el
 to display types and other annotations interactively.
 .TP
 .B \-c
@@ -225,6 +226,11 @@ causes the C linker to search for C libraries in
 directory
 .IR dir .
 .TP
+.B \-config
+Print the version number of
+.BR ocamlc (1)
+and a detailed summary of its configuration, then exit.
+.TP
 .B \-custom
 Link in "custom runtime" mode. In the default linking mode, the
 linker produces bytecode that is intended to be executed with the
@@ -296,12 +302,12 @@ standard library directory. Directories added with
 are searched
 after the current directory, in the order in which they were given on
 the command line, but before the standard library directory.
-.IP
+
 If the given directory starts with
 .BR + ,
 it is taken relative to the
 standard library directory. For instance,
-.B \-I +labltk
+.B \-I\ +labltk
 adds the subdirectory
 .B labltk
 of the standard library to the search path.
@@ -331,7 +337,7 @@ flag is not given, unreferenced modules are not linked in. When
 building a library (option
 .BR \-a ),
 setting the
-.B -linkall
+.B \-linkall
 option forces all subsequent links of programs involving that library
 to link all the modules contained in the library.
 .TP
@@ -346,7 +352,7 @@ bytecode executables produced with the option
 .TP
 .B \-noassert
 Do not compile assertion checks.  Note that the special form
-.B assert false
+.B assert\ false
 is always compiled because it is typed specially.
 This flag has no effect when linking already-compiled files.
 .TP
@@ -398,7 +404,7 @@ the output .cmo file.  The name of the output .cmo file must be
 given with the
 .B \-o
 option.  For instance,
-.B ocamlc -pack -o p.cmo a.cmo b.cmo c.cmo
+.B ocamlc\ \-pack\ \-o\ p.cmo\ a.cmo\ b.cmo\ c.cmo
 generates compiled files p.cmo and p.cmi describing a compilation
 unit having three sub-modules A, B and C, corresponding to the
 contents of the object files a.cmo, b.cmo and c.cmo.  These
@@ -442,7 +448,7 @@ system "threads" library described in
 .IR The\ Objective\ Caml\ user's\ manual .
 .TP
 .B \-unsafe
-Turn bound checking off on array and string accesses (the
+Turn bound checking off for array and string accesses (the
 .BR v.(i) and s.[i]
 constructs). Programs compiled with
 .B \-unsafe
@@ -455,7 +461,7 @@ Generate a bytecode executable file that can be executed on the custom
 runtime system
 .IR runtime\-name ,
 built earlier with
-.B ocamlc -make-runtime
+.B ocamlc\ \-make\-runtime
 .IR runtime\-name .
 .TP
 .B \-v
@@ -469,7 +475,7 @@ invocations of the C compiler and linker in
 mode.  Useful to debug C library problems.
 .TP
 .B \-version
-Print the version number of the compiler in short form (e.g. 3.06),
+Print the version number of the compiler in short form (e.g. "3.11.0"),
 then exit.
 .TP
 .B \-vmthread
@@ -483,62 +489,63 @@ Enable or disable warnings according to the argument
 The argument is a set of letters.  If a letter is
 uppercase, it enables the corresponding warnings; lowercase disables
 the warnings.  The correspondence is the following:
-.TP
+
 .B A
-all warnings
-.TP
+\ \ all warnings
+
 .B C
-start of comments that look like mistakes
-.TP
+\ \ start of comments that look like mistakes
+
 .B D
-use of deprecated features
-.TP
+\ \ use of deprecated features
+
 .B E
-fragile pattern matchings (matchings that will remain
+\ \ fragile pattern matchings (matchings that will remain
 complete even if additional constructors are added to one of the
 variant types matched)
-.TP
+
 .B F
-partially applied functions (expressions whose result has
+\ \ partially applied functions (expressions whose result has
 function type and is ignored)
-.TP
+
 .B L
-omission of labels in applications
-.TP
+\ \ omission of labels in applications
+
 .B M
-overriding of methods
-.TP
+\ \ overriding of methods
+
 .B P
-missing cases in pattern matchings (i.e. partial matchings)
-.TP
+\ \ missing cases in pattern matchings (i.e. partial matchings)
+
 .B S
-expressions in the left-hand side of a sequence that don't
+\ \ expressions in the left-hand side of a sequence that don't
 have type
 .B unit
 (and that are not functions, see
 .B F
 above)
-.TP
+
 .B U
-redundant cases in pattern matching (unused cases)
-.TP
+\ \ redundant cases in pattern matching (unused cases)
+
 .B V
-overriding of instance variables
-.TP
+\ \ overriding of instance variables
+
 .B Y
-unused variables that are bound with
+\ \ unused variables that are bound with
 .BR let \ or \ as ,
 and don't start with an underscore (_) character
-.TP
+
 .B Z
-all other cases of unused variables that don't start with an
+\ \ all other cases of unused variables that don't start with an
 underscore (_) character
-.TP
+
 .B X
-warnings that don't fit in the above categories
+\ \ warnings that don't fit in the above categories (except
+.BR A )
 .IP
 The default setting is
-.BR Aelz ,
+.BR \-w\ Aelz ,
 enabling all warnings except fragile
 pattern matchings, omitted labels, and innocuous unused variables.
 Note that warnings
@@ -555,7 +562,7 @@ has the same meaning as for
 the "-w" option: an uppercase character turns the corresponding
 warning into an error, a lowercase character leaves it as a warning.
 The default setting is
-.B \-warn\-error a
+.B \-warn\-error\ a
 (none of the warnings is treated as an error).
 .TP
 .B \-where
@@ -567,10 +574,10 @@ Process
 as a file name, even if it starts with a dash (-) character.
 .TP
 .BR \-help \ or \ \-\-help
-Display a usage summary and exit.
+Display a short usage summary and exit.
 
 .SH SEE ALSO
 .BR ocamlopt (1), \ ocamlrun (1), \ ocaml (1).
 .br
-.I The Objective Caml user's manual,
+.IR "The Objective Caml user's manual" ,
 chapter "Batch compilation".
diff --git a/man/ocamlcp.m b/man/ocamlcp.m
index b5d8eef6a..d3559ad30 100644
--- a/man/ocamlcp.m
+++ b/man/ocamlcp.m
@@ -1,3 +1,5 @@
+\" $Id$
+
 .TH OCAMLCP 1
 
 .SH NAME
@@ -70,9 +72,9 @@ branch of an exception catcher
 
 .PP
 For instance, compiling with
-.B ocamlcp \-pfilm
+.B ocamlcp\ \-pfilm
 profiles function calls,
-\BR if \ ... \ then \ ... \ else \ ... ,
+.BR if \ ... \ then \ ... \ else \ ...,
 loops, and pattern matching.
 
 Calling
@@ -80,7 +82,7 @@ Calling
 without the
 .B \-p
 option defaults to
-.B \-p fm
+.B \-p\ fm
 meaning that only function calls and pattern matching are profiled.
 
 Note: due to the implementation of streams and stream patterns as
@@ -93,5 +95,5 @@ streams, we recommend using
 .BR ocamlc (1),
 .BR ocamlprof (1).
 .br
-.I The Objective Caml user's manual,
+.IR "The Objective Caml user's manual" ,
 chapter "Profiling".
diff --git a/man/ocamldebug.m b/man/ocamldebug.m
index 4e157ebfa..eb8619ba4 100644
--- a/man/ocamldebug.m
+++ b/man/ocamldebug.m
@@ -1,3 +1,5 @@
+\" $Id$
+
 .TH OCAMLDEBUG 1
 
 .SH NAME
@@ -8,30 +10,74 @@ ocamldebug \- the Objective Caml source-level replay debugger.
 .SH DESCRIPTION
 .B ocamldebug
 is the Objective Caml source-level replay debugger.
+
+Before the debugger can be used, the program must be compiled and
+linked with the
+.B \-g
+option: all .cmo and .cma files that are part
+of the program should have been created with
+.BR ocamlc\ \-g ,
+and they must be linked together with
+.BR ocamlc\ \-g .
+
+Compiling with
+.B \-g
+entails no penalty on the running time of
+programs: object files and bytecode executable files are bigger and
+take longer to produce, but the executable files run at
+exactly the same speed as if they had been compiled without
+.BR \-g .
+
 .SH OPTIONS
 A summary of options are included below.
 For a complete description, see the html documentation in the ocaml-doc
 package.
 .TP
-.B \-I directory
-Add directory to the list of directories searched for source files and
-compiled files.
+.BI \-c \ count
+Set the maximum number of simultaneously live checkpoints to
+.IR count .
 .TP
-.B \-s socket
-Use socket for communicating with the debugged program.
-.TP 
-.B \-c count
-Set the maximum number of simultaneously live checkpoints to count.
-.TP 
-.B \-cd directory
-Run the debugger program from the given directory,
-instead of the current working directory. 
+.BI \-cd \ dir
+Run the debugger program from the working directory
+.IR dir ,
+instead of the current working directory. (See also the
+.B cd
+command.)
 .TP
 .B \-emacs
-Tell the debugger it is executed under Emacs.
+Tell the debugger it is executed under Emacs.  (See
+.I "The Objective Caml user's manual"
+for information on how to run the debugger under Emacs.)
+.TP
+.BI \-I \ directory
+Add
+.I directory
+to the list of directories searched for source files and
+compiled files.  (See also the
+.B directory
+command.)
+.TP
+.BI \-s \ socket
+Use
+.I socket
+for communicating with the debugged program. See the description
+of the command
+.B set\ socket
+in
+.I "The Objective Caml user's manual"
+for the format of
+.IR socket .
+.TP
+.B \-version
+Print version and exit.
+.TP
+.BR \-help \ or \ \-\-help
+Display a short usage summary and exit.
 .SH SEE ALSO
-ocamldebug is documented fully in the Ocaml HTML documentation.
+.BR ocamlc (1)
+.br
+.IR "The Objective Caml user's manual" ,
+chapter "The debugger".
 .SH AUTHOR
 This manual page was written by Sven LUTHER <luther@debian.org>,
 for the Debian GNU/Linux system (but may be used by others).
-
diff --git a/man/ocamldep.m b/man/ocamldep.m
index 7b24082af..e5aa48add 100644
--- a/man/ocamldep.m
+++ b/man/ocamldep.m
@@ -4,15 +4,15 @@
 ocamldep \- Dependency generator for Objective Caml
 
 .SH SYNOPSIS
-.B ocamldep 
+.B ocamldep
 [
-.BI \-I \ lib-dir
+.I options
 ]
 .I filename ...
 
 .SH DESCRIPTION
 
-The 
+The
 .BR ocamldep (1)
 command scans a set of Objective Caml source files
 (.ml and .mli files) for references to external compilation units,
@@ -24,7 +24,7 @@ file is modified.
 
 The typical usage is:
 .P
-ocamldep 
+ocamldep
 .I options
 *.mli *.ml > .depend
 .P
@@ -32,30 +32,45 @@ where .depend is the file that should contain the
 dependencies.
 
 Dependencies are generated both for compiling with the bytecode
-compiler 
+compiler
 .BR ocamlc (1)
-and with the native-code compiler 
+and with the native-code compiler
 .BR ocamlopt (1).
 
 .SH OPTIONS
 
-The following command-line option is recognized by 
+The following command-line options are recognized by
 .BR ocamldep (1).
-
 .TP
 .BI \-I \ directory
 Add the given directory to the list of directories searched for
 source files. If a source file foo.ml mentions an external
 compilation unit Bar, a dependency on that unit's interface
 bar.cmi is generated only if the source for bar is found in the
-current directory or in one of the directories specified with 
-.BR -I .
+current directory or in one of the directories specified with
+.BR \-I .
 Otherwise, Bar is assumed to be a module from the standard library,
 and no dependencies are generated. For programs that span multiple
-directories, it is recommended to pass 
+directories, it is recommended to pass
 .BR ocamldep (1)
-the same -I options that are passed to the compiler.
-
+the same
+.B \-I
+options that are passed to the compiler.
+.TP
+.B \-modules
+Output raw dependencies of the form
+.IR filename : \ Module1\ Module2 \ ... \ ModuleN
+where
+.IR Module1 ,\ ..., \ ModuleN
+are the names of the compilation
+units referenced within the file
+.IR filename ,
+but these names are not
+resolved to source file names.  Such raw dependencies cannot be used
+by
+.BR make (1),
+but can be post-processed by other tools such as
+.BR Omake (1).
 .TP
 .BI \-native
 Generate dependencies for a pure native-code program (no bytecode
@@ -66,14 +81,30 @@ generates dependencies on the
 bytecode compiled file (.cmo file) to reflect interface changes.
 This can cause unnecessary bytecode recompilations for programs that
 are compiled to native-code only.  The flag
-.BR -native
+.B \-native
 causes dependencies on native compiled files (.cmx) to be generated instead
 of on .cmo files.  (This flag makes no difference if all source files
 have explicit .mli interface files.)
+.TP
+.BI \-pp \ command
+Cause
+.BR ocamldep (1)
+to call the given
+.I command
+as a preprocessor for each source file.
+.TP
+.B \-slash
+Under Unix, this option does nothing.
+.TP
+.B \-version
+Print version and exit.
+.TP
+.BR \-help \ or \ \-\-help
+Display a short usage summary and exit.
 
 .SH SEE ALSO
 .BR ocamlc (1),
 .BR ocamlopt (1).
 .br
-.I The Objective Caml user's manual,
+.IR The\ Objective\ Caml\ user's\ manual ,
 chapter "Dependency generator".
diff --git a/man/ocamldoc.m b/man/ocamldoc.m
index 5dcc0a52b..f3c7ab51f 100644
--- a/man/ocamldoc.m
+++ b/man/ocamldoc.m
@@ -1,13 +1,13 @@
-.TH OCAMLDOC 1 "February 6, 2004" "GNU/Linux" "User's Manual"
+.TH OCAMLDOC 1
 
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
+\" .de Sh \" Subsection heading
+\" .br
+\" .if t .Sp
+\" .ne 5
+\" .PP
+\" \fB\\$1\fR
+\" .PP
+\" ..
 
 .SH NAME
 ocamldoc \- The Objective Caml documentation generator
@@ -16,54 +16,9 @@ ocamldoc \- The Objective Caml documentation generator
 .SH SYNOPSIS
 .B ocamldoc
 [
-.B \-html
-]
-[
-.B \-latex
-]
-[
-.B \-texi
-]
-[
-.B \-man
-]
-[
-.B \-dot
+.I options
 ]
-[
-.BI \-g \ file
-]
-[
-.BI \-d \ dir
-]
-[
-.BI \-dump \ file
-]
-[
-.BI \-hide \ modules
-]
-[
-.B \-inv\-merge\-ml\-mli
-]
-[
-.B \-keep\-code
-]
-[
-.BI \-load \ file
-]
-[
-.BI \-m \ flags
-]
-[
-.BI \-o \ file
-]
-[
-.BI \-I \ directory
-]
-[
-.BI ...
-]
-.I filename ...
+.IR filename \ ...
 
 .SH DESCRIPTION
 
@@ -71,7 +26,7 @@ The Objective Caml documentation generator
 .BR ocamldoc (1)
 generates documentation from special comments embedded in source files. The
 comments used by OCamldoc are of the form
-.I (**...*)
+.I (** ... *)
 and follow the format described in the
 .IR "The Objective Caml user's manual" .
 
@@ -82,7 +37,7 @@ dependency graphs. Moreover, users can add their own
 custom generators.
 
 In this manpage, we use the word
-.IR element
+.I element
 to refer to any of the following parts of an OCaml source file: a type
 declaration, a value, a module, an exception, a module type, a type
 constructor, a record field, a class, a class type, a class method, a class
@@ -93,9 +48,7 @@ value or a class inheritance clause.
 The following command-line options determine the format for the generated
 documentation generated by
 .BR ocamldoc (1).
-
-.Sh "Options for choosing the output format"
-
+.SS "Options for choosing the output format"
 .TP
 .B \-html
 Generate documentation in HTML default format. The generated HTML pages are
@@ -105,11 +58,10 @@ option. You can customize the style of the generated pages by editing the
 generated
 .I style.css
 file, or by providing your own style sheet using option
-.B \-css\-style
-. The file
+.BR \-css\-style .
+The file
 .I style.css
 is not generated if it already exists.
-
 .TP
 .B \-latex
 Generate documentation in LaTeX default format. The generated LaTeX document
@@ -123,7 +75,6 @@ This file is generated when using the
 .B \-latex
 option, if it does not already exist. You can change this file to customize
 the style of your LaTeX documentation.
-
 .TP
 .B \-texi
 Generate documentation in TeXinfo default format. The generated LaTeX document
@@ -132,18 +83,18 @@ is saved in file
 or in the file specified with the
 .B -o
 option.
-
 .TP
 .B \-man
 Generate documentation as a set of Unix man pages. The generated pages are
 stored in the current directory, or in the directory specified with the
 .B \-d
 option.
-
 .TP
 .B \-dot
 Generate a dependency graph for the toplevel modules, in a format suitable for
-displaying and processing by dot. The
+displaying and processing by
+.IR dot (1).
+The
 .IR dot (1)
 tool is available from
 .IR http://www.research.att.com/sw/tools/graphviz/ .
@@ -154,75 +105,67 @@ or to the file specified with the
 option. Use
 .BI dot \ ocamldoc.out
 to display it.
-
 .TP
 .BI \-g \ file
 Dynamically load the given file (which extension usually is .cmo or .cma),
 which defines a custom documentation generator. This option is supported by the
 .BR ocamldoc (1)
 command, but not by its native-code version
-.BR ocamldoc.opt . 
+.BR ocamldoc.opt .
 If the given file is a simple one and does not exist in
-the current directory, then ocamldoc looks for it in the custom 
-generators default directory.
-
+the current directory, then ocamldoc looks for it in the custom
+generators default directory, and in the directories specified with the
+.B \-i
+option.
 .TP
 .BI \-customdir
 Display the custom generators default directory.
-
 .TP
 .BI \-i \ directory
 Add the given directory to the path where to look for custom generators.
-
-.Sh "General options"
-
+.SS "General options"
 .TP
 .BI \-d \ dir
 Generate files in directory
 .IR dir ,
-rather than in the current directory.
-
+rather than the current directory.
 .TP
 .BI \-dump \ file
-Dump collected information into file. This information can be read with the
-.B -load
+Dump collected information into
+.IR file .
+This information can be read with the
+.B \-load
 option in a subsequent invocation of
 .BR ocamldoc (1).
-
 .TP
 .BI \-hide \ modules
 Hide the given complete module names in the generated documentation.
 .I modules
-is a list of complete module names are separated by ',', without blanks. For
-instance:
+is a list of complete module names are separated by commas (,),
+without blanks. For instance:
 .IR Pervasives,M2.M3 .
-
 .TP
 .B \-inv\-merge\-ml\-mli
-Inverse implementations and interfaces when merging. All elements in
-implementation files are kept, and the
+Reverse the precedence of implementations and interfaces when merging.
+All elements in implementation files are kept, and the
 .B \-m
 option indicates which parts of the comments in interface files are merged with
 the comments in implementation files.
-
 .TP
 .B \-keep\-code
 Always keep the source code for values, methods and instance variables, when
 available. The source code is always kept when a .ml
 file is given, but is by default discarded when a .mli
 is given. This option allows to always keep the source code.
-
 .TP
 .BI \-load \ file
 Load information from
 .IR file ,
 which has been produced by
-.B ocamldoc
-.BR \-dump .
+.BR ocamldoc\ \-dump .
 Several
 .B -load
 options can be given.
-
 .TP
 .BI \-m flags
 Specify merge options between interfaces and implementations.
@@ -236,7 +179,7 @@ merge description
 merge @author
 
 .B v
-merge @version 
+merge @version
 
 .B l
 merge @see
@@ -245,30 +188,27 @@ merge @see
 merge @since
 
 .B o
-merge @deprecated 
+merge @deprecated
 
 .B p
-merge @param 
+merge @param
 
 .B e
-merge @raise 
+merge @raise
 
 .B r
-merge @return 
+merge @return
 
 .B A
-merge everything 
-
+merge everything
 .TP
 .B \-no\-custom\-tags
 Do not allow custom @-tags.
-
 .TP
 .B \-no\-stop
 Keep elements placed after the
-.I (**/**)
+.B (**/**)
 special comment.
-
 .TP
 .BI \-o \ file
 Output the generated documentation to
@@ -276,104 +216,97 @@ Output the generated documentation to
 instead of
 .IR ocamldoc.out .
 This option is meaningful only in conjunction with the
-.BR \-latex ,
-.BR \-texi ,
-or
-.B \-dot
+.BR \-latex , \ \-texi ,\ or \ \-dot
 options.
-
 .TP
 .BI \-pp \ command
-Pipe sources through preprocessor command.
-
+Pipe sources through preprocessor
+.IR command .
 .TP
 .B \-sort
 Sort the list of top-level modules before generating the documentation.
-
 .TP
 .B \-stars
 Remove blank characters until the first asterisk ('*') in each line of comments.
-
 .TP
 .BI \-t \ title
 Use
 .I title
 as the title for the generated documentation.
-
 .TP
 .BI \-intro \ file
 Use content of
 .I file
 as ocamldoc text to use as introduction (HTML, LaTeX and TeXinfo only).
 For HTML, the file is used to create the whole "index.html" file.
-
 .TP
 .B \-v
 Verbose mode. Display progress information.
-
 .TP
-.B \-warn-error
-Treat warnings as errors.
-
-.Sh "Type-checking options"
-
+.B \-version
+Print the version string and exit.
+.TP
+.B \-warn\-error
+Treat Ocamldoc warnings as errors.
+.TP
+.B \-hide\-warnings
+Do not print OCamldoc warnings.
+.TP
+.BR \-help \ or \ \-\-help
+Display a short usage summary and exit.
+.SS "Type-checking options"
 .BR ocamldoc (1)
 calls the Objective Caml type-checker to obtain type informations. The
 following options impact the type-checking phase. They have the same meaning
 as for the
-.BR ocamlc (1)
-and
-.BR ocamlopt (1)
+.BR ocamlc (1)\ and \ ocamlopt (1)
 commands.
-
 .TP
 .BI \-I \ directory
-Add directory to the list of directories search for compiled interface files
-(.cmi files).
-
+Add
+.I directory
+to the list of directories search for compiled interface files (.cmi files).
 .TP
 .B \-nolabels
 Ignore non-optional labels in types.
-
 .TP
 .B \-rectypes
  Allow arbitrary recursive types. (See the
 .B \-rectypes
 option to
 .BR ocamlc (1).)
-
-.Sh "Options for generating HTML pages"
-
+.SS "Options for generating HTML pages"
 The following options apply in conjunction with the
 .B \-html
 option:
-
 .TP
-.B \-all-params
+.B \-all\-params
 Display the complete list of parameters for functions and methods.
-
 .TP
-.BI \-css-style \ filename
-Use filename as the Cascading Style Sheet file.
-
+.BI \-css\-style \ filename
+Use
+.I filename
+as the Cascading Style Sheet file.
 .TP
-.B \-colorize-code
+.B \-colorize\-code
 Colorize the OCaml code enclosed in [ ] and \\{[ ]\\}, using colors to emphasize
 keywords, etc. If the code fragments are not syntactically correct, no color
 is added.
-
 .TP
-.B \-index-only
+.B \-index\-only
 Generate only index files.
-
-.Sh "Options for generating LaTeX files"
-
+.TP
+.B \-short\-functors
+Use a short form to display functors:
+.B "module M : functor (A:Module) -> functor (B:Module2) -> sig .. end"
+is displayed as
+.BR "module M (A:Module) (B:Module2) : sig .. end" .
+.SS "Options for generating LaTeX files"
 The following options apply in conjunction with the
 .B \-latex
 option:
-
 .TP
-.B \-latex-value-prefix prefix
+.B \-latex\-value\-prefix prefix
 Give a prefix to use for the labels of the values in the generated LaTeX
 document. The default prefix is the empty string. You can also use the options
 .BR -latex-type-prefix ,
@@ -382,81 +315,67 @@ document. The default prefix is the empty string. You can also use the options
 .BR -latex-module-type-prefix ,
 .BR -latex-class-prefix ,
 .BR -latex-class-type-prefix ,
-.B -latex-attribute-prefix
-and
+.BR -latex-attribute-prefix ,\ and
 .BR -latex-method-prefix .
 
 These options are useful when you have, for example, a type and a value
 with the same name. If you do not specify prefixes, LaTeX will complain about
 multiply defined labels.
-
 .TP
 .BI \-latextitle \ n,style
 Associate style number
 .I n
-to the given LaTeX sectioning command style, e.g. section or subsection.
+to the given LaTeX sectioning command
+.IR style ,
+e.g.
+.BR section or subsection .
 (LaTeX only.) This is useful when including the generated document in another
 LaTeX document, at a given sectioning level. The default association is 1 for
 section, 2 for subsection, 3 for subsubsection, 4 for paragraph and 5 for
 subparagraph.
-
 .TP
 .B \-noheader
 Suppress header in generated documentation.
-
 .TP
 .B \-notoc
 Do not generate a table of contents.
-
 .TP
 .B \-notrailer
 Suppress trailer in generated documentation.
-
 .TP
 .B \-sepfiles
 Generate one .tex file per toplevel module, instead of the global
 .I ocamldoc.out
-file. 
-
-.Sh "Options for generating TeXinfo files"
-
+file.
+.SS "Options for generating TeXinfo files"
 The following options apply in conjunction with the
 .B -texi
 option:
-
 .TP
 .B \-esc8
 Escape accented characters in Info files.
-
 .TP
 .B
-\-info-entry
+\-info\-entry
 Specify Info directory entry.
-
 .TP
-.B \-info-section
+.B \-info\-section
 Specify section of Info directory.
-
 .TP
 .B \-noheader
 Suppress header in generated documentation.
-
 .TP
 .B \-noindex
 Do not build index for Info files.
-
 .TP
 .B \-notrailer
-Suppress trailer in generated documentation. 
-
-.Sh "Options for generating dot graphs"
-
+Suppress trailer in generated documentation.
+.SS "Options for generating dot graphs"
 The following options apply in conjunction with the
 .B \-dot
 option:
-
 .TP
-.BI \-dot-colors \ colors
+.BI \-dot\-colors \ colors
 Specify the colors to use in the generated dot code. When generating module
 dependencies,
 .BR ocamldoc (1)
@@ -464,46 +383,44 @@ uses different colors for modules, depending on the directories in which they
 reside. When generating types dependencies,
 .BR ocamldoc (1)
 uses different colors for types, depending on the modules in which they are
-defined. colors is a list of color names separated by ',', as in
-.IR Red,Blue,Green .
+defined.
+.I colors
+is a list of color names separated by commas (,), as in
+.BR Red,Blue,Green .
 The available colors are the ones supported by the
 .BR dot (1)
 tool.
-
 .TP
-.B \-dot-include-all
+.B \-dot\-include\-all
 Include all modules in the
 .BR dot (1)
 output, not only modules given on the command line or loaded with the
 .B \-load
 option.
-
 .TP
-.B \-dot-reduce
+.B \-dot\-reduce
 Perform a transitive reduction of the dependency graph before outputting the
 dot code. This can be useful if there are a lot of transitive dependencies
 that clutter the graph.
-
 .TP
-.B \-dot-types
+.B \-dot\-types
 Output dot code describing the type dependency graph instead of the module
 dependency graph.
-
-.Sh "Options for generating man files"
-
+.SS "Options for generating man files"
 The following options apply in conjunction with the
 .B \-man
 option:
-
 .TP
-.B \-man-mini
+.B \-man\-mini
 Generate man pages only for modules, module types, classes and class types,
 instead of pages for all elements.
-
 .TP
-.B \-man-suffix
-Set the suffix used for generated man filenames. Default is 'o', like in
+.BI \-man\-suffix suffix
+Set the suffix used for generated man filenames. Default is o, as in
 .IR List.o .
+.TP
+.BI \-man\-section section
+Set the section number used for generated man filenames. Default is 3.
 
 
 .SH SEE ALSO
diff --git a/man/ocamllex.m b/man/ocamllex.m
index 3b1340d33..58c9ec5e0 100644
--- a/man/ocamllex.m
+++ b/man/ocamllex.m
@@ -25,7 +25,7 @@ Running
 .BR ocamllex (1)
 on the input file
 .IR lexer \&.mll
-produces Caml code for a lexical analyzer in file 
+produces Caml code for a lexical analyzer in file
 .IR lexer \&.ml.
 
 This file defines one lexing function per entry point in the lexer
@@ -39,33 +39,45 @@ Lexing.from_string and Lexing.from_function create
 lexer buffers that read from an input channel, a character string, or
 any reading function, respectively.
 
-When used in conjunction with a parser generated by 
+When used in conjunction with a parser generated by
 .BR ocamlyacc (1),
 the semantic actions compute a value belonging to the type token defined
 by the generated parsing module.
 
 .SH OPTIONS
 
-The 
+The
 .BR ocamllex (1)
 command recognizes the following options:
-
-.TP
-.BI \-o \ output-file
-Specify the output file name
-.IR output-file
-instead of the default naming convention.
-
 .TP
 .B \-ml
-Output code that does not use the Caml built-in automata
+Output code that does not use OCaml's built-in automata
 interpreter. Instead, the automaton is encoded by Caml functions.
-This option is useful for debugging
+This option is mainly useful for debugging
 .BR ocamllex (1),
 using it for production lexers is not recommended.
+.TP
+.BI \-o \ output\-file
+Specify the name of the output file produced by
+.BR ocamllex (1).
+The default is the input file name, with its extension replaced by .ml.
+.TP
+.B \-q
+Quiet mode.
+.BR ocamllex (1)
+normally outputs informational messages
+to standard output.  They are suppressed if option
+.B \-q
+is used.
+.TP
+.BR \-v \ or \ \-version
+Print version and exit.
+.TP
+.BR \-help \ or \ \-\-help
+Display a short usage summary and exit.
 
 .SH SEE ALSO
 .BR ocamlyacc (1).
 .br
-.I The Objective Caml user's manual,
+.IR "The Objective Caml user's manual" ,
 chapter "Lexer and parser generators".
diff --git a/man/ocamlmktop.m b/man/ocamlmktop.m
index 1a956329c..1fb402b9b 100644
--- a/man/ocamlmktop.m
+++ b/man/ocamlmktop.m
@@ -26,59 +26,53 @@ ocamlmktop \- Building custom toplevel systems
 
 .SH DESCRIPTION
 
-The 
+The
 .BR ocamlmktop (1)
 command builds Objective Caml toplevels that
 contain user code preloaded at start-up.
-The 
+The
 .BR ocamlmktop (1)
 command takes as argument a set of
-.IR x \&.cmo
+.IR x .cmo
 and
-.IR x \&.cma
-files, and links them with the object files that implement the Objective 
+.IR x .cma
+files, and links them with the object files that implement the Objective
 Caml toplevel.  If the
-.B -custom
+.B \-custom
 flag is given, C object files and libraries (.o and .a files) can also
 be given on the command line and are linked in the resulting toplevel.
 
 .SH OPTIONS
 
-The following command-line options are recognized by 
+The following command-line options are recognized by
 .BR ocamlmktop (1).
-
 .TP
 .B \-v
 Print the version number of the compiler.
-
 .TP
-.BI \-cclib\ -l libname
-Pass the 
+.BI \-cclib\ \-l libname
+Pass the
 .BI \-l libname
 option to the C linker when linking in
 ``custom runtime'' mode (see the corresponding option for
 .BR ocamlc (1).
-
 .TP
 .B \-ccopt
 Pass the given option to the C compiler and linker, when linking in
 ``custom runtime'' mode. See the corresponding option for
 .BR ocamlc (1).
-
 .TP
 .B \-custom
 Link in ``custom runtime'' mode. See the corresponding option for
 .BR ocamlc (1).
-
 .TP
-.BI \-I  directory
+.BI \-I \ directory
 Add the given directory to the list of directories searched for
 compiled interface files (.cmo and .cma).
-
 .TP
-.BI \-o \ exec-file
+.BI \-o \ exec\-file
 Specify the name of the toplevel file produced by the linker.
-The default is is 
+The default is is
 .BR a.out .
 
 .SH SEE ALSO
diff --git a/man/ocamlopt.m b/man/ocamlopt.m
index da7c59974..62ec9fd06 100644
--- a/man/ocamlopt.m
+++ b/man/ocamlopt.m
@@ -1,48 +1,32 @@
 .TH OCAMLOPT 1
 
 .SH NAME
-ocamlopt \- The Objective Caml native-code compiler
 
+ocamlopt \- The Objective Caml native-code compiler
 
 .SH SYNOPSIS
+
 .B ocamlopt
 [
-.B \-acivS
-]
-[
-.BI \-cclib \ libname
-]
-[
-.BI \-ccopt \ option
-]
-[
-.B \-compact
+.I options
 ]
-[
-.B \-unsafe
-]
-[
-.BI \-o \ exec-file
-]
-[
-.BI \-I \ lib-dir
-]
-.I filename ...
+.IR filename \ ...
 
 .B ocamlopt.opt
-.I (same options)
+(same options)
 
 .SH DESCRIPTION
+
 The Objective Caml high-performance
-native-code compiler 
+native-code compiler
 .BR ocamlopt (1)
 compiles Caml source files to native code object files and link these
 object files to produce standalone executables.
 
-The 
+The
 .BR ocamlopt (1)
 command has a command-line interface very close to that
-of 
+of
 .BR ocamlc (1).
 It accepts the same types of arguments and processes them
 sequentially:
@@ -51,39 +35,39 @@ Arguments ending in .mli are taken to be source files for
 compilation unit interfaces. Interfaces specify the names exported by
 compilation units: they declare value names with their types, define
 public data types, declare abstract data types, and so on. From the
-file 
-.IR x \&.mli,
-the 
+file
+.IR x .mli,
+the
 .BR ocamlopt (1)
 compiler produces a compiled interface
-in the file 
-.IR x \&.cmi.
+in the file
+.IR x .cmi.
 The interface produced is identical to that
-produced by the bytecode compiler 
+produced by the bytecode compiler
 .BR ocamlc (1).
 
 Arguments ending in .ml are taken to be source files for compilation
 unit implementations. Implementations provide definitions for the
 names exported by the unit, and also contain expressions to be
-evaluated for their side-effects.  From the file 
-.IR x \&.ml,
-the 
+evaluated for their side-effects.  From the file
+.IR x .ml,
+the
 .BR ocamlopt (1)
-compiler produces two files: 
-.IR x \&.o,
-containing native object code, and 
-.IR x \&.cmx,
+compiler produces two files:
+.IR x .o,
+containing native object code, and
+.IR x .cmx,
 containing extra information for linking and
 optimization of the clients of the unit. The compiled implementation
-should always be referred to under the name 
-.IR x \&.cmx
-(when given a .o file, 
+should always be referred to under the name
+.IR x .cmx
+(when given a .o file,
 .BR ocamlopt (1)
 assumes that it contains code compiled from C, not from Caml).
 
-The implementation is checked against the interface file 
-.IR x \&.mli
-(if it exists) as described in the manual for 
+The implementation is checked against the interface file
+.IR x .mli
+(if it exists) as described in the manual for
 .BR ocamlc (1).
 
 Arguments ending in .cmx are taken to be compiled object code.  These
@@ -93,17 +77,17 @@ library, to produce a native-code executable program. The order in
 which .cmx and .ml arguments are presented on the command line is
 relevant: compilation units are initialized in that order at
 run-time, and it is a link-time error to use a component of a unit
-before having initialized it. Hence, a given 
-.IR x \&.cmx
+before having initialized it. Hence, a given
+.IR x .cmx
 file must come
-before all .cmx files that refer to the unit 
+before all .cmx files that refer to the unit
 .IR x .
 
 Arguments ending in .cmxa are taken to be libraries of object code.
 Such a library packs in two files
-.IR lib \&.cmxa
-and 
-.IR lib \&.a
+.IR lib .cmxa
+and
+.IR lib .a
 a set of object files (.cmx/.o files). Libraries are build with
 .B ocamlopt \-a
 (see the description of the
@@ -121,7 +105,7 @@ Arguments ending in .o or .a are assumed to be C object files and
 libraries. They are linked with the program.
 
 The output of the linking phase is a regular Unix executable file. It
-does not need 
+does not need
 .BR ocamlrun (1)
 to run.
 
@@ -138,56 +122,100 @@ is not available in all installations of Objective Caml.
 
 .SH OPTIONS
 
-The following command-line options are recognized by 
+The following command-line options are recognized by
 .BR ocamlopt (1).
-
 .TP
 .B \-a
 Build a library (.cmxa/.a file) with the object files (.cmx/.o
 files) given on the command line, instead of linking them into an
-executable file. The name of the library can be set with the 
+executable file. The name of the library must be set with the
 .B \-o
-option. The default name is library.cmxa.
+option.
 
+If
+.BR \-cclib \ or \ \-ccopt
+options are passed on the command
+line, these options are stored in the resulting .cmxa library.  Then,
+linking with this library automatically adds back the
+\BR \-cclib \ and \ \-ccopt
+options as if they had been provided on the
+command line, unless the
+.B \-noautolink
+option is given.
+.TP
+.B \-annot
+Dump detailed information about the compilation (types, bindings,
+tail-calls, etc).  The information for file
+.IR src .ml
+is put into file
+.IR src .annot.
+In case of a type error, dump all the information inferred by the
+type-checker before the error. The
+.IR src .annot
+file can be used with the emacs commands given in
+.B emacs/caml\-types.el
+to display types and other annotations interactively.
 .TP
 .B \-c
 Compile only. Suppress the linking phase of the
 compilation. Source code files are turned into compiled files, but no
 executable file is produced. This option is useful to
 compile modules separately.
-
 .TP
-.BI \-cclib\ -l libname
+.BI \-cc \ ccomp
+Use
+.I ccomp
+as the C linker called to build the final executable and as the C
+compiler for compiling .c source files.
+.TP
+.BI \-cclib\ \-l libname
 Pass the
-.BI -l libname
+.BI \-l libname
 option to the linker. This causes the given C library to be linked
 with the program.
-
 .TP
 .BI \-ccopt \ option
 Pass the given option to the C compiler and linker. For instance,
-.B -ccopt -L
-.I dir
+.BI \-ccopt\ \-L dir
 causes the C linker to search for C libraries in
-directory 
+directory
 .IR dir .
-
 .TP
 .B \-compact
 Optimize the produced code for space rather than for time. This
 results in smaller but slightly slower programs. The default is to
 optimize for speed.
-
+.TP
+.B \-config
+Print the version number of
+.BR ocamlopt (1)
+and a detailed summary of its configuration, then exit.
+.TP
+.BI \-for\-pack \ module\-path
+Generate an object file (.cmx and .o files) that can later be included
+as a sub-module (with the given access path) of a compilation unit
+constructed with
+.BR \-pack .
+For instance,
+.B ocamlopt\ \-for\-pack\ P\ \-c\ A.ml
+will generate a.cmx and a.o files that can later be used with
+.BR "ocamlopt -pack -o P.cmx a.cmx" .
+.TP
+.B \-g
+Add debugging information while compiling and linking. This option is
+required in order to produce stack backtraces when
+the program terminates on an uncaught exception (see
+.BR ocamlrun (1)).
 .TP
 .B \-i
 Cause the compiler to print all defined names (with their inferred
 types or their definitions) when compiling an implementation (.ml
-file). This can be useful to check the types inferred by the
+file). No compiled files (.cmo and .cmi files) are produced.
+This can be useful to check the types inferred by the
 compiler. Also, since the output follows the syntax of interfaces, it
 can help in writing an explicit interface (.mli file) for a file:
 just redirect the standard output of the compiler to a .mli file,
 and edit that file to remove all declarations of unexported names.
-
 .TP
 .BI \-I \ directory
 Add the given directory to the list of directories searched for
@@ -197,35 +225,384 @@ standard library directory. Directories added with -I are searched
 after the current directory, in the order in which they were given on
 the command line, but before the standard library directory.
 
+If the given directory starts with
+.BR + ,
+it is taken relative to the
+standard library directory. For instance,
+.B \-I\ +labltk
+adds the subdirectory
+.B labltk
+of the standard library to the search path.
+.TP
+.BI \-inline \ n
+Set aggressiveness of inlining to
+.IR n ,
+where
+.I n
+is a positive
+integer. Specifying
+.B \-inline 0
+prevents all functions from being
+inlined, except those whose body is smaller than the call site. Thus,
+inlining causes no expansion in code size. The default aggressiveness,
+.BR \-inline\ 1 ,
+allows slightly larger functions to be inlined, resulting
+in a slight expansion in code size. Higher values for the
+.B \-inline
+option cause larger and larger functions to become candidate for
+inlining, but can result in a serious increase in code size.
+.TP
+.BI \-intf \ filename
+Compile the file
+.I filename
+as an interface file, even if its extension is not .mli.
+.TP
+.BI \-intf\-suffix \ string
+Recognize file names ending with
+.I string
+as interface files (instead of the default .mli).
 .TP
-.BI \-o \ exec-file
+.B \-labels
+Labels are not ignored in types, labels may be used in applications,
+and labelled parameters can be given in any order.  This is the default.
+.TP
+.B \-linkall
+Force all modules contained in libraries to be linked in. If this
+flag is not given, unreferenced modules are not linked in. When
+building a library
+.RB ( \-a
+flag), setting the
+.B \-linkall
+flag forces all
+subsequent links of programs involving that library to link all the
+modules contained in the library.
+.TP
+.B \-noassert
+Do not compile assertion checks.  Note that the special form
+.B assert\ false
+is always compiled because it is typed specially.
+This flag has no effect when linking already-compiled files.
+.TP
+.B \-noautolink
+When linking .cmxa libraries, ignore
+.BR \-cclib \ and \ \-ccopt
+options potentially contained in the libraries (if these options were
+given when building the libraries).  This can be useful if a library
+contains incorrect specifications of C libraries or C options; in this
+case, during linking, set
+.B -noautolink
+and pass the correct C libraries and options on the command line.
+.TP
+.B \-nodynlink
+Allow the compiler to use some optimizations that are valid only for code
+that is never dynlinked.
+.TP
+.B \-nolabels
+Ignore non-optional labels in types. Labels cannot be used in
+applications, and parameter order becomes strict.
+.TP
+.BI \-o \ exec\-file
 Specify the name of the output file produced by the linker. The
-default output name is a.out, in keeping with the Unix tradition. If
-the 
+default output name is a.out, in keeping with the Unix tradition. If the
 .B \-a
-option is given, specify the name of the library produced.
+option is given, specify the name of the library produced. If the
+.B \-pack
+option is given, specify the name of the packed object file produced.
+If the
+.B \-output\-obj
+option is given, specify the name of the output file produced. If the
+.B \-shared
+option is given, specify the name of plugin file produced.
+.TP
+.B \-output\-obj
+Cause the linker to produce a C object file instead of an executable
+file. This is useful to wrap Caml code as a C library,
+callable from any C program. The name of the output object file is
+camlprog.o by default; it can be set with the
+.B \-o
+option.
+This option can also be used to produce a compiled shared/dynamic
+library (.so extension).
+.TP
+.B \-p
+Generate extra code to write profile information when the program is
+executed.  The profile information can then be examined with the
+analysis program
+.BR gprof (1).
+The
+.B \-p
+option must be given both at
+compile-time and at link-time.  Linking object files not compiled with
+.B \-p
+is possible, but results in less precise profiling.
+
+See the
+.BR gprof (1)
+man page for more information about the profiles.
+
+Full support for
+.BR gprof (1)
+is only available for certain platforms
+(currently: Intel x86/Linux and Alpha/Digital Unix).
+On other platforms, the
+.B \-p
+option will result in a less precise
+profile (no call graph information, only a time profile).
+.TP
+.B \-pack
+Build an object file (.cmx and .o files) and its associated compiled
+interface (.cmi) that combines the .cmx object
+files given on the command line, making them appear as sub-modules of
+the output .cmx file.  The name of the output .cmx file must be
+given with the
+.B \-o
+option.  For instance,
+.B ocamlopt\ -pack\ -o\ P.cmx\ A.cmx\ B.cmx\ C.cmx
+generates compiled files P.cmx, P.o and P.cmi describing a
+compilation unit having three sub-modules A, B and C,
+corresponding to the contents of the object files A.cmx, B.cmx and
+C.cmx.  These contents can be referenced as P.A, P.B and P.C
+in the remainder of the program.
+
+The .cmx object files being combined must have been compiled with
+the appropriate
+.B \-for\-pack
+option.  In the example above,
+A.cmx, B.cmx and C.cmx must have been compiled with
+.BR ocamlopt\ \-for\-pack\ P .
 
+Multiple levels of packing can be achieved by combining
+.B \-pack
+with
+.BR \-for\-pack .
+See
+.IR "The Objective Caml user's manual" ,
+chapter "Native-code compilation" for more details.
+.TP
+.BI \-pp \ command
+Cause the compiler to call the given
+.I command
+as a preprocessor for each source file. The output of
+.I command
+is redirected to
+an intermediate file, which is compiled. If there are no compilation
+errors, the intermediate file is deleted afterwards.
+.TP
+.B \-principal
+Check information path during type-checking, to make sure that all
+types are derived in a principal way. All programs accepted in
+.B \-principal
+mode are also accepted in default mode with equivalent
+types, but different binary signatures.
+.TP
+.B \-rectypes
+Allow arbitrary recursive types during type-checking.  By default,
+only recursive types where the recursion goes through an object type
+are supported. Note that once you have created an interface using this
+flag, you must use it again for all dependencies.
 .TP
 .B \-S
 Keep the assembly code produced during the compilation. The assembly
-code for the source file 
-.IR x \&.ml
-is saved in the file 
-.IR x \&.s.
-
+code for the source file
+.IR x .ml
+is saved in the file
+.IR x .s.
 .TP
-.B \-v
-Print the version number of the compiler.
-
+.B \-shared
+Build a plugin (usually .cmxs) that can be dynamically loaded with
+the
+.B Dynlink
+module. The name of the plugin must be
+set with the
+.B \-o
+option. A plugin can include a number of Caml
+modules and libraries, and extra native objects (.o, .a files).
+Building native plugins is only supported for some
+operating system. Under some systems (currently,
+only Linux AMD 64), all the Caml code linked in a plugin must have
+been compiled without the
+.B \-nodynlink
+flag. Some constraints might also
+apply to the way the extra native objects have been compiled (under
+Linux AMD 64, they must contain only position-independent code).
+.TP
+.B \-thread
+Compile or link multithreaded programs, in combination with the
+system threads library described in
+.IR "The Objective Caml user's manual" .
 .TP
 .B \-unsafe
-Turn bound checking off on array and string accesses (the v.(i) and
-s.[i] constructs). Programs compiled with -unsafe are therefore
+Turn bound checking off for array and string accesses (the
+.BR v.(i) and s.[i]
+constructs). Programs compiled with
+.B \-unsafe
+are therefore
 faster, but unsafe: anything can happen if the program accesses an
-array or string outside of its bounds.
+array or string outside of its bounds. Additionally, turn off the
+check for zero divisor in integer division and modulus operations.
+With
+.BR \-unsafe ,
+an integer division (or modulus) by zero can halt the
+program or continue with an unspecified result instead of raising a
+.B Division_by_zero
+exception.
+.TP
+.B \-v
+Print the version number of the compiler and the location of the
+standard library directory, then exit.
+.TP
+.B \-verbose
+Print all external commands before they are executed, in particular
+invocations of the assembler, C compiler, and linker.
+.TP
+.B \-version
+Print the version number of the compiler in short form (e.g. "3.11.0"),
+then exit.
+.TP
+.BI \-w \ warning\-list
+Enable or disable warnings according to the argument
+.IR warning\-list .
+The argument is a set of letters.  If a letter is
+uppercase, it enables the corresponding warnings; lowercase disables
+the warnings.  The correspondence is the following:
+
+.B A
+\ \ all warnings
+
+.B C
+\ \ start of comments that look like mistakes
+
+.B D
+\ \ use of deprecated features
+
+.B E
+\ \ fragile pattern matchings (matchings that will remain
+complete even if additional constructors are added to one of the
+variant types matched)
+
+.B F
+\ \ partially applied functions (expressions whose result has
+function type and is ignored)
+
+.B L
+\ \ omission of labels in applications
+
+.B M
+\ \ overriding of methods
+
+.B P
+\ \ missing cases in pattern matchings (i.e. partial matchings)
+
+.B S
+\ \ expressions in the left-hand side of a sequence that don't
+have type
+.B unit
+(and that are not functions, see
+.B F
+above)
+
+.B U
+\ \ redundant cases in pattern matching (unused cases)
+
+.B V
+\ \ overriding of instance variables
+
+.B Y
+\ \ unused variables that are bound with
+.BR let \ or \ as ,
+and don't start with an underscore (_) character
+
+.B Z
+\ \ all other cases of unused variables that don't start with an
+underscore (_) character
+
+.B X
+\ \ warnings that don't fit in the above categories (except
+.BR A )
+.IP
+The default setting is
+.BR \-w\ Aelz ,
+enabling all warnings except fragile
+pattern matchings, omitted labels, and innocuous unused variables.
+Note that warnings
+.BR F \ and \ S
+are not always triggered, depending on the internals of the type checker.
+.TP
+.BI \-warn\-error \ warning\-list
+Turn the warnings indicated in the argument
+.I warning\-list
+into errors.  The compiler will stop with an error when one of these
+warnings is emitted.  The
+.I warning\-list
+has the same meaning as for
+the "-w" option: an uppercase character turns the corresponding
+warning into an error, a lowercase character leaves it as a warning.
+The default setting is
+.B \-warn\-error\ a
+(none of the warnings is treated as an error).
+.TP
+.B \-where
+Print the location of the standard library, then exit.
+.TP
+.BI \- \ file
+Process
+.I file
+as a file name, even if it starts with a dash (-) character.
+.TP
+.BR \-help \ or \ \-\-help
+Display a short usage summary and exit.
+
+.SH OPTIONS FOR THE IA32 ARCHITECTURE
+
+The IA32 code generator (Intel Pentium, AMD Athlon) supports the
+following additional option:
+.TP
+.B \-ffast\-math
+Use the IA32 instructions to compute
+trigonometric and exponential functions, instead of calling the
+corresponding library routines.  The functions affected are:
+.BR atan ,
+.BR atan2 ,
+.BR cos ,
+.BR log ,
+.BR log10 ,
+.BR sin ,
+.B sqrt
+and
+.BR tan .
+The resulting code runs faster, but the range of supported arguments
+and the precision of the result can be reduced.  In particular,
+trigonometric operations
+.BR cos ,
+.BR sin ,
+.B tan
+have their range reduced to [-2^64, 2^64].
+
+.SH OPTIONS FOR THE AMD64 ARCHITECTURE
+
+The AMD64 code generator (64-bit versions of Intel Pentium and AMD
+Athlon) supports the following additional options:
+.TP
+.B \-fPIC
+Generate position-independent machine code.  This is the default.
+.TP
+.B \-fno\-PIC
+Generate position-dependent machine code.
+
+.SH OPTIONS FOR THE SPARC ARCHITECTURE
+The Sparc code generator supports the following additional options:
+.TP
+.B \-march=v8
+Generate SPARC version 8 code.
+.TP
+.B \-march=v9
+Generate SPARC version 9 code.
+.P
+The default is to generate code for SPARC version 7, which runs on all
+SPARC processors.
 
 .SH SEE ALSO
 .BR ocamlc (1).
 .br
-.I The Objective Caml user's manual,
+.IR "The Objective Caml user's manual" ,
 chapter "Native-code compilation".
diff --git a/man/ocamlprof.m b/man/ocamlprof.m
index abc5301dd..8c60c01cc 100644
--- a/man/ocamlprof.m
+++ b/man/ocamlprof.m
@@ -22,9 +22,9 @@ Objective Caml program instrumented with
 
 It produces a source listing of the program modules given as arguments
 where execution counts have been inserted as comments. For instance,
-.P
-ocamlprof foo.ml
-.P
+
+.B ocamlprof foo.ml
+
 prints the source code for the foo module, with comments indicating
 how many times the functions in this module have been called. Naturally,
 this information is accurate only if the source file has not been modified
@@ -33,14 +33,13 @@ since the profiling execution took place.
 .SH OPTIONS
 
 .TP
-.BI \-f \ dumpfile 
+.BI \-f \ dumpfile
 Specifies an alternate dump file of profiling information.
-The default is the file ocamlprof.dump in the current directory.
 .TP
 .BI \-F \ string
 Specifies an additional string to be output with profiling information.
 By default,
-.B ocamlprof
+.BR ocamlprof (1)
 will annotate programs with comments of the form
 .BI (* \ n \ *)
 where
@@ -48,10 +47,26 @@ where
 is the counter value for a profiling point. With option
 .BI \-F \ string
 the annotation will be
-.BI (* \ s\ n \ *)
+.BI (* \ string\ n \ *)
+.TP
+.BI \-impl \ filename
+Compile the file
+.I filename
+as an implementation file, even if its extension is not .ml.
+.TP
+.BI \-intf \ filename
+Compile the file
+.I filename
+as an interface file, even if its extension is not .mli.
+.TP
+.B \-version
+Print the version number of ocamlprof and exit.
+.TP
+.BR \-help \ or \ \-\-help
+Display a short usage summary and exit.
 
 .SH SEE ALSO
 .BR ocamlcp (1).
 .br
-.I The Objective Caml user's manual,
+.IR "The Objective Caml user's manual" ,
 chapter "Profiling".
diff --git a/man/ocamlrun.m b/man/ocamlrun.m
index 7db888bdd..3aead1643 100644
--- a/man/ocamlrun.m
+++ b/man/ocamlrun.m
@@ -6,15 +6,15 @@ ocamlrun \- The Objective Caml bytecode interpreter
 .SH SYNOPSIS
 .B ocamlrun
 [
-.B \-v
+.I options
 ]
 .I filename argument ...
 
 .SH DESCRIPTION
-The 
+The
 .BR ocamlrun (1)
 command executes bytecode files produced by the
-linking phase of the 
+linking phase of the
 .BR ocamlc (1)
 command.
 
@@ -22,54 +22,104 @@ The first non-option argument is taken to be the name of the file
 containing the executable bytecode. (That file is searched in the
 executable path as well as in the current directory.) The remaining
 arguments are passed to the Objective Caml program, in the string array
-Sys.argv. Element 0 of this array is the name of the
-bytecode executable file; elements 1 to 
+.BR Sys.argv .
+Element 0 of this array is the name of the
+bytecode executable file; elements 1 to
 .I n
 are the remaining arguments.
 
 In most cases, the bytecode
-executable files produced by the 
+executable files produced by the
 .BR ocamlc (1)
 command are self-executable,
-and manage to launch the 
+and manage to launch the
 .BR ocamlrun (1)
 command on themselves automatically.
 
 .SH OPTIONS
 
-The following command-line option is recognized by 
+The following command-line options are recognized by
 .BR ocamlrun (1).
-
 .TP
-.B \-v 
-When set, the memory manager prints verbose messages on standard error
-to signal garbage collections and heap extensions.
+.B \-b
+When the program aborts due to an uncaught exception, print a detailed
+"back trace" of the execution, showing where the exception was
+raised and which function calls were outstanding at this point.  The
+back trace is printed only if the bytecode executable contains
+debugging information, i.e. was compiled and linked with the
+.B \-g
+option to
+.BR ocamlc (1)
+set.  This option is equivalent to setting the
+.B b
+flag in the OCAMLRUNPARAM environment variable (see below).
+.TP
+.BI \-I \ dir
+Search the directory
+.I dir
+for dynamically-loaded libraries, in addition to the standard search path.
+.B \-p
+Print the names of the primitives known to this version of
+.BR ocamlrun (1)
+and exit.
+.TP
+.B \-v
+Direct the memory manager to print verbose messages on standard error.
+This is equivalent to setting
+.B v=63
+in the OCAMLRUNPARAM environment variable (see below).
+.TP
+.B \-version
+Print version and exit.
 
 .SH ENVIRONMENT VARIABLES
 
 The following environment variable are also consulted:
-
 .TP
-.B OCAMLRUNPARAM
-Set the garbage collection parameters.
-(If
-.B OCAMLRUNPARAM
+.B CAML_LD_LIBRARY_PATH
+Additional directories to search for dynamically-loaded libraries.
+.TP
+.B OCAMLLIB
+The directory containing the Objective Caml standard
+library.  (If
+.B OCAMLLIB
 is not set,
-.B CAMLRUNPARAM
-will be used instead.)
+.B CAMLLIB
+will be used instead.) Used to locate the ld.conf configuration file for
+dynamic loading.  If not set,
+default to the library directory specified when compiling Objective Caml.
+.TP
+.B OCAMLRUNPARAM
+Set the runtime system options and garbage collection parameters.
+(If OCAMLRUNPARAM is not set, CAMLRUNPARAM will be used instead.)
 This variable must be a sequence of parameter specifications.
 A parameter specification is an option letter followed by an =
-sign, a decimal number, and an optional multiplier.  There are seven
-options:
-.TP
-.BR b \ (backtrace)
-Print a stack backtrace in case of an uncaught exception.
+sign, a decimal number (or a hexadecimal number prefixed by
+.BR 0x ),
+and an optional multiplier.  There are nine options, six of which
+correspond to the fields of the
+.B control
+record documented in
+.IR "The Objective Caml user's manual",
+chapter "Standard Library", section "Gc".
+.TP
+.BR b
+Trigger the printing of a stack backtrace
+when an uncaught exception aborts the program.
+This option takes no argument.
+.TP
+.BR p
+Turn on debugging support for
+.BR ocamlyacc -generated
+parsers.  When this option is on,
+the pushdown automaton that executes the parsers prints a
+trace of its actions.  This option takes no argument.
 .TP
 .BR s \ (minor_heap_size)
-Size of the minor heap.
+The size of the minor heap (in words).
 .TP
 .BR i \ (major_heap_increment)
-Minimum size increment for the major heap.
+The default size increment for the major heap (in words).
 .TP
 .BR o \ (space_overhead)
 The major GC speed setting.
@@ -86,48 +136,51 @@ The initial size of the major heap (in words).
 .BR v \ (verbose)
 What GC messages to print to stderr.  This is a sum of values selected
 from the following:
-.TP
-.BR 1
+
+.B 0x001
 Start of major GC cycle.
-.TP
-.BR 2
+
+.B 0x002
 Minor collection and major GC slice.
-.TP
-.BR 4
+
+.B 0x004
 Growing and shrinking of the heap.
-.TP
-.BR 8
+
+.B 0x008
 Resizing of stacks and memory manager tables.
-.TP
-.BR 16
+
+.B 0x010
 Heap compaction.
-.TP
-.BR 32
+
+.BR 0x020
 Change of GC parameters.
-.TP
-.BR 64
+
+.BR 0x040
 Computation of major GC slice size.
-.TP
-.BR 128
-Calling of finalisation function.
-.TP
-.BR 256
-Startup messages.
+
+.BR 0x080
+Calling of finalisation functions.
+
+.BR 0x100
+Startup messages (loading the bytecode executable file, resolving
+shared libraries).
 
 The multiplier is
-.B k
-,
-.B M
-, or
-.B G
-, for multiplication by 2^10, 2^20, and 2^30 respectively.
+.BR k ,
+.BR M \ or
+.BR G ,
+for multiplication by 2^10, 2^20, and 2^30 respectively.
 For example, on a 32-bit machine under bash, the command
 .B export OCAMLRUNPARAM='s=256k,v=1'
 tells a subsequent
 .B ocamlrun
 to set its initial minor heap size to 1 megabyte and to print
 a message at the start of each major GC cycle.
-
+.TP
+.B CAMLRUNPARAM
+If OCAMLRUNPARAM is not found in the environment, then CAMLRUNPARAM
+will be used instead.  If CAMLRUNPARAM is not found, then the default
+values will be used.
 .TP
 .B PATH
 List of directories searched to find the bytecode executable file.
@@ -135,5 +188,5 @@ List of directories searched to find the bytecode executable file.
 .SH SEE ALSO
 .BR ocamlc (1).
 .br
-.I The Objective Caml user's manual,
+.IR "The Objective Caml user's manual" ,
 chapter "Runtime system".
diff --git a/man/ocamlyacc.m b/man/ocamlyacc.m
index fb6b2f34d..8fee26eda 100644
--- a/man/ocamlyacc.m
+++ b/man/ocamlyacc.m
@@ -15,18 +15,18 @@ ocamlyacc \- The Objective Caml parser generator
 
 .SH DESCRIPTION
 
-The 
+The
 .BR ocamlyacc (1)
 command produces a parser from a LALR(1) context-free grammar
 specification with attached semantic actions, in the style of
 .BR yacc (1).
-Assuming the input file is 
+Assuming the input file is
 .IR grammar \&.mly,
 running
 .B ocamlyacc
-produces Caml code for a parser in the file 
+produces Caml code for a parser in the file
 .IR grammar \&.ml,
-and its interface in file 
+and its interface in file
 .IR grammar \&.mli.
 
 The generated module defines one parsing function per entry point in
@@ -40,22 +40,14 @@ program. Lexer buffers are an abstract data type
 implemented in the standard library module Lexing. Tokens are values from
 the concrete type token, defined in the interface file
 .IR grammar \&.mli
-produced by 
+produced by
 .BR ocamlyacc (1).
 
 .SH OPTIONS
 
-The 
+The
 .BR ocamlyacc (1)
 command recognizes the following options:
-
-.TP
-.B \-v
-Generate a description of the parsing tables and a report on conflicts
-resulting from ambiguities in the grammar. The description is put in
-file 
-.IR grammar \&.output.
-
 .TP
 .BI \-b prefix
 Name the output files
@@ -63,9 +55,32 @@ Name the output files
 .IR prefix \&.mli,
 .IR prefix \&.output,
 instead of the default naming convention.
+.TP
+.B \-q
+This option has no effect.
+.TP
+.B \-v
+Generate a description of the parsing tables and a report on conflicts
+resulting from ambiguities in the grammar. The description is put in
+file
+.IR grammar .output.
+.TP
+.B \-version
+Print version and exit.
+.TP
+.B \-
+Read the grammar specification from standard input.  The default
+output file names are stdin.ml and stdin.mli.
+.TP
+.BI \-\- \ file
+Process
+.I file
+as the grammar specification, even if its name
+starts with a dash (-) character.  This option must be the last on the
+command line.
 
 .SH SEE ALSO
 .BR ocamllex (1).
 .br
-.I The Objective Caml user's manual,
+.IR "The Objective Caml user's manual" ,
 chapter "Lexer and parser generators".