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