l4/pkg/ocaml/ocaml/contrib/man/ocamldoc.m

   1 \" $Id: ocamldoc.m 9282 2009-05-27 14:35:27Z doligez $
   2
   3 .TH OCAMLDOC 1
   4
   5 \" .de Sh \" Subsection heading
   6 \" .br
   7 \" .if t .Sp
   8 \" .ne 5
   9 \" .PP
  10 \" \fB\\$1\fR
  11 \" .PP
  12 \" ..
  13
  14 .SH NAME
  15 ocamldoc \- The Objective Caml documentation generator
  16
  17
  18 .SH SYNOPSIS
  19 .B ocamldoc
  20 [
  21 .I options
  22 ]
  23 .IR filename \ ...
  24
  25 .SH DESCRIPTION
  26
  27 The Objective Caml documentation generator
  28 .BR ocamldoc (1)
  29 generates documentation from special comments embedded in source files. The
  30 comments used by OCamldoc are of the form
  31 .I (** ... *)
  32 and follow the format described in the
  33 .IR "The Objective Caml user's manual" .
  34
  35 OCamldoc can produce documentation in various formats: HTML, LaTeX, TeXinfo,
  36 Unix man pages, and
  37 .BR dot (1)
  38 dependency graphs. Moreover, users can add their own
  39 custom generators.
  40
  41 In this manpage, we use the word
  42 .I element
  43 to refer to any of the following parts of an OCaml source file: a type
  44 declaration, a value, a module, an exception, a module type, a type
  45 constructor, a record field, a class, a class type, a class method, a class
  46 value or a class inheritance clause.
  47
  48 .SH OPTIONS
  49
  50 The following command-line options determine the format for the generated
  51 documentation generated by
  52 .BR ocamldoc (1).
  53 .SS "Options for choosing the output format"
  54 .TP
  55 .B \-html
  56 Generate documentation in HTML default format. The generated HTML pages are
  57 stored in the current directory, or in the directory specified with the
  58 .B \-d
  59 option. You can customize the style of the generated pages by editing the
  60 generated
  61 .I style.css
  62 file, or by providing your own style sheet using option
  63 .BR \-css\-style .
  64 The file
  65 .I style.css
  66 is not generated if it already exists.
  67 .TP
  68 .B \-latex
  69 Generate documentation in LaTeX default format. The generated LaTeX document
  70 is saved in file
  71 .IR ocamldoc.out ,
  72 or in the file specified with the
  73 .B -o
  74 option. The document uses the style file
  75 .IR ocamldoc.sty .
  76 This file is generated when using the
  77 .B \-latex
  78 option, if it does not already exist. You can change this file to customize
  79 the style of your LaTeX documentation.
  80 .TP
  81 .B \-texi
  82 Generate documentation in TeXinfo default format. The generated LaTeX document
  83 is saved in file
  84 .IR ocamldoc.out ,
  85 or in the file specified with the
  86 .B -o
  87 option.
  88 .TP
  89 .B \-man
  90 Generate documentation as a set of Unix man pages. The generated pages are
  91 stored in the current directory, or in the directory specified with the
  92 .B \-d
  93 option.
  94 .TP
  95 .B \-dot
  96 Generate a dependency graph for the toplevel modules, in a format suitable for
  97 displaying and processing by
  98 .IR dot (1).
  99 The
 100 .IR dot (1)
 101 tool is available from
 102 .IR http://www.research.att.com/sw/tools/graphviz/ .
 103 The textual representation of the graph is written to the file
 104 .IR ocamldoc.out ,
 105 or to the file specified with the
 106 .B -o
 107 option. Use
 108 .BI dot \ ocamldoc.out
 109 to display it.
 110 .TP
 111 .BI \-g \ file
 112 Dynamically load the given file (which extension usually is .cmo or .cma),
 113 which defines a custom documentation generator.
 114 If the given file is a simple one and does not exist in
 115 the current directory, then ocamldoc looks for it in the custom
 116 generators default directory, and in the directories specified with the
 117 .B \-i
 118 option.
 119 .TP
 120 .BI \-customdir
 121 Display the custom generators default directory.
 122 .TP
 123 .BI \-i \ directory
 124 Add the given directory to the path where to look for custom generators.
 125 .SS "General options"
 126 .TP
 127 .BI \-d \ dir
 128 Generate files in directory
 129 .IR dir ,
 130 rather than the current directory.
 131 .TP
 132 .BI \-dump \ file
 133 Dump collected information into
 134 .IR file .
 135 This information can be read with the
 136 .B \-load
 137 option in a subsequent invocation of
 138 .BR ocamldoc (1).
 139 .TP
 140 .BI \-hide \ modules
 141 Hide the given complete module names in the generated documentation.
 142 .I modules
 143 is a list of complete module names are separated by commas (,),
 144 without blanks. For instance:
 145 .IR Pervasives,M2.M3 .
 146 .TP
 147 .B \-inv\-merge\-ml\-mli
 148 Reverse the precedence of implementations and interfaces when merging.
 149 All elements in implementation files are kept, and the
 150 .B \-m
 151 option indicates which parts of the comments in interface files are merged with
 152 the comments in implementation files.
 153 .TP
 154 .B \-keep\-code
 155 Always keep the source code for values, methods and instance variables, when
 156 available. The source code is always kept when a .ml
 157 file is given, but is by default discarded when a .mli
 158 is given. This option allows to always keep the source code.
 159 .TP
 160 .BI \-load \ file
 161 Load information from
 162 .IR file ,
 163 which has been produced by
 164 .BR ocamldoc\ \-dump .
 165 Several
 166 .B -load
 167 options can be given.
 168 .TP
 169 .BI \-m flags
 170 Specify merge options between interfaces and implementations.
 171 .I flags
 172 can be one or several of the following characters:
 173
 174 .B d
 175 merge description
 176
 177 .B a
 178 merge @author
 179
 180 .B v
 181 merge @version
 182
 183 .B l
 184 merge @see
 185
 186 .B s
 187 merge @since
 188
 189 .B o
 190 merge @deprecated
 191
 192 .B p
 193 merge @param
 194
 195 .B e
 196 merge @raise
 197
 198 .B r
 199 merge @return
 200
 201 .B A
 202 merge everything
 203 .TP
 204 .B \-no\-custom\-tags
 205 Do not allow custom @-tags.
 206 .TP
 207 .B \-no\-stop
 208 Keep elements placed after the
 209 .B (**/**)
 210 special comment.
 211 .TP
 212 .BI \-o \ file
 213 Output the generated documentation to
 214 .I file
 215 instead of
 216 .IR ocamldoc.out .
 217 This option is meaningful only in conjunction with the
 218 .BR \-latex , \ \-texi ,\ or \ \-dot
 219 options.
 220 .TP
 221 .BI \-pp \ command
 222 Pipe sources through preprocessor
 223 .IR command .
 224 .TP
 225 .B \-sort
 226 Sort the list of top-level modules before generating the documentation.
 227 .TP
 228 .B \-stars
 229 Remove blank characters until the first asterisk ('*') in each line of comments.
 230 .TP
 231 .BI \-t \ title
 232 Use
 233 .I title
 234 as the title for the generated documentation.
 235 .TP
 236 .BI \-intro \ file
 237 Use content of
 238 .I file
 239 as ocamldoc text to use as introduction (HTML, LaTeX and TeXinfo only).
 240 For HTML, the file is used to create the whole "index.html" file.
 241 .TP
 242 .B \-v
 243 Verbose mode. Display progress information.
 244 .TP
 245 .B \-version
 246 Print the version string and exit.
 247 .TP
 248 .B \-warn\-error
 249 Treat Ocamldoc warnings as errors.
 250 .TP
 251 .B \-hide\-warnings
 252 Do not print OCamldoc warnings.
 253 .TP
 254 .BR \-help \ or \ \-\-help
 255 Display a short usage summary and exit.
 256 .SS "Type-checking options"
 257 .BR ocamldoc (1)
 258 calls the Objective Caml type-checker to obtain type informations. The
 259 following options impact the type-checking phase. They have the same meaning
 260 as for the
 261 .BR ocamlc (1)\ and \ ocamlopt (1)
 262 commands.
 263 .TP
 264 .BI \-I \ directory
 265 Add
 266 .I directory
 267 to the list of directories search for compiled interface files (.cmi files).
 268 .TP
 269 .B \-nolabels
 270 Ignore non-optional labels in types.
 271 .TP
 272 .B \-rectypes
 273  Allow arbitrary recursive types. (See the
 274 .B \-rectypes
 275 option to
 276 .BR ocamlc (1).)
 277 .SS "Options for generating HTML pages"
 278 The following options apply in conjunction with the
 279 .B \-html
 280 option:
 281 .TP
 282 .B \-all\-params
 283 Display the complete list of parameters for functions and methods.
 284 .TP
 285 .BI \-css\-style \ filename
 286 Use
 287 .I filename
 288 as the Cascading Style Sheet file.
 289 .TP
 290 .B \-colorize\-code
 291 Colorize the OCaml code enclosed in [ ] and \\{[ ]\\}, using colors to emphasize
 292 keywords, etc. If the code fragments are not syntactically correct, no color
 293 is added.
 294 .TP
 295 .B \-index\-only
 296 Generate only index files.
 297 .TP
 298 .B \-short\-functors
 299 Use a short form to display functors:
 300 .B "module M : functor (A:Module) -> functor (B:Module2) -> sig .. end"
 301 is displayed as
 302 .BR "module M (A:Module) (B:Module2) : sig .. end" .
 303 .SS "Options for generating LaTeX files"
 304 The following options apply in conjunction with the
 305 .B \-latex
 306 option:
 307 .TP
 308 .B \-latex\-value\-prefix prefix
 309 Give a prefix to use for the labels of the values in the generated LaTeX
 310 document. The default prefix is the empty string. You can also use the options
 311 .BR -latex-type-prefix ,
 312 .BR -latex-exception-prefix ,
 313 .BR -latex-module-prefix ,
 314 .BR -latex-module-type-prefix ,
 315 .BR -latex-class-prefix ,
 316 .BR -latex-class-type-prefix ,
 317 .BR -latex-attribute-prefix ,\ and
 318 .BR -latex-method-prefix .
 319
 320 These options are useful when you have, for example, a type and a value
 321 with the same name. If you do not specify prefixes, LaTeX will complain about
 322 multiply defined labels.
 323 .TP
 324 .BI \-latextitle \ n,style
 325 Associate style number
 326 .I n
 327 to the given LaTeX sectioning command
 328 .IR style ,
 329 e.g.
 330 .BR section or subsection .
 331 (LaTeX only.) This is useful when including the generated document in another
 332 LaTeX document, at a given sectioning level. The default association is 1 for
 333 section, 2 for subsection, 3 for subsubsection, 4 for paragraph and 5 for
 334 subparagraph.
 335 .TP
 336 .B \-noheader
 337 Suppress header in generated documentation.
 338 .TP
 339 .B \-notoc
 340 Do not generate a table of contents.
 341 .TP
 342 .B \-notrailer
 343 Suppress trailer in generated documentation.
 344 .TP
 345 .B \-sepfiles
 346 Generate one .tex file per toplevel module, instead of the global
 347 .I ocamldoc.out
 348 file.
 349 .SS "Options for generating TeXinfo files"
 350 The following options apply in conjunction with the
 351 .B -texi
 352 option:
 353 .TP
 354 .B \-esc8
 355 Escape accented characters in Info files.
 356 .TP
 357 .B
 358 \-info\-entry
 359 Specify Info directory entry.
 360 .TP
 361 .B \-info\-section
 362 Specify section of Info directory.
 363 .TP
 364 .B \-noheader
 365 Suppress header in generated documentation.
 366 .TP
 367 .B \-noindex
 368 Do not build index for Info files.
 369 .TP
 370 .B \-notrailer
 371 Suppress trailer in generated documentation.
 372 .SS "Options for generating dot graphs"
 373 The following options apply in conjunction with the
 374 .B \-dot
 375 option:
 376 .TP
 377 .BI \-dot\-colors \ colors
 378 Specify the colors to use in the generated dot code. When generating module
 379 dependencies,
 380 .BR ocamldoc (1)
 381 uses different colors for modules, depending on the directories in which they
 382 reside. When generating types dependencies,
 383 .BR ocamldoc (1)
 384 uses different colors for types, depending on the modules in which they are
 385 defined.
 386 .I colors
 387 is a list of color names separated by commas (,), as in
 388 .BR Red,Blue,Green .
 389 The available colors are the ones supported by the
 390 .BR dot (1)
 391 tool.
 392 .TP
 393 .B \-dot\-include\-all
 394 Include all modules in the
 395 .BR dot (1)
 396 output, not only modules given on the command line or loaded with the
 397 .B \-load
 398 option.
 399 .TP
 400 .B \-dot\-reduce
 401 Perform a transitive reduction of the dependency graph before outputting the
 402 dot code. This can be useful if there are a lot of transitive dependencies
 403 that clutter the graph.
 404 .TP
 405 .B \-dot\-types
 406 Output dot code describing the type dependency graph instead of the module
 407 dependency graph.
 408 .SS "Options for generating man files"
 409 The following options apply in conjunction with the
 410 .B \-man
 411 option:
 412 .TP
 413 .B \-man\-mini
 414 Generate man pages only for modules, module types, classes and class types,
 415 instead of pages for all elements.
 416 .TP
 417 .BI \-man\-suffix suffix
 418 Set the suffix used for generated man filenames. Default is o, as in
 419 .IR List.o .
 420 .TP
 421 .BI \-man\-section section
 422 Set the section number used for generated man filenames. Default is 3.
 423
 424
 425 .SH SEE ALSO
 426 .BR ocaml (1),
 427 .BR ocamlc (1),
 428 .BR ocamlopt (1).
 429 .br
 430 .IR "The Objective Caml user's manual",
 431 chapter "The documentation generator".