new ocamldoc manpage

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

1 files changed, 508 insertions, 0 deletions

diff --git a/man/ocamldoc.m b/man/ocamldoc.m
new file mode 100644
index 0000000000..26000f37d3
--- /dev/null
+++ b/man/ocamldoc.m
@@ -0,0 +1,508 @@
+.TH OCAMLDOC 1 "February 6, 2004" "GNU/Linux" "User's Manual"
+
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+
+.SH NAME
+ocamldoc \- The Objective Caml documentation generator
+
+
+.SH SYNOPSIS
+.B ocamldoc
+[
+.B \-html
+]
+[
+.B \-latex
+]
+[
+.B \-texi
+]
+[
+.B \-man
+]
+[
+.B \-dot
+]
+[
+.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 ...
+
+.SH DESCRIPTION
+
+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 (**...*)
+and follow the format described in the
+.IR "The Objective Caml user's manual" .
+
+OCamldoc can produce documentation in various formats: HTML, LaTeX, TeXinfo,
+Unix man pages, and
+.BR dot (1)
+dependency graphs. Moreover, users can add their own
+custom generators.
+
+In this manpage, we use the word
+.IR 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
+value or a class inheritance clause.
+
+.SH OPTIONS
+
+The following command-line options determine the format for the generated
+documentation generated by
+.BR ocamldoc (1).
+
+.Sh "Options for choosing the output format"
+
+.TP
+.B \-html
+Generate documentation in HTML default format. The generated HTML pages are
+stored in the current directory, or in the directory specified with the
+.B \-d
+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
+.I style.css
+is not generated if it already exists.
+
+.TP
+.B \-latex
+Generate documentation in LaTeX default format. The generated LaTeX document
+is saved in file
+.IR ocamldoc.out ,
+or in the file specified with the
+.B -o
+option. The document uses the style file
+.IR ocamldoc.sty .
+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
+is saved in file
+.IR ocamldoc.out ,
+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
+.IR dot (1)
+tool is available from
+.IR http://www.research.att.com/sw/tools/graphviz/ .
+The textual representation of the graph is written to the file
+.IR ocamldoc.out ,
+or to the file specified with the
+.B -o
+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 . 
+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.
+
+.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"
+
+.TP
+.BI \-d \ dir
+Generate files in directory
+.IR dir ,
+rather than in the current directory.
+
+.TP
+.BI \-dump \ file
+Dump collected information into 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:
+.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
+.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 .
+Several
+.B -load
+options can be given.
+
+.TP
+.BI \-m flags
+Specify merge options between interfaces and implementations.
+.I flags
+can be one or several of the following characters:
+
+.B d
+merge description
+
+.B a
+merge @author
+
+.B v
+merge @version 
+
+.B l
+merge @see
+
+.B s
+merge @since
+
+.B o
+merge @deprecated 
+
+.B p
+merge @param 
+
+.B e
+merge @raise 
+
+.B r
+merge @return 
+
+.B A
+merge everything 
+
+.TP
+.B \-no\-custom\-tags
+Do not allow custom @-tags.
+
+.TP
+.B \-no\-stop
+Keep elements placed after the
+.I (**/**)
+special comment.
+
+.TP
+.BI \-o \ file
+Output the generated documentation to
+.I file
+instead of
+.IR ocamldoc.out .
+This option is meaningful only in conjunction with the
+.BR \-latex ,
+.BR \-texi ,
+or
+.B \-dot
+options.
+
+.TP
+.BI \-pp \ command
+Pipe sources through preprocessor 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
+.B \-v
+Verbose mode. Display progress information.
+
+.TP
+.B \-warn-error
+Treat warnings as errors.
+
+.Sh "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)
+commands.
+
+.TP
+.BI \-I \ directory
+Add 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"
+
+The following options apply in conjunction with the
+.B \-html
+option:
+
+.TP
+.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.
+
+.TP
+.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
+Generate only index files.
+
+.Sh "Options for generating LaTeX files"
+
+The following options apply in conjunction with the
+.B \-latex
+option:
+
+.TP
+.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 ,
+.BR -latex-exception-prefix ,
+.BR -latex-module-prefix ,
+.BR -latex-module-type-prefix ,
+.BR -latex-class-prefix ,
+.BR -latex-class-type-prefix ,
+.B -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.
+(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"
+
+The following options apply in conjunction with the
+.B -texi
+option:
+
+.TP
+.B \-esc8
+Escape accented characters in Info files.
+
+.TP
+.B
+\-info-entry
+Specify Info directory entry.
+
+.TP
+.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"
+
+The following options apply in conjunction with the
+.B \-dot
+option:
+
+.TP
+.BI \-dot-colors \ colors
+Specify the colors to use in the generated dot code. When generating module
+dependencies,
+.BR ocamldoc (1)
+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 .
+The available colors are the ones supported by the
+.BR dot (1)
+tool.
+
+.TP
+.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
+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
+Output dot code describing the type dependency graph instead of the module
+dependency graph.
+
+.Sh "Options for generating man files"
+
+The following options apply in conjunction with the
+.B \-man
+option:
+
+.TP
+.B \-man-mini
+Generate man pages only for modules, module types, clases 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
+.IR List.o .
+
+
+.SH SEE ALSO
+.BR ocaml (1),
+.BR ocamlc (1),
+.BR ocamlopt (1).
+.br
+.IR "The Objective Caml user's manual",
+chapter "The documentation generator".