* 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 a 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. ** 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 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 .