man/ocamldoc.m

   1 .TH OCAMLDOC 1 "February 6, 2004" "GNU/Linux" "User's Manual"
   2
   3 .de Sh \" Subsection heading
   4 .br
   5 .if t .Sp
   6 .ne 5
   7 .PP
   8 \fB\\$1\fR
   9 .PP
  10 ..
  11
  12 .SH NAME
  13 ocamldoc \- The Objective Caml documentation generator
  14
  15
  16 .SH SYNOPSIS
  17 .B ocamldoc
  18 [
  19 .B \-html
  20 ]
  21 [
  22 .B \-latex
  23 ]
  24 [
  25 .B \-texi
  26 ]
  27 [
  28 .B \-man
  29 ]
  30 [
  31 .B \-dot
  32 ]
  33 [
  34 .BI \-g \ file
  35 ]
  36 [
  37 .BI \-d \ dir
  38 ]
  39 [
  40 .BI \-dump \ file
  41 ]
  42 [
  43 .BI \-hide \ modules
  44 ]
  45 [
  46 .B \-inv\-merge\-ml\-mli
  47 ]
  48 [
  49 .B \-keep\-code
  50 ]
  51 [
  52 .BI \-load \ file
  53 ]
  54 [
  55 .BI \-m \ flags
  56 ]
  57 [
  58 .BI \-o \ file
  59 ]
  60 [
  61 .BI \-I \ directory
  62 ]
  63 [
  64 .BI ...
  65 ]
  66 .I filename ...
  67
  68 .SH DESCRIPTION
  69
  70 The Objective Caml documentation generator
  71 .BR ocamldoc (1)
  72 generates documentation from special comments embedded in source files. The
  73 comments used by OCamldoc are of the form
  74 .I (**...*)
  75 and follow the format described in the
  76 .IR "The Objective Caml user's manual" .
  77
  78 OCamldoc can produce documentation in various formats: HTML, LaTeX, TeXinfo,
  79 Unix man pages, and
  80 .BR dot (1)
  81 dependency graphs. Moreover, users can add their own
  82 custom generators.
  83
  84 In this manpage, we use the word
  85 .IR element
  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.
  90
  91 .SH OPTIONS
  92
  93 The following command-line options determine the format for the generated
  94 documentation generated by
  95 .BR ocamldoc (1).
  96
  97 .Sh "Options for choosing the output format"
  98
  99 .TP
 100 .B \-html
 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
 103 .B \-d
 104 option. You can customize the style of the generated pages by editing the
 105 generated
 106 .I style.css
 107 file, or by providing your own style sheet using option
 108 .B \-css\-style
 109 . The file
 110 .I style.css
 111 is not generated if it already exists.
 112
 113 .TP
 114 .B \-latex
 115 Generate documentation in LaTeX default format. The generated LaTeX document
 116 is saved in file
 117 .IR ocamldoc.out ,
 118 or in the file specified with the
 119 .B -o
 120 option. The document uses the style file
 121 .IR ocamldoc.sty .
 122 This file is generated when using the
 123 .B \-latex
 124 option, if it does not already exist. You can change this file to customize
 125 the style of your LaTeX documentation.
 126
 127 .TP
 128 .B \-texi
 129 Generate documentation in TeXinfo default format. The generated LaTeX document
 130 is saved in file
 131 .IR ocamldoc.out ,
 132 or in the file specified with the
 133 .B -o
 134 option.
 135
 136 .TP
 137 .B \-man
 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
 140 .B \-d
 141 option.
 142
 143 .TP
 144 .B \-dot
 145 Generate a dependency graph for the toplevel modules, in a format suitable for
 146 displaying and processing by dot. The
 147 .IR dot (1)
 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
 151 .IR ocamldoc.out ,
 152 or to the file specified with the
 153 .B -o
 154 option. Use
 155 .BI dot \ ocamldoc.out
 156 to display it.
 157
 158 .TP
 159 .BI \-g \ file
 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
 162 .BR ocamldoc (1)
 163 command, but not by its native-code version
 164 .BR ocamldoc.opt .
 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.
 168
 169 .TP
 170 .BI \-customdir
 171 Display the custom generators default directory.
 172
 173 .TP
 174 .BI \-i \ directory
 175 Add the given directory to the path where to look for custom generators.
 176
 177 .Sh "General options"
 178
 179 .TP
 180 .BI \-d \ dir
 181 Generate files in directory
 182 .IR dir ,
 183 rather than in the current directory.
 184
 185 .TP
 186 .BI \-dump \ file
 187 Dump collected information into file. This information can be read with the
 188 .B -load
 189 option in a subsequent invocation of
 190 .BR ocamldoc (1).
 191
 192 .TP
 193 .BI \-hide \ modules
 194 Hide the given complete module names in the generated documentation.
 195 .I modules
 196 is a list of complete module names are separated by ',', without blanks. For
 197 instance:
 198 .IR Pervasives,M2.M3 .
 199
 200 .TP
 201 .B \-inv\-merge\-ml\-mli
 202 Inverse implementations and interfaces when merging. All elements in
 203 implementation files are kept, and the
 204 .B \-m
 205 option indicates which parts of the comments in interface files are merged with
 206 the comments in implementation files.
 207
 208 .TP
 209 .B \-keep\-code
 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.
 214
 215 .TP
 216 .BI \-load \ file
 217 Load information from
 218 .IR file ,
 219 which has been produced by
 220 .B ocamldoc
 221 .BR \-dump .
 222 Several
 223 .B -load
 224 options can be given.
 225
 226 .TP
 227 .BI \-m flags
 228 Specify merge options between interfaces and implementations.
 229 .I flags
 230 can be one or several of the following characters:
 231
 232 .B d
 233 merge description
 234
 235 .B a
 236 merge @author
 237
 238 .B v
 239 merge @version
 240
 241 .B l
 242 merge @see
 243
 244 .B s
 245 merge @since
 246
 247 .B o
 248 merge @deprecated
 249
 250 .B p
 251 merge @param
 252
 253 .B e
 254 merge @raise
 255
 256 .B r
 257 merge @return
 258
 259 .B A
 260 merge everything
 261
 262 .TP
 263 .B \-no\-custom\-tags
 264 Do not allow custom @-tags.
 265
 266 .TP
 267 .B \-no\-stop
 268 Keep elements placed after the
 269 .I (**/**)
 270 special comment.
 271
 272 .TP
 273 .BI \-o \ file
 274 Output the generated documentation to
 275 .I file
 276 instead of
 277 .IR ocamldoc.out .
 278 This option is meaningful only in conjunction with the
 279 .BR \-latex ,
 280 .BR \-texi ,
 281 or
 282 .B \-dot
 283 options.
 284
 285 .TP
 286 .BI \-pp \ command
 287 Pipe sources through preprocessor command.
 288
 289 .TP
 290 .B \-sort
 291 Sort the list of top-level modules before generating the documentation.
 292
 293 .TP
 294 .B \-stars
 295 Remove blank characters until the first asterisk ('*') in each line of comments.
 296
 297 .TP
 298 .BI \-t \ title
 299 Use
 300 .I title
 301 as the title for the generated documentation.
 302
 303 .TP
 304 .BI \-intro \ file
 305 Use content of
 306 .I file
 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.
 309
 310 .TP
 311 .B \-v
 312 Verbose mode. Display progress information.
 313
 314 .TP
 315 .B \-warn-error
 316 Treat warnings as errors.
 317
 318 .Sh "Type-checking options"
 319
 320 .BR ocamldoc (1)
 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
 323 as for the
 324 .BR ocamlc (1)
 325 and
 326 .BR ocamlopt (1)
 327 commands.
 328
 329 .TP
 330 .BI \-I \ directory
 331 Add directory to the list of directories search for compiled interface files
 332 (.cmi files).
 333
 334 .TP
 335 .B \-nolabels
 336 Ignore non-optional labels in types.
 337
 338 .TP
 339 .B \-rectypes
 340  Allow arbitrary recursive types. (See the
 341 .B \-rectypes
 342 option to
 343 .BR ocamlc (1).)
 344
 345 .Sh "Options for generating HTML pages"
 346
 347 The following options apply in conjunction with the
 348 .B \-html
 349 option:
 350
 351 .TP
 352 .B \-all-params
 353 Display the complete list of parameters for functions and methods.
 354
 355 .TP
 356 .BI \-css-style \ filename
 357 Use filename as the Cascading Style Sheet file.
 358
 359 .TP
 360 .B \-colorize-code
 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
 363 is added.
 364
 365 .TP
 366 .B \-index-only
 367 Generate only index files.
 368
 369 .Sh "Options for generating LaTeX files"
 370
 371 The following options apply in conjunction with the
 372 .B \-latex
 373 option:
 374
 375 .TP
 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
 386 and
 387 .BR -latex-method-prefix .
 388
 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.
 392
 393 .TP
 394 .BI \-latextitle \ n,style
 395 Associate style number
 396 .I n
 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
 401 subparagraph.
 402
 403 .TP
 404 .B \-noheader
 405 Suppress header in generated documentation.
 406
 407 .TP
 408 .B \-notoc
 409 Do not generate a table of contents.
 410
 411 .TP
 412 .B \-notrailer
 413 Suppress trailer in generated documentation.
 414
 415 .TP
 416 .B \-sepfiles
 417 Generate one .tex file per toplevel module, instead of the global
 418 .I ocamldoc.out
 419 file.
 420
 421 .Sh "Options for generating TeXinfo files"
 422
 423 The following options apply in conjunction with the
 424 .B -texi
 425 option:
 426
 427 .TP
 428 .B \-esc8
 429 Escape accented characters in Info files.
 430
 431 .TP
 432 .B
 433 \-info-entry
 434 Specify Info directory entry.
 435
 436 .TP
 437 .B \-info-section
 438 Specify section of Info directory.
 439
 440 .TP
 441 .B \-noheader
 442 Suppress header in generated documentation.
 443
 444 .TP
 445 .B \-noindex
 446 Do not build index for Info files.
 447
 448 .TP
 449 .B \-notrailer
 450 Suppress trailer in generated documentation.
 451
 452 .Sh "Options for generating dot graphs"
 453
 454 The following options apply in conjunction with the
 455 .B \-dot
 456 option:
 457
 458 .TP
 459 .BI \-dot-colors \ colors
 460 Specify the colors to use in the generated dot code. When generating module
 461 dependencies,
 462 .BR ocamldoc (1)
 463 uses different colors for modules, depending on the directories in which they
 464 reside. When generating types dependencies,
 465 .BR ocamldoc (1)
 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
 468 .IR Red,Blue,Green .
 469 The available colors are the ones supported by the
 470 .BR dot (1)
 471 tool.
 472
 473 .TP
 474 .B \-dot-include-all
 475 Include all modules in the
 476 .BR dot (1)
 477 output, not only modules given on the command line or loaded with the
 478 .B \-load
 479 option.
 480
 481 .TP
 482 .B \-dot-reduce
 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.
 486
 487 .TP
 488 .B \-dot-types
 489 Output dot code describing the type dependency graph instead of the module
 490 dependency graph.
 491
 492 .Sh "Options for generating man files"
 493
 494 The following options apply in conjunction with the
 495 .B \-man
 496 option:
 497
 498 .TP
 499 .B \-man-mini
 500 Generate man pages only for modules, module types, classes and class types,
 501 instead of pages for all elements.
 502
 503 .TP
 504 .B \-man-suffix
 505 Set the suffix used for generated man filenames. Default is 'o', like in
 506 .IR List.o .
 507
 508
 509 .SH SEE ALSO
 510 .BR ocaml (1),
 511 .BR ocamlc (1),
 512 .BR ocamlopt (1).
 513 .br
 514 .IR "The Objective Caml user's manual",
 515 chapter "The documentation generator".