[haddock @ 2002-05-29 13:38:51 by simonmar]

Document recent changes to markup syntax

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>&gt;</literal>.  For
+	line of a paragraph with <literal>&gt;</literal> (we often
+	call these &ldquo;bird tracks&rdquo;).  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
+      &lsquo;<literal>></literal>&rsquo; 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