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
|
\section{Module \ocamlinlinecode{Markup}}\label{module-Markup}%
Here, we test the rendering of comment markup.
\subsection{Sections\label{sections}}%
Let's get these done first, because sections will be used to break up the rest of this test.
Besides the section heading above, there are also
\subsubsection{Subsection headings\label{subsection-headings}}%
and
\subsubsection{Sub-subsection headings\label{sub-subsection-headings}}%
but odoc has banned deeper headings. There are also title headings, but they are only allowed in mld files.
\subsubsection{Anchors\label{anchors}}%
Sections can have attached \hyperref[module-Markup-anchors]{\ocamlinlinecode{Anchors}[p\pageref*{module-Markup-anchors}]}, and it is possible to \hyperref[module-Markup-anchors]{\ocamlinlinecode{link}[p\pageref*{module-Markup-anchors}]} to them. Links to section headers should not be set in source code style.
\subsubsection{Paragraph\label{paragraph}}%
Individual paragraphs can have a heading.
\subsubsection{Subparagraph\label{subparagraph}}%
Parts of a longer paragraph that can be considered alone can also have headings.
\subsection{Styling\label{styling}}%
This paragraph has some styled elements: \bold{bold} and \emph{italic}, \bold{\emph{bold italic}}, \emph{emphasis}, \emph{\emph{emphasis} within emphasis}, \bold{\emph{bold italic}}, super\textsuperscript{script}, sub\textsubscript{script}. The line spacing should be enough for superscripts and subscripts not to look odd.
Note: \emph{In italics \emph{emphasis} is rendered as normal text while \emph{emphasis \emph{in} emphasis} is rendered in italics.} \emph{It also work the same in \href{\#}{links in italics with \emph{emphasis \emph{in} emphasis}.}\footnote{\url{\#}}}
\ocamlinlinecode{code} is a different kind of markup that doesn't allow nested markup.
It's possible for two markup elements to appear \bold{next} \emph{to} each other and have a space, and appear \bold{next}\emph{to} each other with no space. It doesn't matter \bold{how} \emph{much} space it was in the source: in this sentence, it was two space characters. And in this one, there is \bold{a} \emph{newline}.
This is also true between \emph{non-}\ocamlinlinecode{code} markup \emph{and} \ocamlinlinecode{code}.
Code can appear \bold{inside \ocamlinlinecode{other} markup}. Its display shouldn't be affected.
\subsection{Links and references\label{links-and-references}}%
This is a \href{\#}{link}\footnote{\url{\#}}. It sends you to the top of this page. Links can have markup inside them: \href{\#}{\bold{bold}}\footnote{\url{\#}}, \href{\#}{\emph{italics}}\footnote{\url{\#}}, \href{\#}{\emph{emphasis}}\footnote{\url{\#}}, \href{\#}{super\textsuperscript{script}}\footnote{\url{\#}}, \href{\#}{sub\textsubscript{script}}\footnote{\url{\#}}, and \href{\#}{\ocamlinlinecode{code}}\footnote{\url{\#}}. Links can also be nested \emph{\href{\#}{inside}\footnote{\url{\#}}} markup. Links cannot be nested inside each other. This link has no replacement text: \href{\#}{\#}\footnote{\url{\#}}. The text is filled in by odoc. This is a shorthand link: \href{\#}{\#}\footnote{\url{\#}}. The text is also filled in by odoc in this case.
This is a reference to \hyperref[module-Markup-val-foo]{\ocamlinlinecode{\ocamlinlinecode{foo}}[p\pageref*{module-Markup-val-foo}]}. References can have replacement text: \hyperref[module-Markup-val-foo]{\ocamlinlinecode{the value foo}[p\pageref*{module-Markup-val-foo}]}. Except for the special lookup support, references are pretty much just like links. The replacement text can have nested styles: \hyperref[module-Markup-val-foo]{\ocamlinlinecode{\bold{bold}}[p\pageref*{module-Markup-val-foo}]}, \hyperref[module-Markup-val-foo]{\ocamlinlinecode{\emph{italic}}[p\pageref*{module-Markup-val-foo}]}, \hyperref[module-Markup-val-foo]{\ocamlinlinecode{\emph{emphasis}}[p\pageref*{module-Markup-val-foo}]}, \hyperref[module-Markup-val-foo]{\ocamlinlinecode{super\textsuperscript{script}}[p\pageref*{module-Markup-val-foo}]}, \hyperref[module-Markup-val-foo]{\ocamlinlinecode{sub\textsubscript{script}}[p\pageref*{module-Markup-val-foo}]}, and \hyperref[module-Markup-val-foo]{\ocamlinlinecode{\ocamlinlinecode{code}}[p\pageref*{module-Markup-val-foo}]}. It's also possible to surround a reference in a style: \bold{\hyperref[module-Markup-val-foo]{\ocamlinlinecode{\ocamlinlinecode{foo}}[p\pageref*{module-Markup-val-foo}]}}. References can't be nested inside references, and links and references can't be nested inside each other.
\subsection{Preformatted text\label{preformatted-text}}%
This is a code block:\medbreak
\begin{ocamlcodeblock}
let foo = ()
(** There are some nested comments in here, but an unpaired comment
terminator would terminate the whole doc surrounding comment. It's
best to keep code blocks no wider than 72 characters. *)
let bar =
ignore foo
\end{ocamlcodeblock}\medbreak
There are also verbatim blocks:
\begin{verbatim}The main difference is these don't get syntax highlighting.\end{verbatim}%
\subsection{Lists\label{lists}}%
\begin{itemize}\item{This is a}%
\item{shorthand bulleted list,}%
\item{and the paragraphs in each list item support \emph{styling}.}\end{itemize}%
\begin{enumerate}\item{This is a}%
\item{shorthand numbered list.}\end{enumerate}%
\begin{itemize}\item{Shorthand list items can span multiple lines, however trying to put two paragraphs into a shorthand list item using a double line break}\end{itemize}%
just creates a paragraph outside the list.
\begin{itemize}\item{Similarly, inserting a blank line between two list items}\end{itemize}%
\begin{itemize}\item{creates two separate lists.}\end{itemize}%
\begin{itemize}\item{To get around this limitation, one
can use explicitly-delimited lists.
}%
\item{This one is bulleted,}\end{itemize}%
\begin{enumerate}\item{but there is also the numbered variant.}\end{enumerate}%
\begin{itemize}\item{\begin{itemize}\item{lists}%
\item{can be nested}%
\item{and can include references}%
\item{\hyperref[module-Markup-val-foo]{\ocamlinlinecode{\ocamlinlinecode{foo}}[p\pageref*{module-Markup-val-foo}]}}\end{itemize}%
}\end{itemize}%
\subsection{Unicode\label{unicode}}%
The parser supports any ASCII-compatible encoding, in particuλar UTF-8.
\subsection{Raw HTML\label{raw-html}}%
Raw HTML can be as inline elements into sentences.
\subsection{Modules\label{modules}}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{\hyperref[module-Markup-module-X]{\ocamlinlinecode{\ocamlinlinecode{X}}[p\pageref*{module-Markup-module-X}]}}]{}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{\hyperref[module-Markup-module-X]{\ocamlinlinecode{\ocamlinlinecode{X}}[p\pageref*{module-Markup-module-X}]}}]{}%
\item[{\hyperref[module-Markup-module-Y]{\ocamlinlinecode{\ocamlinlinecode{Y}}[p\pageref*{module-Markup-module-Y}]}}]{}\end{description}%
\subsection{Tags\label{tags}}%
Each comment can end with zero or more tags. Here are some examples:
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{author}]{antron}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{deprecated}]{a \emph{long} time ago
}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{parameter foo}]{unused
}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{raises Failure}]{always
}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{returns}]{never
}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{see \href{\#}{\#}\footnote{\url{\#}}}]{this url
}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{see \ocamlinlinecode{foo.\allowbreak{}ml}}]{this file
}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{see Foo}]{this document
}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{since}]{0}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{before 1.0}]{it was in b\textsuperscript{e}t\textsubscript{a}
}\end{description}%
\begin{description}\kern-\topsep
\makeatletter\advance\@topsepadd-\topsep\makeatother% topsep is hardcoded
\item[{version}]{-1}\end{description}%
\label{module-Markup-val-foo}\ocamlcodefragment{\ocamltag{keyword}{val} foo : unit}\begin{ocamlindent}Comments in structure items \bold{support} \emph{markup}, t\textsuperscript{o}\textsubscript{o}.\end{ocamlindent}%
\medbreak
Some modules to support references.
\label{module-Markup-module-X}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Markup-module-X]{\ocamlinlinecode{X}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\end{ocamlindent}%
\ocamlcodefragment{\ocamltag{keyword}{end}}\\
\label{module-Markup-module-Y}\ocamlcodefragment{\ocamltag{keyword}{module} \hyperref[module-Markup-module-Y]{\ocamlinlinecode{Y}}}\ocamlcodefragment{ : \ocamltag{keyword}{sig}}\begin{ocamlindent}\end{ocamlindent}%
\ocamlcodefragment{\ocamltag{keyword}{end}}\\
|
