jon.recoil.org
this repo has no description
1(** Here, we test the rendering of comment markup. *)
2
3
4(** {1 Sections}
5
6 Let's get these done first, because sections will be used to break up the
7 rest of this test.
8
9 Besides the section heading above, there are also
10
11 {2 Subsection headings}
12
13 and
14
15 {3 Sub-subsection headings}
16
17 but odoc has banned deeper headings. There are also title headings, but they
18 are only allowed in mld files.
19
20 {3:anchors Anchors}
21
22 Sections can have attached {!anchors}, and it is possible to {{!anchors}
23 link} to them. Links to section headers should not be set in source code
24 style.
25
26 {4 Paragraph}
27
28 Individual paragraphs can have a heading.
29
30 {5 Subparagraph}
31
32 Parts of a longer paragraph that can be considered alone can also have
33 headings.
34
35
36 {1 Styling}
37
38 This paragraph has some styled elements: {b bold} and {i italic},
39 {b {i bold italic}}, {e emphasis}, {e {e emphasis} within emphasis},
40 {b {i bold italic}}, super{^script}, sub{_script}. The line spacing should
41 be enough for superscripts and subscripts not to look odd.
42
43 Note: {i In italics {e emphasis} is rendered as normal text while {e
44 emphasis {e in} emphasis} is rendered in italics.} {i It also work the same
45 in {{:#} links in italics with {e emphasis {e in} emphasis}.}}
46
47 [code] is a different kind of markup that doesn't allow nested markup.
48
49 It's possible for two markup elements to appear {b next} {i to} each other
50 and have a space, and appear {b next}{i to} each other with no space. It
51 doesn't matter {b how} {i much} space it was in the source: in this
52 sentence, it was two space characters. And in this one, there is {b a}
53 {i newline}.
54
55 This is also true between {e non-}[code] markup {e and} [code].
56
57 Code can appear {b inside [other] markup}. Its display shouldn't be
58 affected.
59
60 There is no differences between [a b] and [a
61 b].
62
63 Consecutive whitespaces not after a newline are conserved as they are: [a b].
64
65 {1 Links and references}
66
67 This is a {{:#} link}. It sends you to the top of this page. Links can have
68 markup inside them: {{:#} {b bold}}, {{:#} {i italics}},
69 {{:#} {e emphasis}}, {{:#} super{^script}}, {{:#} sub{_script}}, and
70 {{:#} [code]}. Links can also be nested {e {{:#} inside}} markup. Links
71 cannot be nested inside each other. This link has no replacement text:
72 {{:#}}. The text is filled in by odoc. This is a shorthand link: {:#}. The
73 text is also filled in by odoc in this case.
74
75 This is a reference to {!foo}. References can have replacement text:
76 {{!foo} the value foo}. Except for the special lookup support, references
77 are pretty much just like links. The replacement text can have nested
78 styles: {{!foo} {b bold}}, {{!foo} {i italic}}, {{!foo} {e emphasis}},
79 {{!foo} super{^script}}, {{!foo} sub{_script}}, and {{!foo} [code]}. It's
80 also possible to surround a reference in a style: {b {!foo}}. References
81 can't be nested inside references, and links and references can't be nested
82 inside each other.
83
84
85 {1 Preformatted text}
86
87 This is a code block:
88
89 {[
90 let foo = ()
91 (** There are some nested comments in here, but an unpaired comment
92 terminator would terminate the whole doc surrounding comment. It's
93 best to keep code blocks no wider than 72 characters. *)
94
95 let bar =
96 ignore foo
97 ]}
98
99 There are also verbatim blocks:
100
101{v
102The main difference is these don't get syntax highlighting.
103v}
104
105
106 {1 Lists}
107
108 - This is a
109 - shorthand bulleted list,
110 - and the paragraphs in each list item support {e styling}.
111
112 + This is a
113 + shorthand numbered list.
114
115 - Shorthand list items can span multiple lines, however trying to put two
116 paragraphs into a shorthand list item using a double line break
117
118 just creates a paragraph outside the list.
119
120 - Similarly, inserting a blank line between two list items
121
122 - creates two separate lists.
123
124 {ul
125 {li To get around this limitation, one
126
127 can use explicitly-delimited lists.}
128 {li This one is bulleted,}}
129
130 {ol {li but there is also the numbered variant.}}
131
132 {ul
133 {li
134 {ul
135 {li lists}
136 {li can be nested}
137 {li and can include references}
138 {li {!foo}}}}}
139
140
141 {1 Unicode}
142
143 The parser supports any ASCII-compatible encoding.
144
145 In particuλar UTF-8.
146
147
148 {1 Raw HTML}
149
150 Raw HTML can be {%html:<input type="text" placeholder="inserted">%} as
151 inline elements into sentences.
152
153 {%html:
154 <blockquote>
155 If the raw HTML is the only thing in a paragraph, it is treated as a block
156 element, and won't be wrapped in paragraph tags by the HTML generator.
157 </blockquote>
158 %}
159
160
161 {1 Math}
162
163 Math elements can be inline: {m \int_{-\infty}^\infty}, or blocks:
164
165 {math
166 % \f is defined as #1f(#2) using the macro
167 \newcommand{\f}[2]{#1f(#2)}
168 \f\relax{x} = \int_{-\infty}^\infty
169 \f\hat\xi\,e^{2 \pi i \xi x}
170 \,d\xi
171 }
172
173
174 {1 Modules}
175
176 {!modules: X}
177 {!modules: X Y}
178
179
180 {1 Tables}
181
182 {t
183 Left | Center | Right | Default
184 :-----|:------:|------:|---------
185 A | B | C | D
186 }
187
188 {t
189 Left | Center | Right | Default
190 :-----|:------:|------:|---------
191 A | B | C | D
192 A much longer paragraph which will need to be wrapped and more content and more content and some different content and we will see what is does if we can see it | B much longer paragraph which will need to be wrapped and more content and more content and some different content and we will see what is does if we can see it | C much longer paragraph which will need to be wrapped and more content and more content and some different content and we will see what is does if we can see it | D much longer paragraph which will need to be wrapped and more content and more content and some different content and we will see what is does if we can see it
193 }
194
195 {t
196 No | Header
197 A | B
198 }
199
200 {table
201 {tr
202 {th Header 1}
203 {th Header 2}
204 }
205 {tr
206 {td Data 1}
207 {td Data 2}
208 }
209 }
210
211 {table
212 {tr
213 {th Header 1}
214 {td Data 1}
215 }
216 {tr
217 {th Header 2}
218 {td Data 2}
219 }
220 }
221
222
223 {1 Tags}
224
225 Each comment can end with zero or more tags. Here are some examples:
226
227 @author antron
228 @deprecated a {e long} time ago
229 @param foo unused
230 @raise Failure always
231 @return never
232 @see <#> this url
233 @see 'foo.ml' this file
234 @see "Foo" this document
235 @since 0
236 @before 1.0 it was in b{^e}t{_a}
237 @version -1 *)
238
239val foo : unit
240(** Comments in structure items {b support} {e markup}, t{^o}{_o}. *)
241
242(** Some modules to support references. *)
243
244module X : sig end
245module Y : sig end