\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{Math\label{math}}%
Math elements can be inline: $\int_{-\infty}^\infty$, or blocks:

\begin{equation*}
    % \f is defined as #1f(#2) using the macro
    \newcommand{\f}[2]{#1f(#2)}
    \f\relax{x} = \int_{-\infty}^\infty
    \f\hat\xi\,e^{2 \pi i \xi x}
    \,d\xi
    
\end{equation*}

\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}}\\


