From f39ec607259b936af0c10a89105e5f296ca6d021 Mon Sep 17 00:00:00 2001 From: Yuchen Pei Date: Thu, 21 Jul 2022 15:51:23 +1000 Subject: include hadrian build instructions in readme Also moved readme out to root dir for better forge rendering. --- haddock-api/README.org | 142 ------------------------------------------------- 1 file changed, 142 deletions(-) delete mode 100644 haddock-api/README.org (limited to 'haddock-api/README.org') diff --git a/haddock-api/README.org b/haddock-api/README.org deleted file mode 100644 index 3bd64d32..00000000 --- a/haddock-api/README.org +++ /dev/null @@ -1,142 +0,0 @@ -* 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 . -- cgit v1.2.3