From 131e3b41d6128d2e4b66be8582ae60ccd6380994 Mon Sep 17 00:00:00 2001
From: Yuchen Pei <hi@ypei.me>
Date: Mon, 18 Jul 2022 15:40:47 +1000
Subject: Preparing for publication.

- license
- cabal
- readme
---
 haddock-api/README.org | 127 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 haddock-api/README.org

(limited to 'haddock-api/README.org')

diff --git a/haddock-api/README.org b/haddock-api/README.org
new file mode 100644
index 00000000..4a00483c
--- /dev/null
+++ b/haddock-api/README.org
@@ -0,0 +1,127 @@
+* haddorg-api
+
+** 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 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
+
+- base-4.16.1.org
+- ghc-lib-parser.org, pretending to be ghc (fake ghc)
+- lens
+- haddorg-api-2.26.1.org, also in this repository
+- haddock-library-2.26.1.org
+- haddorg-api + haddock-library + fake ghc + base, to demo
+  cross-package links
+- fsd + sqlite-simple + debian, to demo cross-package links
+- and 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 ~~/.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~ with the ~"$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 want 
+
+** 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 org file per package or one big org file containing all packages?
+Currently haddorg-api takes the former approach.  However, this may
+become unwieldy, especially when including large libraries like base
+and ghc.  Whereas the issue with having one file per package is
+correct linking.
+
+** License, copyright, contributing
+
+Haddock, including haddock-api and haddock-library is licensed under
+the FreeBSD license (aka BSD 2-Clause).  To contribute, see
+CONTRIBUTING.md.
+
+The Org backend written by Yuchen Pei is licensed under the GNU Affero
+GPL 3.0+.  See COPYING.agpl3 for the license text.  To report issues
+or send patches regarding the org backend, email Yuchen at
+<id@ypei.org>.
-- 
cgit v1.2.3