aboutsummaryrefslogtreecommitdiff
path: root/haddock-api
diff options
context:
space:
mode:
authorYuchen Pei <hi@ypei.me>2022-07-21 15:51:23 +1000
committerYuchen Pei <hi@ypei.me>2022-07-21 15:51:23 +1000
commit87e59e7826b427b8718ef4313d07d75aa4c2a7bf (patch)
tree1819a6c1097774e1b5303c9cccac4498b2861ab5 /haddock-api
parentcd17128898089450bb21790fd1864dc08fd4ddbc (diff)
include hadrian build instructions in readme
Also moved readme out to root dir for better forge rendering.
Diffstat (limited to 'haddock-api')
-rw-r--r--haddock-api/README.org142
1 files changed, 0 insertions, 142 deletions
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 <id@ypei.org>.