Adding initial test for the org backend.

6 files changed, 1276 insertions, 0 deletions

diff --git a/org-test/Main.hs b/org-test/Main.hs
new file mode 100644
index 00000000..01658fd9
--- /dev/null
+++ b/org-test/Main.hs
@@ -0,0 +1,35 @@
+{-# LANGUAGE CPP #-}
+
+
+import Data.Function
+import System.Environment
+import System.FilePath
+
+import Test.Haddock
+import Test.Haddock.Utils
+
+
+checkConfig :: CheckConfig String
+checkConfig = CheckConfig
+    { ccfgRead = Just
+    , ccfgClean = const id
+    , ccfgDump = id
+    , ccfgEqual = (==)
+    }
+
+
+dirConfig :: DirConfig
+dirConfig = (defaultDirConfig $ takeDirectory __FILE__)
+  { dcfgCheckIgnore = checkIgnore
+  }
+
+
+main :: IO ()
+main = do
+    cfg <- parseArgs checkConfig dirConfig =<< getArgs
+    runAndCheck $ cfg
+        { cfgHaddockArgs = cfgHaddockArgs cfg ++ ["--org"]
+        }
+
+checkIgnore :: FilePath -> Bool
+checkIgnore file = takeExtension file /= ".org"
diff --git a/org-test/ref/main.org b/org-test/ref/main.org
new file mode 100644
index 00000000..e4b2b830
--- /dev/null
+++ b/org-test/ref/main.org
@@ -0,0 +1,764 @@
+* 
+  :PROPERTIES:
+  :CUSTOM_ID: main
+  :Hackage: https://hackage.haskell.org/package/main
+  :END:
+
+
+
+** Test
+   :PROPERTIES:
+   :CUSTOM_ID: main.Test
+   :Hackage: https://hackage.haskell.org/package/main/docs/Test.html
+   :END:
+
+This module illustrates & tests most of the features of Haddock. Testing references from the description: [[#main.Test.T][T]], [[#main.Test.f][f]], [[#main.Test.g][g]], [[#main.Visible.visible][visible]].
+
+*** Type declarations
+
+**** Data types
+
+***** data T a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.T
+      :CUSTOM_ID: Test.T
+      :END:
+
+This comment applies to the /following/ declaration and it continues until the next non-comment line
+
+****** A [[#base.Data.Int.Int][Int]] ([[#base.Data.Maybe.Maybe][Maybe]] [[#base.Prelude.Float][Float]])
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.A:dc
+       :CUSTOM_ID: Test.A:dc
+       :END:
+
+This comment describes the [[#main.Test.A:dc][A]] constructor
+
+****** B ([[#main.Test.T][T]] a b, [[#main.Test.T][T]] [[#base.Data.Int.Int][Int]] [[#base.Prelude.Float][Float]])
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.B:dc
+       :CUSTOM_ID: Test.B:dc
+       :END:
+
+This comment describes the [[#main.Test.B:dc][B]] constructor
+
+***** data T2 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.T2
+      :CUSTOM_ID: Test.T2
+      :END:
+
+An abstract data declaration
+
+***** data T3 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.T3
+      :CUSTOM_ID: Test.T3
+      :END:
+
+A data declaration with no documentation annotations on the constructors
+
+****** A1 a
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.A1:dc
+       :CUSTOM_ID: Test.A1:dc
+       :END:
+
+****** B1 b
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.B1:dc
+       :CUSTOM_ID: Test.B1:dc
+       :END:
+
+***** data T4 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.T4
+      :CUSTOM_ID: Test.T4
+      :END:
+
+****** A2 a
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.A2:dc
+       :CUSTOM_ID: Test.A2:dc
+       :END:
+
+****** B2 b
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.B2:dc
+       :CUSTOM_ID: Test.B2:dc
+       :END:
+
+***** data T5 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.T5
+      :CUSTOM_ID: Test.T5
+      :END:
+
+****** A3 a
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.A3:dc
+       :CUSTOM_ID: Test.A3:dc
+       :END:
+
+documents [[#main.Test.A3:dc][A3]]
+
+****** B3 b
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.B3:dc
+       :CUSTOM_ID: Test.B3:dc
+       :END:
+
+documents [[#main.Test.B3:dc][B3]]
+
+***** data T6
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.T6
+      :CUSTOM_ID: Test.T6
+      :END:
+
+Testing alternative comment styles
+
+****** A4
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.A4:dc
+       :CUSTOM_ID: Test.A4:dc
+       :END:
+
+This is the doc for [[#main.Test.A4:dc][A4]]
+
+****** B4
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.B4:dc
+       :CUSTOM_ID: Test.B4:dc
+       :END:
+
+This is the doc for [[#main.Test.B4:dc][B4]]
+
+****** C4
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.C4:dc
+       :CUSTOM_ID: Test.C4:dc
+       :END:
+
+This is the doc for [[#main.Test.C4:dc][C4]]
+
+***** newtype N1 a
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.N1
+      :CUSTOM_ID: Test.N1
+      :END:
+
+A newtype
+
+****** N1 a
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.N1:dc
+       :CUSTOM_ID: Test.N1:dc
+       :END:
+
+***** newtype N2 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.N2
+      :CUSTOM_ID: Test.N2
+      :END:
+
+A newtype with a fieldname
+
+****** N2 {
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.N2:dc
+       :CUSTOM_ID: Test.N2:dc
+       :END:
+
+******* n :: a b
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.n
+        :CUSTOM_ID: Test.n
+        :END:
+
+***** newtype N3 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.N3
+      :CUSTOM_ID: Test.N3
+      :END:
+
+A newtype with a fieldname, documentation on the field
+
+****** N3 {
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.N3:dc
+       :CUSTOM_ID: Test.N3:dc
+       :END:
+
+******* n3 :: a b
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.n3
+        :CUSTOM_ID: Test.n3
+        :END:
+
+this is the [[#main.Test.n3][n3]] field
+
+***** data N4 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.N4
+      :CUSTOM_ID: Test.N4
+      :END:
+
+An abstract newtype - we show this one as data rather than newtype because the difference isn't visible to the programmer for an abstract type.
+
+***** newtype N5 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.N5
+      :CUSTOM_ID: Test.N5
+      :END:
+
+****** N5 {
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.N5:dc
+       :CUSTOM_ID: Test.N5:dc
+       :END:
+
+******* n5 :: a b
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.n5
+        :CUSTOM_ID: Test.n5
+        :END:
+
+no docs on the datatype or the constructor
+
+***** newtype N6 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.N6
+      :CUSTOM_ID: Test.N6
+      :END:
+
+****** N6 {
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.N6:dc
+       :CUSTOM_ID: Test.N6:dc
+       :END:
+
+docs on the constructor only
+
+******* n6 :: a b
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.n6
+        :CUSTOM_ID: Test.n6
+        :END:
+
+***** newtype N7 a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.N7
+      :CUSTOM_ID: Test.N7
+      :END:
+
+docs on the newtype and the constructor
+
+****** N7 {
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.N7:dc
+       :CUSTOM_ID: Test.N7:dc
+       :END:
+
+The [[#main.Test.N7][N7]] constructor
+
+******* n7 :: a b
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.n7
+        :CUSTOM_ID: Test.n7
+        :END:
+
+**** Records
+
+***** data R
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.R
+      :CUSTOM_ID: Test.R
+      :END:
+
+This is the documentation for the [[#main.Test.R][R]] record, which has four fields, [[#main.Test.p][p]], [[#main.Test.q][q]], [[#main.Test.r][r]], and [[#main.Test.s][s]].
+
+****** C1 {
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.C1:dc
+       :CUSTOM_ID: Test.C1:dc
+       :END:
+
+This is the [[#main.Test.C1:dc][C1]] record constructor, with the following fields:
+
+******* p :: [[#base.Data.Int.Int][Int]]
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.p
+        :CUSTOM_ID: Test.p
+        :END:
+
+This comment applies to the [[#main.Test.p][p]] field
+
+******* q :: forall a. a -> a
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.q
+        :CUSTOM_ID: Test.q
+        :END:
+
+This comment applies to the [[#main.Test.q][q]] field
+
+******* r, s :: [[#base.Data.Int.Int][Int]]
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.r
+        :CUSTOM_ID: Test.r
+        :CUSTOM_ID: main.Test.s
+        :CUSTOM_ID: Test.s
+        :END:
+
+This comment applies to both [[#main.Test.r][r]] and [[#main.Test.s][s]]
+
+****** C2 {
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.C2:dc
+       :CUSTOM_ID: Test.C2:dc
+       :END:
+
+This is the [[#main.Test.C2:dc][C2]] record constructor, also with some fields:
+
+******* t :: [[#main.Test.T1][T1]] -> ([[#main.Test.T2][T2]] [[#base.Data.Int.Int][Int]] [[#base.Data.Int.Int][Int]]) -> ([[#main.Test.T3][T3]] [[#base.Data.Bool.Bool][Bool]] [[#base.Data.Bool.Bool][Bool]]) -> ([[#main.Test.T4][T4]] [[#base.Prelude.Float][Float]] [[#base.Prelude.Float][Float]]) -> [[#main.Test.T5][T5]] () ()
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.t
+        :CUSTOM_ID: Test.t
+        :END:
+
+******* u, v :: [[#base.Data.Int.Int][Int]]
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.u
+        :CUSTOM_ID: Test.u
+        :CUSTOM_ID: main.Test.v
+        :CUSTOM_ID: Test.v
+        :END:
+
+***** data R1
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.R1
+      :CUSTOM_ID: Test.R1
+      :END:
+
+Testing different record commenting styles
+
+****** C3 {
+       :PROPERTIES:
+       :CUSTOM_ID: main.Test.C3:dc
+       :CUSTOM_ID: Test.C3:dc
+       :END:
+
+This is the [[#main.Test.C3:dc][C3]] record constructor
+
+******* s1 :: [[#base.Data.Int.Int][Int]]
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.s1
+        :CUSTOM_ID: Test.s1
+        :END:
+
+The [[#main.Test.s1][s1]] record selector
+
+******* s2 :: [[#base.Data.Int.Int][Int]]
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.s2
+        :CUSTOM_ID: Test.s2
+        :END:
+
+The [[#main.Test.s2][s2]] record selector
+
+******* s3 :: [[#base.Data.Int.Int][Int]]
+        :PROPERTIES:
+        :CUSTOM_ID: main.Test.s3
+        :CUSTOM_ID: Test.s3
+        :END:
+
+The [[#main.Test.s3][s3]] record selector
+
+test that we can export record selectors on their own:
+
+***** p :: [[#main.Test.R][R]] -> [[#base.Data.Int.Int][Int]]
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.p
+      :CUSTOM_ID: Test.p
+      :END:
+
+This comment applies to the [[#main.Test.p][p]] field
+
+***** q :: [[#main.Test.R][R]] -> forall a. a -> a
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.q
+      :CUSTOM_ID: Test.q
+      :END:
+
+This comment applies to the [[#main.Test.q][q]] field
+
+***** u :: [[#main.Test.R][R]] -> [[#base.Data.Int.Int][Int]]
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.u
+      :CUSTOM_ID: Test.u
+      :END:
+
+*** Class declarations
+
+**** class ([[#main.Test.D][D]] a) => C a
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.C
+     :CUSTOM_ID: Test.C
+     :END:
+
+This comment applies to the /previous/ declaration (the [[#main.Test.C][C]] class)
+
+***** a :: [[#base.System.IO.IO][IO]] a
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.a
+      :CUSTOM_ID: Test.a
+      :END:
+
+this is a description of the [[#main.Test.a][a]] method
+
+***** b :: [a]
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.b
+      :CUSTOM_ID: Test.b
+      :END:
+
+this is a description of the [[#main.Test.b][b]] method
+
+**** class D a
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.D
+     :CUSTOM_ID: Test.D
+     :END:
+
+This is a class declaration with no separate docs for the methods
+
+***** d :: [[#main.Test.T][T]] a b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.d
+      :CUSTOM_ID: Test.d
+      :END:
+
+***** e :: (a, a)
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.e
+      :CUSTOM_ID: Test.e
+      :END:
+
+***** Instances:
+
+- [[#main.Test.D][D]] [[#base.Prelude.Float][Float]]
+- [[#main.Test.D][D]] [[#base.Data.Int.Int][Int]]
+
+**** class E a
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.E
+     :CUSTOM_ID: Test.E
+     :END:
+
+This is a class declaration with no methods (or no methods exported)
+
+**** class F a
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.F
+     :CUSTOM_ID: Test.F
+     :END:
+
+***** ff :: a
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.ff
+      :CUSTOM_ID: Test.ff
+      :END:
+
+Test that we can export a class method on its own:
+
+**** a :: [[#main.Test.C][C]] a => [[#base.System.IO.IO][IO]] a
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.a
+     :CUSTOM_ID: Test.a
+     :END:
+
+this is a description of the [[#main.Test.a][a]] method
+
+*** Function types
+
+**** f :: [[#main.Test.C][C]] a => a -> [[#base.Data.Int.Int][Int]]
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.f
+     :CUSTOM_ID: Test.f
+     :END:
+
+In a comment string we can refer to identifiers in scope with single quotes like this: [[#main.Test.T][T]], and we can refer to modules by using double quotes: [[Foo]].  We can add emphasis /like this/.
+
+- This is a bulleted list
+- This is the next item (different kind of bullet)
+
+1. This is an ordered list
+2. This is the next item (different kind of bullet)
+
+- cat :: a small, furry, domesticated mammal
+- pineapple :: a fruit grown in the tropics
+
+#+begin_src haskell
+     This is a block of code, which can include other markup: R
+     formatting
+               is
+                 significant
+#+end_src
+
+#+begin_src haskell
+this is another block of code
+#+end_src
+
+We can also include URLs in documentation: [[http://www.haskell.org/]].
+
+**** g :: [[#base.Data.Int.Int][Int]] -> [[#base.System.IO.IO][IO]] [[#main.Test.CInt][CInt]]
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.g
+     :CUSTOM_ID: Test.g
+     :END:
+
+we can export foreign declarations too
+
+*** Auxiliary stuff
+
+This is some documentation that is attached to a name ($aux1) rather than a source declaration.  The documentation may be referred to in the export list using its name.
+
+#+begin_src haskell
+ code block in named doc
+#+end_src
+
+This is some documentation that is attached to a name ($aux2)
+
+#+begin_src haskell
+ code block on its own in named doc
+#+end_src
+
+#+begin_src haskell
+ code block on its own in named doc (after newline)
+#+end_src
+
+a nested, named doc comment
+
+with a paragraph,
+
+#+begin_src haskell
+ and a code block
+#+end_src
+
+#+begin_src haskell
+test
+test1
+#+end_src
+
+#+begin_src haskell
+ test2
+  test3
+#+end_src
+
+#+begin_src haskell
+test1
+test2
+#+end_src
+
+#+begin_src haskell
+test3
+test4
+#+end_src
+
+#+begin_src haskell
+test1
+test2
+#+end_src
+
+#+begin_src haskell
+test3
+test4
+#+end_src
+
+#+begin_src haskell
+test3
+test4
+#+end_src
+
+#+begin_src haskell
+test1
+test2
+#+end_src
+
+aux11:
+
+#+begin_src haskell
+test3
+test4
+#+end_src
+
+#+begin_src haskell
+test1
+test2
+#+end_src
+
+#+begin_src haskell
+foo
+#+end_src
+
+#+begin_src haskell
+bar
+#+end_src
+
+This is some inline documentation in the export list
+
+#+begin_src haskell
+a code block using bird-tracks
+each line must begin with > (which isn't significant unless it
+is at the beginning of the line).
+#+end_src
+
+*** A hidden module
+
+**** hidden :: [[#base.Data.Int.Int][Int]] -> [[#base.Data.Int.Int][Int]]
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.hidden
+     :CUSTOM_ID: Test.hidden
+     :END:
+
+*** A visible module
+
+**** module [[Visible]]
+
+nested-style doc comments 
+
+*** Existential / Universal types
+
+**** data Ex a
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.Ex
+     :CUSTOM_ID: Test.Ex
+     :END:
+
+A data-type using existential/universal types
+
+***** forall b. [[#main.Test.C][C]] b => Ex1 b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.Ex1:dc
+      :CUSTOM_ID: Test.Ex1:dc
+      :END:
+
+***** forall b. Ex2 b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.Ex2:dc
+      :CUSTOM_ID: Test.Ex2:dc
+      :END:
+
+***** forall b. [[#main.Test.C][C]] a => Ex3 b
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.Ex3:dc
+      :CUSTOM_ID: Test.Ex3:dc
+      :END:
+
+***** Ex4 (forall a. a -> a)
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.Ex4:dc
+      :CUSTOM_ID: Test.Ex4:dc
+      :END:
+
+*** Type signatures with argument docs
+
+**** k :: [[#main.Test.T][T]] () () -> [[#main.Test.T2][T2]] [[#base.Data.Int.Int][Int]] [[#base.Data.Int.Int][Int]] -> ([[#main.Test.T3][T3]] [[#base.Data.Bool.Bool][Bool]] [[#base.Data.Bool.Bool][Bool]] -> [[#main.Test.T4][T4]] [[#base.Prelude.Float][Float]] [[#base.Prelude.Float][Float]]) -> [[#main.Test.T5][T5]] () () -> [[#base.System.IO.IO][IO]] ()
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.k
+     :CUSTOM_ID: Test.k
+     :END:
+
+Arguments:
+
+- [[#main.Test.T][T]] () () :: This argument has type [[#main.Test.T][T]]
+- ([[#main.Test.T2][T2]] [[#base.Data.Int.Int][Int]] [[#base.Data.Int.Int][Int]]) :: This argument has type 'T2 Int Int'
+- ([[#main.Test.T3][T3]] [[#base.Data.Bool.Bool][Bool]] [[#base.Data.Bool.Bool][Bool]] -> [[#main.Test.T4][T4]] [[#base.Prelude.Float][Float]] [[#base.Prelude.Float][Float]]) :: This argument has type ~T3 Bool Bool -> T4 Float Float~
+- [[#main.Test.T5][T5]] () () :: This argument has a very long description that should hopefully cause some wrapping to happen when it is finally rendered by Haddock in the generated HTML page.
+- [[#base.System.IO.IO][IO]] () :: This is the result type
+
+This is a function with documentation for each argument
+
+**** l :: ([[#base.Data.Int.Int][Int]], [[#base.Data.Int.Int][Int]], [[#base.Prelude.Float][Float]]) -> [[#base.Data.Int.Int][Int]]
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.l
+     :CUSTOM_ID: Test.l
+     :END:
+
+Arguments:
+
+- ([[#base.Data.Int.Int][Int]], [[#base.Data.Int.Int][Int]], [[#base.Prelude.Float][Float]]) :: takes a triple
+- [[#base.Data.Int.Int][Int]] :: returns an [[#base.Data.Int.Int][Int]]
+
+**** m :: [[#main.Test.R][R]] -> [[#main.Test.N1][N1]] () -> [[#base.System.IO.IO][IO]] [[#base.Data.Int.Int][Int]]
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.m
+     :CUSTOM_ID: Test.m
+     :END:
+
+Arguments:
+
+- [[#main.Test.R][R]] :: 
+- [[#main.Test.N1][N1]] () :: one of the arguments
+- [[#base.System.IO.IO][IO]] [[#base.Data.Int.Int][Int]] :: and the return value
+
+This function has some arg docs
+
+**** o :: [[#base.Prelude.Float][Float]] -> [[#base.System.IO.IO][IO]] [[#base.Prelude.Float][Float]]
+     :PROPERTIES:
+     :CUSTOM_ID: main.Test.o
+     :CUSTOM_ID: Test.o
+     :END:
+
+Arguments (in order):
+
+1. The input float
+2. The output float
+
+A foreign import with argument docs
+
+*** A section
+
+**** A subsection
+
+#+begin_src haskell
+a literal line
+#+end_src
+
+$ a non /literal/ line $
+
+***** f' :: [[#base.Data.Int.Int][Int]]
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.f'
+      :CUSTOM_ID: Test.f'
+      :END:
+
+a function with a prime can be referred to as [[#main.Test.f'][f']] but f' doesn't get link'd 'f''
+
+***** withType :: [[#base.Data.Int.Int][Int]]
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.withType
+      :CUSTOM_ID: Test.withType
+      :END:
+
+Comment on a definition with type signature
+
+***** withoutType :: a
+      :PROPERTIES:
+      :CUSTOM_ID: main.Test.withoutType
+      :CUSTOM_ID: Test.withoutType
+      :END:
+
+Comment on a definition without type signature
+
+** Visible
+   :PROPERTIES:
+   :CUSTOM_ID: main.Visible
+   :Hackage: https://hackage.haskell.org/package/main/docs/Visible.html
+   :END:
+
+*** visible :: [[#base.Data.Int.Int][Int]] -> [[#base.Data.Int.Int][Int]]
+    :PROPERTIES:
+    :CUSTOM_ID: main.Visible.visible
+    :CUSTOM_ID: Visible.visible
+    :END:
diff --git a/org-test/run b/org-test/run
new file mode 100644
index 00000000..3e72be80
--- /dev/null
+++ b/org-test/run
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+export HADDOCK_PATH=$(which haddock)
+LIB_PATH="$(dirname "$BASH_SOURCE")/../haddock-test/src/"
+MAIN_PATH="$(dirname "$BASH_SOURCE")/Main.hs"
+runhaskell -i:"$LIB_PATH" $MAIN_PATH $@
diff --git a/org-test/src/Hidden.hs b/org-test/src/Hidden.hs
new file mode 100644
index 00000000..2b694e86
--- /dev/null
+++ b/org-test/src/Hidden.hs
@@ -0,0 +1,7 @@
+{-# LANGUAGE Haskell2010 #-}
+{-# OPTIONS_HADDOCK hide #-}
+
+module Hidden where
+
+hidden :: Int -> Int
+hidden a = a
diff --git a/org-test/src/Test.hs b/org-test/src/Test.hs
new file mode 100644
index 00000000..d5632bfa
--- /dev/null
+++ b/org-test/src/Test.hs
@@ -0,0 +1,460 @@
+{-# LANGUAGE Haskell2010 #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module      :  Test
+-- Copyright   :  (c) Simon Marlow 2002
+-- License     :  BSD-style
+--
+-- Maintainer  :  libraries@haskell.org
+-- Stability   :  provisional
+-- Portability :  portable
+--
+-- This module illustrates & tests most of the features of Haddock.
+-- Testing references from the description: 'T', 'f', 'g', 'Visible.visible'.
+--
+-----------------------------------------------------------------------------
+
+-- This is plain comment, ignored by Haddock.
+{-# LANGUAGE Rank2Types, GADTs #-}
+module Test
+  (
+
+        -- Section headings are introduced with '-- *':
+        -- * Type declarations
+
+        -- Subsection headings are introduced with '-- **' and so on.
+        -- ** Data types
+    T(..)
+  , T2
+  , T3(..)
+  , T4(..)
+  , T5(..)
+  , T6(..)
+  , N1(..)
+  , N2(..)
+  , N3(..)
+  , N4
+  , N5(..)
+  , N6(..)
+  , N7(..)
+  ,
+
+        -- ** Records
+    R(..)
+  , R1(..)
+  ,
+
+        -- | test that we can export record selectors on their own:
+    p
+  , q
+  , u
+  ,
+
+        -- * Class declarations
+    C(a, b)
+  , D(..)
+  , E
+  , F(..)
+  ,
+
+        -- | Test that we can export a class method on its own:
+    a
+  ,
+
+        -- * Function types
+    f
+  , g
+  ,
+
+        -- * Auxiliary stuff
+
+        -- $aux1
+
+        -- $aux2
+
+        -- $aux3
+
+        -- $aux4
+
+        -- $aux5
+
+        -- $aux6
+
+        -- $aux7
+
+        -- $aux8
+
+        -- $aux9
+
+        -- $aux10
+
+        -- $aux11
+
+        -- $aux12
+
+        -- | This is some inline documentation in the export list
+        --
+        -- > a code block using bird-tracks
+        -- > each line must begin with > (which isn't significant unless it
+        -- > is at the beginning of the line).
+
+        -- * A hidden module
+    module Hidden
+  ,
+
+        -- * A visible module
+    module Visible
+  ,
+
+        {-| nested-style doc comments -}
+
+        -- * Existential \/ Universal types
+    Ex(..)
+  ,
+
+        -- * Type signatures with argument docs
+    k
+  , l
+  , m
+  , o
+  ,
+
+        -- * A section
+        -- and without an intervening comma:
+        -- ** A subsection
+
+{-|
+ > a literal line
+
+ $ a non /literal/ line $
+-}
+    f'
+  , withType
+  , withoutType
+  ) where
+
+import           Data.Maybe
+import           Hidden
+import           Visible
+
+bla = Nothing
+
+-- | This comment applies to the /following/ declaration
+-- and it continues until the next non-comment line
+data T a b
+ = A Int (Maybe Float) -- ^ This comment describes the 'A' constructor
+ | -- | This comment describes the 'B' constructor
+   B (T a b, T Int Float) -- ^
+
+-- | An abstract data declaration
+data T2 a b = T2 a b
+
+-- | A data declaration with no documentation annotations on the constructors
+data T3 a b = A1 a | B1 b
+
+-- A data declaration with no documentation annotations at all
+data T4 a b = A2 a | B2 b
+
+-- A data declaration documentation on the constructors only
+data T5 a b
+  = A3 a -- ^ documents 'A3'
+  | B3 b -- ^ documents 'B3'
+
+-- | Testing alternative comment styles
+data T6
+  -- | This is the doc for 'A4'
+  = A4
+  | B4
+  | -- ^ This is the doc for 'B4'
+
+    -- | This is the doc for 'C4'
+    C4
+
+-- | A newtype
+newtype N1 a = N1 a
+
+-- | A newtype with a fieldname
+newtype N2 a b = N2 {n :: a b}
+
+-- | A newtype with a fieldname, documentation on the field
+newtype N3 a b = N3 {n3 :: a b -- ^ this is the 'n3' field
+                    }
+
+-- | An abstract newtype - we show this one as data rather than newtype because
+-- the difference isn\'t visible to the programmer for an abstract type.
+newtype N4 a b = N4 a
+
+newtype N5 a b = N5 {n5 :: a b -- ^ no docs on the datatype or the constructor
+                    }
+
+newtype N6 a b = N6 {n6 :: a b
+                    }
+                 -- ^ docs on the constructor only
+
+-- | docs on the newtype and the constructor
+newtype N7 a b = N7 {n7 :: a b
+                    }
+                -- ^ The 'N7' constructor
+
+
+class (D a) => C a  where
+   -- |this is a description of the 'a' method
+   a :: IO a
+   b :: [a]
+   -- ^ this is a description of the 'b' method
+   c :: a -- c is hidden in the export list
+   c = undefined
+
+-- ^ This comment applies to the /previous/ declaration (the 'C' class)
+
+class D a where
+   d :: T a b
+   e :: (a,a)
+-- ^ This is a class declaration with no separate docs for the methods
+
+instance D Int where
+  d = undefined
+  e = undefined
+
+-- instance with a qualified class name
+instance Test.D Float where
+  d = undefined
+  e = undefined
+
+class E a where
+  ee :: a
+-- ^ This is a class declaration with no methods (or no methods exported)
+
+-- This is a class declaration with no documentation at all
+class F a where
+  ff :: a
+
+-- | This is the documentation for the 'R' record, which has four fields,
+-- 'p', 'q', 'r', and 's'.
+data R =
+  -- | This is the 'C1' record constructor, with the following fields:
+  C1 { p :: Int -- ^ This comment applies to the 'p' field
+     , q :: forall a . a->a  -- ^ This comment applies to the 'q' field
+     , -- | This comment applies to both 'r' and 's'
+       r,s :: Int
+     }
+  | C2 { t :: T1 -> (T2 Int Int)-> (T3 Bool Bool) -> (T4 Float Float) -> T5 () (),
+       u,v :: Int
+     }
+  -- ^ This is the 'C2' record constructor, also with some fields:
+
+-- | Testing different record commenting styles
+data R1
+  -- | This is the 'C3' record constructor
+        = C3
+  {
+              -- | The 's1' record selector
+    s1 :: Int
+              -- | The 's2' record selector
+  , s2 :: Int
+  , s3 :: Int  -- NOTE: In the original examples/Test.hs in Haddock, there is an extra "," here.
+                           -- Since GHC doesn't allow that, I have removed it in this file.
+              -- ^ The 's3' record selector
+  }
+
+-- These section headers are only used when there is no export list to
+-- give the structure of the documentation:
+
+-- * This is a section header (level 1)
+-- ** This is a section header (level 2)
+-- *** This is a section header (level 3)
+
+{-|
+In a comment string we can refer to identifiers in scope with
+single quotes like this: 'T', and we can refer to modules by
+using double quotes: "Foo".  We can add emphasis /like this/.
+
+   * This is a bulleted list
+
+   - This is the next item (different kind of bullet)
+
+   (1) This is an ordered list
+
+   2. This is the next item (different kind of bullet)
+
+   [cat] a small, furry, domesticated mammal
+
+   [pineapple] a fruit grown in the tropics
+
+@
+     This is a block of code, which can include other markup: 'R'
+     formatting
+               is
+                 significant
+@
+
+> this is another block of code
+
+We can also include URLs in documentation: <http://www.haskell.org/>.
+-}
+
+f :: C a => a -> Int
+
+-- | we can export foreign declarations too
+foreign import ccall g :: Int -> IO CInt
+
+-- | this doc string has a parse error in it: \'
+h :: Int
+h = 42
+
+
+-- $aux1 This is some documentation that is attached to a name ($aux1)
+-- rather than a source declaration.  The documentation may be
+-- referred to in the export list using its name.
+--
+-- @ code block in named doc @
+
+-- $aux2 This is some documentation that is attached to a name ($aux2)
+
+-- $aux3
+-- @ code block on its own in named doc @
+
+-- $aux4
+--
+-- @ code block on its own in named doc (after newline) @
+
+{- $aux5 a nested, named doc comment
+
+   with a paragraph,
+
+   @ and a code block @
+-}
+
+-- some tests for various arrangements of code blocks:
+
+{- $aux6
+>test
+>test1
+
+@ test2
+  test3
+@
+-}
+
+{- $aux7
+@
+test1
+test2
+@
+-}
+
+{- $aux8
+>test3
+>test4
+-}
+
+{- $aux9
+@
+test1
+test2
+@
+
+>test3
+>test4
+-}
+
+{- $aux10
+>test3
+>test4
+
+@
+test1
+test2
+@
+-}
+
+-- This one is currently wrong (Haddock 0.4).  The @...@ part is
+-- interpreted as part of the bird-tracked code block.
+{- $aux11
+aux11:
+
+>test3
+>test4
+
+@
+test1
+test2
+@
+-}
+
+-- $aux12
+-- > foo
+--
+-- > bar
+--
+
+-- | A data-type using existential\/universal types
+data Ex a
+  = forall b . C b => Ex1 b
+  | forall b . Ex2 b
+  | forall b . C a => Ex3 b -- NOTE: I have added "forall b" here make GHC accept this file
+  | Ex4 (forall a . a -> a)
+
+-- | This is a function with documentation for each argument
+k
+  :: T () ()      -- ^ This argument has type 'T'
+  -> (T2 Int Int) -- ^ This argument has type 'T2 Int Int'
+  -> (T3 Bool Bool -> T4 Float Float) -- ^ This argument has type @T3 Bool Bool -> T4 Float Float@
+  -> T5 () ()     -- ^ This argument has a very long description that should
+                  -- hopefully cause some wrapping to happen when it is finally
+                  -- rendered by Haddock in the generated HTML page.
+  -> IO ()        -- ^ This is the result type
+
+-- This function has arg docs but no docs for the function itself
+l
+  :: (Int, Int, Float) -- ^ takes a triple
+  -> Int -- ^ returns an 'Int'
+
+-- | This function has some arg docs
+m
+  :: R
+  -> N1 ()      -- ^ one of the arguments
+  -> IO Int     -- ^ and the return value
+
+-- | This function has some arg docs but not a return value doc
+
+-- can't use the original name ('n') with GHC
+newn
+  :: R               -- ^ one of the arguments, an 'R'
+  -> N1 ()           -- ^ one of the arguments
+  -> IO Int
+newn = undefined
+
+
+-- | A foreign import with argument docs
+foreign import ccall unsafe
+ o :: Float  -- ^ The input float
+   -> IO Float  -- ^ The output float
+
+-- | We should be able to escape this: \#\#\#
+
+-- p :: Int
+-- can't use the above original definition with GHC
+newp :: Int
+newp = undefined
+
+-- | a function with a prime can be referred to as 'f''
+-- but f' doesn't get link'd 'f\''
+f' :: Int
+
+-- | Comment on a definition without type signature
+withoutType = undefined
+
+-- | Comment on a definition with type signature
+withType :: Int
+withType = 1
+
+-- Add some definitions here so that this file can be compiled with GHC
+
+data T1
+f = undefined
+f' = undefined
+type CInt = Int
+k = undefined
+l = undefined
+m = undefined
diff --git a/org-test/src/Visible.hs b/org-test/src/Visible.hs
new file mode 100644
index 00000000..9440aeef
--- /dev/null
+++ b/org-test/src/Visible.hs
@@ -0,0 +1,4 @@
+{-# LANGUAGE Haskell2010 #-}
+module Visible where
+visible :: Int -> Int
+visible a = a