1 files changed, 142 insertions, 0 deletions
diff --git a/haddock-api/README.org b/haddock-api/README.org
new file mode 100644
index 00000000..3bd64d32
--- /dev/null
+++ b/haddock-api/README.org
@@ -0,0 +1,142 @@
+* haddorg-api
+
+*NOTE*. This is the README file to ~haddorg-api~.  For the README file
+to haddock, see README.md.
+
+** Overview
+
+Haddock is a documentation generator for Haskell libraries and it
+supports several backends including HTML, latex and hoogle.  The
+program logic of the ~haddock~ tool is the ~haddock-api~ package.
+
+~haddorg-api~ adds an org backend of ~haddock-api~, so that one can
+invoke haddock to generate org files, of the Org Mode.
+
+** Examples
+
+- [[https://ypei.org/assets/haddorg-output/base-4.16.1.0.org.gz][base-4.16.1.0.org]]
+- [[https://ypei.org/assets/haddorg-output/ghc-lib-parser-9.2.2.20220307.org.gz][ghc-lib-parser-9.2.2.20220307.org]], which can be used as a fake ghc
+  for cross-package linking
+- lens
+- [[https://ypei.org/assets/haddorg-output/haddorg-api-2.26.1.org.gz][haddorg-api-2.26.1.org]], also in this repository
+- [[https://ypei.org/assets/haddorg-output/haddock-library-2.26.1.org.gz][haddock-library-2.26.1.org]]
+- [[https://ypei.org/assets/haddorg-output/haddorg-ghc-base.org.gz][haddorg-api + haddock-library + fake ghc + base]], demonstrating
+  cross-package linking
+- [[https://ypei.org/assets/haddorg-output/fsd-sqlite-simple-debian.org.gz][fsd + sqlite-simple + debian]], to demonstrating cross-package linking
+- and [[https://ypei.org/assets/haddorg-output/][more...]]
+
+** Install
+
+#+begin_src sh
+git clone https://g.ypei.me/haddock.git
+cd haddock
+cabal install
+#+end_src
+
+This will create a haddock binary under ~$HOME/.cabal/bin~ - make sure
+it is in your PATH.
+
+To make cabal use the haddock built with ~haddorg-api~, modify the
+~haddock-ghc-x.y.z~ shell script, where ~x.y.z~ is the GHC version.
+
+The file ~haddock-ghc-x.y.z~ is located in the same directory as your
+~ghc-x.y.z~ binary.  The following command should print its path
+
+#+begin_src sh
+readlink -f `which ghc` | sed 's/\(.*\)ghc\(.*\)/\1haddock-ghc\2/'
+#+end_src
+
+For example, if you use ghcup and ghc-9.2.2, then the path should be
+~$HOME/.ghcup/ghc/9.2.2/bin/haddock-ghc-9.2.2~.
+
+Once you have located the correct ~haddock-ghc~ script, modify it by
+updating the ~exedir~ to ~"$HOME/.cabal/bin"~:
+
+#+begin_src sh
+#!/bin/sh
+exedir="$HOME/.cabal/bin" # <- update this line
+exeprog="haddock"
+# ...
+#+end_src
+
+** Usage
+
+~haddorg-api~ adds an ~--org~ flag to the ~haddock~ command.
+
+*** Direct invocation
+
+#+begin_src sh
+haddock Hello.hs --org
+#+end_src
+
+*** With cabal
+After telling cabal to use haddock built with haddorg-api (see
+[[Install]]), cd into the package you want to build the org documentation
+for, and run:
+
+#+begin_src sh
+cabal haddock --haddock-option=--org
+#+end_src
+
+If success, a fresh new org documentation will be placed under the
+package directory.
+
+** Tips
+
+- If you would like cross-package links to work, simply concatenate
+  files.  For example, concat the org file of base with that of any
+  library that say uses ~String~ in ~Prelude~ will cause ~String~
+  links to navigate to the definition of ~String~.
+
+** Coverage and areas for further work
+
+Most features and most packages should work.  However, there are some
+features to be completed.  Below is an incomplete list of missing
+features, with rare occurrences in real world haskell documentations
+marked by (RARE)
+
+- Infix declarations (currently all infix decls are shown as prefix)
+- Operator precendences
+- Minimal Signatures for classes operations
+- Correct linking due to distinction between top level identifiers and
+  constructors
+- (RARE) Data instance constructors
+- (RARE) Linear types
+- (RARE) Bundled patterns
+
+Some (rare) problems due to mismatch of haddock markup and org mode:
+
+- (RARE) Lack of distinction between inline and block elements in
+  haddock markup
+- (RARE) Table column and row spans
+
+Some cosmetic issues:
+
+- Relative heading depth for DocHeaders
+
+*** Linking issue
+
+One classical question for Org Mode users is: One org file per package
+or one big org file containing all packages?  Currently haddorg-api
+takes the latter approach.  It produces one org file per package, but
+cross-package links are generated in a way so that they only work in
+one big org file from concatenation of separate package org
+files. This may become unwieldy, especially when the big org file
+contains large libraries like base and ghc.  For links to work in the
+alternative approach, the links have to be aware of org files of other
+packages.
+
+** Acknowledgement
+
+Part of the code is adapted from [[https://github.com/lucasvreis/org-parser][org-parser]].
+
+** License, copyright, contributing
+
+Haddock is licensed under modified BSD (aka BSD-3-Clause), with
+haddock-api and haddock-library licensed under the FreeBSD license
+(aka BSD 2-Clause).  To contribute, see CONTRIBUTING.md.
+
+The Org backend written by Yuchen Pei is under the GNU Affero General
+Public License, version 3 or later.  See COPYING.agpl3 for the license
+text.  To report issues or send patches regarding the org backend,
+email Yuchen at <id@ypei.org>.