From cdb697bffbae507d8b465817ac4c380e5f0147b8 Mon Sep 17 00:00:00 2001
From: simonmar <unknown>
Date: Thu, 8 Jan 2004 10:14:24 +0000
Subject: [haddock @ 2004-01-08 10:14:24 by simonmar] Add instructions for
 using GHC to pre-process source for feeding to Haddock.

---
 doc/haddock.sgml | 37 +++++++++++++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 4 deletions(-)

(limited to 'doc/haddock.sgml')

diff --git a/doc/haddock.sgml b/doc/haddock.sgml
index 7d76bcd8..1539126b 100644
--- a/doc/haddock.sgml
+++ b/doc/haddock.sgml
@@ -207,10 +207,14 @@
     </cmdsynopsis>
 
     <para>Where each <replaceable>file</replaceable> is a filename
-    containing a Haskell source module.  All the modules specified on
-    the command line will be processed together.  When one module
-    refers to an entity in another module being processed, the
-    documentation will link directly to that entity.</para>
+    containing a Haskell source module.  Only plain Haskell source
+    files are accepted (but see <xref linkend="cpp"> for instructions
+    on how to pre-process source files for feeding to Haddock).</para>
+
+    <para>All the modules specified on the command line will be
+    processed together.  When one module refers to an entity in
+    another module being processed, the documentation will link
+    directly to that entity.</para>
 
     <para>Entities that cannot be found, for example because they are
     in a module that isn't being processed as part of the current
@@ -534,6 +538,31 @@
       </varlistentry>
     </variablelist>
 
+    <section id="cpp">
+      <title>Using literate or pre-processed source</title>
+
+      <para>Haddock only accepts plain, non-literate, Haskell source.
+      This means that if you program in Literate Haskell, or you need
+      to use the C pre-processor in your Haskell source, then you need
+      to pre-process the files before feeding them to Haddock.  This
+      is easily accomplished using GHC; for example, suppose we have a
+      Literate Haskell source file <filename>Foo.lhs</filename>, on
+      which we also need to run the C pre-processor:</para>
+
+<screen>
+$ ghc -cpp -E -D__HADDOCK__ Foo.lhs -o Foo.hs
+$ haddock -h Foo.hs ...
+</screen>
+
+      <para>The <option>-E</option> option to GHC says "stop after
+      pre-processing", the <option>-cpp</option> turns on the C
+      pre-processor, and the <option>-D__HADDOCK__</option> option
+      defines the symbol <literal>__HADDOCK__</literal> when
+      pre-processing (this is sometimes handy if you need to
+      any pre-processing conditionals in your source which depend on
+      whether the source is going to be fed to Haddock).</para>
+    </section>
+
   </chapter>
   
   <chapter id="markup">
-- 
cgit v1.2.3