1 .TH OCAMLDOC 1 "February 6, 2004" "GNU/Linux" "User's Manual"
3 .de Sh \" Subsection heading
13 ocamldoc \- The Objective Caml documentation generator
46 .B \-inv\-merge\-ml\-mli
70 The Objective Caml documentation generator
72 generates documentation from special comments embedded in source files. The
73 comments used by OCamldoc are of the form
75 and follow the format described in the
76 .IR "The Objective Caml user's manual" .
78 OCamldoc can produce documentation in various formats: HTML, LaTeX, TeXinfo,
81 dependency graphs. Moreover, users can add their own
84 In this manpage, we use the word
86 to refer to any of the following parts of an OCaml source file: a type
87 declaration, a value, a module, an exception, a module type, a type
88 constructor, a record field, a class, a class type, a class method, a class
89 value or a class inheritance clause.
93 The following command-line options determine the format for the generated
94 documentation generated by
97 .Sh "Options for choosing the output format"
101 Generate documentation in HTML default format. The generated HTML pages are
102 stored in the current directory, or in the directory specified with the
104 option. You can customize the style of the generated pages by editing the
107 file, or by providing your own style sheet using option
111 is not generated if it already exists.
115 Generate documentation in LaTeX default format. The generated LaTeX document
118 or in the file specified with the
120 option. The document uses the style file
122 This file is generated when using the
124 option, if it does not already exist. You can change this file to customize
125 the style of your LaTeX documentation.
129 Generate documentation in TeXinfo default format. The generated LaTeX document
132 or in the file specified with the
138 Generate documentation as a set of Unix man pages. The generated pages are
139 stored in the current directory, or in the directory specified with the
145 Generate a dependency graph for the toplevel modules, in a format suitable for
146 displaying and processing by dot. The
148 tool is available from
149 .IR http://www.research.att.com/sw/tools/graphviz/ .
150 The textual representation of the graph is written to the file
152 or to the file specified with the
155 .BI dot \ ocamldoc.out
160 Dynamically load the given file (which extension usually is .cmo or .cma),
161 which defines a custom documentation generator. This option is supported by the
163 command, but not by its native-code version
165 If the given file is a simple one and does not exist in
166 the current directory, then ocamldoc looks for it in the custom
167 generators default directory.
171 Display the custom generators default directory.
175 Add the given directory to the path where to look for custom generators.
177 .Sh "General options"
181 Generate files in directory
183 rather than in the current directory.
187 Dump collected information into file. This information can be read with the
189 option in a subsequent invocation of
194 Hide the given complete module names in the generated documentation.
196 is a list of complete module names are separated by ',', without blanks. For
198 .IR Pervasives,M2.M3 .
201 .B \-inv\-merge\-ml\-mli
202 Inverse implementations and interfaces when merging. All elements in
203 implementation files are kept, and the
205 option indicates which parts of the comments in interface files are merged with
206 the comments in implementation files.
210 Always keep the source code for values, methods and instance variables, when
211 available. The source code is always kept when a .ml
212 file is given, but is by default discarded when a .mli
213 is given. This option allows to always keep the source code.
217 Load information from
219 which has been produced by
224 options can be given.
228 Specify merge options between interfaces and implementations.
230 can be one or several of the following characters:
263 .B \-no\-custom\-tags
264 Do not allow custom @-tags.
268 Keep elements placed after the
274 Output the generated documentation to
278 This option is meaningful only in conjunction with the
287 Pipe sources through preprocessor command.
291 Sort the list of top-level modules before generating the documentation.
295 Remove blank characters until the first asterisk ('*') in each line of comments.
301 as the title for the generated documentation.
307 as ocamldoc text to use as introduction (HTML, LaTeX and TeXinfo only).
308 For HTML, the file is used to create the whole "index.html" file.
312 Verbose mode. Display progress information.
316 Treat warnings as errors.
318 .Sh "Type-checking options"
321 calls the Objective Caml type-checker to obtain type informations. The
322 following options impact the type-checking phase. They have the same meaning
331 Add directory to the list of directories search for compiled interface files
336 Ignore non-optional labels in types.
340 Allow arbitrary recursive types. (See the
345 .Sh "Options for generating HTML pages"
347 The following options apply in conjunction with the
353 Display the complete list of parameters for functions and methods.
356 .BI \-css-style \ filename
357 Use filename as the Cascading Style Sheet file.
361 Colorize the OCaml code enclosed in [ ] and \\{[ ]\\}, using colors to emphasize
362 keywords, etc. If the code fragments are not syntactically correct, no color
367 Generate only index files.
369 .Sh "Options for generating LaTeX files"
371 The following options apply in conjunction with the
376 .B \-latex-value-prefix prefix
377 Give a prefix to use for the labels of the values in the generated LaTeX
378 document. The default prefix is the empty string. You can also use the options
379 .BR -latex-type-prefix ,
380 .BR -latex-exception-prefix ,
381 .BR -latex-module-prefix ,
382 .BR -latex-module-type-prefix ,
383 .BR -latex-class-prefix ,
384 .BR -latex-class-type-prefix ,
385 .B -latex-attribute-prefix
387 .BR -latex-method-prefix .
389 These options are useful when you have, for example, a type and a value
390 with the same name. If you do not specify prefixes, LaTeX will complain about
391 multiply defined labels.
394 .BI \-latextitle \ n,style
395 Associate style number
397 to the given LaTeX sectioning command style, e.g. section or subsection.
398 (LaTeX only.) This is useful when including the generated document in another
399 LaTeX document, at a given sectioning level. The default association is 1 for
400 section, 2 for subsection, 3 for subsubsection, 4 for paragraph and 5 for
405 Suppress header in generated documentation.
409 Do not generate a table of contents.
413 Suppress trailer in generated documentation.
417 Generate one .tex file per toplevel module, instead of the global
421 .Sh "Options for generating TeXinfo files"
423 The following options apply in conjunction with the
429 Escape accented characters in Info files.
434 Specify Info directory entry.
438 Specify section of Info directory.
442 Suppress header in generated documentation.
446 Do not build index for Info files.
450 Suppress trailer in generated documentation.
452 .Sh "Options for generating dot graphs"
454 The following options apply in conjunction with the
459 .BI \-dot-colors \ colors
460 Specify the colors to use in the generated dot code. When generating module
463 uses different colors for modules, depending on the directories in which they
464 reside. When generating types dependencies,
466 uses different colors for types, depending on the modules in which they are
467 defined. colors is a list of color names separated by ',', as in
469 The available colors are the ones supported by the
475 Include all modules in the
477 output, not only modules given on the command line or loaded with the
483 Perform a transitive reduction of the dependency graph before outputting the
484 dot code. This can be useful if there are a lot of transitive dependencies
485 that clutter the graph.
489 Output dot code describing the type dependency graph instead of the module
492 .Sh "Options for generating man files"
494 The following options apply in conjunction with the
500 Generate man pages only for modules, module types, classes and class types,
501 instead of pages for all elements.
505 Set the suffix used for generated man filenames. Default is 'o', like in
514 .IR "The Objective Caml user's manual",
515 chapter "The documentation generator".