* 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

- [[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 ~~/.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>.