diff options
| -rw-r--r-- | doc/haddock.sgml | 19 |
1 files changed, 18 insertions, 1 deletions
diff --git a/doc/haddock.sgml b/doc/haddock.sgml index c90e0f01..bfdb78af 100644 --- a/doc/haddock.sgml +++ b/doc/haddock.sgml @@ -889,7 +889,8 @@ module A where <para>Displayed blocks of code are indicated by surrounding a paragraph with <literal>@...@</literal> or by preceding each - line of a paragraph with <literal>></literal>. For + line of a paragraph with <literal>></literal> (we often + call these “bird tracks”). For example:</para> <programlisting> @@ -903,6 +904,12 @@ module A where </programlisting> </section> + <para>There is an important difference between the two forms of + code block: in the bird-track form, the text to the right of the + ‘<literal>></literal>’ is interpreted literally, + whereas the <literal>@...@</literal> form interprets markup as + normal inside the code block.</para> + <section> <title>Hyperlinked Identifiers</title> @@ -935,6 +942,16 @@ module A where (without checking to see whether either <literal>M</literal> or <literal>M.T</literal> exist).</para> + <para>To make life easier for documentation writers, a quoted + identifier is only interpreted as such if the quotes surround + a lexically valid Haskell identifier. This means, for + example, that it normally isn't necessary to escape the single + quote when used as an apostrophe:</para> + +<programlisting> +-- | I don't have to escape my apostrophes; great, isn't it? +</programlisting> + <para>For compatibility with other systems, the following alternative form of markup is accepted<footnote><para> We chose not to use this as the primary markup for |