* 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/hierarchy-e2f0094c.org.gz][Haskell Hierarchical Libraries]], built at [[https://gitlab.haskell.org/ghc/ghc/-/commit/e2f0094c315746ff15b8d9650cf318f81d8416d7][ghc commit e2f0094c]]. - [[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-9.5-e2f0094c.org.gz][ghc-9.5-e2f0094c.org]], GHC API docs built at [[https://gitlab.haskell.org/ghc/ghc/-/commit/e2f0094c315746ff15b8d9650cf318f81d8416d7][ghc commit e2f0094c]]. - [[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. - [[https://ypei.org/assets/haddorg-output/haddorg-api-2.26.1.org.gz][haddorg-api-2.26.1.org]] - [[https://ypei.org/assets/haddorg-output/lens-5.1.org.gz][lens-5.1.org]] - [[https://ypei.org/assets/haddorg-output/fsd-sqlite-simple-debian.org.gz][fsd + sqlite-simple + debian]], demonstrating cross-package linking - and [[https://ypei.org/assets/haddorg-output/][more...]], including [[https://ypei.org/assets/haddorg-output/hierarchy-e2f0094c/][all ghc libraries]] built at [[https://gitlab.haskell.org/ghc/ghc/-/commit/e2f0094c315746ff15b8d9650cf318f81d8416d7][ghc commit e2f0094c]]. ** 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 ls *.org # If success, the org file should be placed here #+end_src *** With cabal Follow instructions in [[Install]] to tell cabal to use haddock built with haddorg-api. Using lens-5.1 as an example package, to fetch a package from Hackage, one may use ~cabal unpack~: #+begin_src sh cabal unpack lens-5.1 #+end_src Now cd into the package you want to build the org documentation for, and run the commands: #+begin_src sh cd lens-5.1 cabal haddock --haddock-option=--org ls lens-5.1.org # If success, the org file should be placed here #+end_src If success, a fresh new org documentation will be placed under the package directory (not in dist-newstyle!). *** With Hadrian In order to build documentation for GHC API or Haskell Hierarchical Libraries, one may need to use the GHC build tool hadrian to invoke Haddock. It is tricky as the ghc repo tracks [[https://gitlab.haskell.org/ghc/haddock/][its own haddock]] as a submodule, which is built by hadrian and invoked for the documentation. Compared to [[https://github.com/haskell/haddock][the official haddock repo]] this haddock can be ahead in some commits as it has to build against the bleeding-edge GHC libraries (ghc api, base, ghc-prim, ...) in ghc repo, and behind in some commits as the official repo make changes to improve haddock itself. The haddorg-api repo at does have a [[https://g.ypei.me/haddock.git/?h=ghc-gitlab-ghc-head][ghc-gitlab-ghc-head branch]] to track the ghc-head branch of ghc haddock repo. In fact, it was used to build ghc and haskell hierarchical libraries org documentation so it is not impossible. But this branch can go out of sync with the official ghc repo, and even if it stays in sync all the time, one still needs to manually find out which commit on the ghc haddock repo ghc-head branch corresponds to which commit on the ghc-gitlab-ghc-head branch. The following is instructions on how to run haddock with hadrian, where the reader may need to figure out the merge part, if a suitable commit on the [[https://g.ypei.me/haddock.git/?h=ghc-gitlab-ghc-head][ghc-gitlab-ghc-head branch]] cannot be found. First, clone ghc with all its submodules. For example, to perform a shallow clone, do: #+begin_src sh git clone --depth 1 --recurse-submodules https://gitlab.haskell.org/ghc/ghc.git #+end_src Then, update the flags in the hadrian code, merge the org backend related commits into the haddock submodule located at ~utils/haddock~, and build the documentation as usual: #+begin_src sh cd ghc # Edit ./hadrian/src/Settings/Builders/Haddock.hs by adding an --org flag. # Merge org backend commits into ./utils/haddock, resolve any conflicts that # may arise ./boot && ./configure hadrian/build docs -j --flavour=Quick ls *.org # If success, the org files should be placed here #+end_src ** 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 .