1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
{0 Parent/Child Specification}
This parent/child specification allows more flexible output support, e.g., per library documentation. See {{:https://v3.ocaml.org/packages}v3.ocaml.org/packages}.
The rules are;
{ul
{- [.mld] files may or may not have a parent [.mld].}
{- Compilation units must have a parent [.mld].}
{- The parent [.mld] file must be compiled before any of its children, and the children
must be specified at the parent's compilation time.}
{- The output paths of [.mld] files and compilation units are subdirectories of their parent's
output directory.}
{- The output directory of a [.mld] file [x.mld] with children is [<parent_output_directory>/x],
and its file name is [index.html]. That is to say, [<parent_output_directory>/x/index.html]}
{- The output directory of a [.mld] file [x.mld] without children is [<parent_output_directory> /x.html]}
{- The output directory of a compilation unit [X] is [<parent_output_directory>/X/index.html]}
}
{b Note:} The [--pkg <package>] option is still supported for backward compatibility in [odoc >= v2.0.0],
although it's now equivalent to specifying a parent [.mld] file.
For example, let's consider [John] whose is [Doe] and [Mark]'s father. [Doe] has
children, [Max], and page [foo], whereas [Mark] has no children. That is to say,
[john.mld], [doe.mld], [mark.mld], [max.mld], [foo.ml] respectively. For instance;
[john.mld]
{v
{0 About John}
I'm John the father to {{!page-doe}Doe} and {{!page-mark}Mark}.
v}
[doe.mld]
{v
{0 About Doe}
I'm Doe, the;
- son to {{!page-john}John}
- brother to {{!page-mark}Mark}
- father to {{!page-max}Max}
I also own page {{!page-foo}foo}
v}
[mark.mld]
{v
{0 About Mark}
I'm Mark {{!page-doe}Doe}'s brother and I have no children.
v}
[max.mld]
{v
{0 About Max}
I'm Max, the child to {{!page-doe}Doe}
v}
[foo.ml]
{[
(** I'm foo, a page child to Doe *)
]}
{2 Compilation}
{v
$ ocamlc -c -bin-annot foo.ml
&& odoc compile john.mld -c page-doe -c page-mark
&& odoc compile doe.mld -I . --parent page-john -c page-max -c foo
&& odoc compile max.mld -I . --parent page-doe
&& odoc compile foo.cmt -I . --parent page-doe
&& odoc compile mark.mld -I . --parent page-john
v}
The output of the compilation phase will be [.odoc] files, where each will be
linked by invoking the [odoc link] command on them.
{2 Linking}
[odoc link -I . <file>.odoc]
{v
$ odoc link -I . page-john.odoc
&& odoc link -I . page-doe.odoc
&& odoc link -I . page-mark.odoc
&& odoc link -I . page-max.odoc
&& odoc link -I . foo.odoc
v}
The output of the [odoc link] command is an [.odocl] file, by default, in the same path as the original [.odoc] file.
{2 Generating HTML}
{v
$ odoc html-generate --indent -o html page-john.odocl
&& odoc html-generate --indent -o html page-doe.odocl
&& odoc html-generate --indent -o html page-mark.odocl
&& odoc html-generate --indent -o html page-max.odocl
&& odoc html-generate --indent -o html foo.odocl
&& odoc support-files -o html
v}
Then we inspect the contents of the [html] directory using;
{v
$ ls -R html
highlight.pack.js
john
odoc.css
html/john:
doe
index.html
mark.html
html/john/doe:
Foo
index.html
max.html
html/john/doe/Foo:
index.
v}
{b Note:} We generated HTML files only for this example, but it's very possible to
generate files in other formats (i.e, latex and man-pages) using:
{ul
{- [$ odoc latex-generate -o latex <file>.odocl]}
{- [$ odoc man-generate -o man <file>.odocl]}
}
Of course there are different commands that [odoc] uses for other purposes; e.g.,
for inspection:
{ul
{- [odoc <html/latex/man>-targets ...] takes a glimpse of the expected targets}
{- [odoc compile-deps ...] lists units (with their digest) that need to be
compiled in order to compile the current compilation unit. The unit itself and its
digest is also reported in the output.}
}
For example, inspecting the dependencies required to compile [foo.cmt], we run
[odoc compile-deps foo.cmt]
and we shall get
{[
Stdlib aea3513d44d604b62eaff79ad12007b3
Foo 5ab79b5411a3c3476029260eda0b4a26
CamlinternalFormatBasics f562e7b79dbe1bb1591060d6b4e854cf
]}
For more about [odoc] commands, simply invoke [odoc --help] in your shell.
|
