aboutsummaryrefslogtreecommitdiff
path: root/haddock-api
diff options
context:
space:
mode:
authorYuchen Pei <hi@ypei.me>2022-07-19 11:16:02 +1000
committerYuchen Pei <hi@ypei.me>2022-07-19 11:16:02 +1000
commit702977b075dfdfc12275c30d3b395b1f811f640e (patch)
tree4103f8c385fae05151e888153f7e292a8959c931 /haddock-api
parentde2eaa25ea0e373b63ea2c22eecefd3aaed01fb0 (diff)
updating readme
Diffstat (limited to 'haddock-api')
-rw-r--r--haddock-api/README.org28
1 files changed, 16 insertions, 12 deletions
diff --git a/haddock-api/README.org b/haddock-api/README.org
index ac63165e..298d2306 100644
--- a/haddock-api/README.org
+++ b/haddock-api/README.org
@@ -7,7 +7,7 @@ to haddock, see README.md.
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.
+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.
@@ -33,8 +33,8 @@ cd haddock
cabal install
#+end_src
-This will create a haddock binary under ~~/.cabal/bin~ - make sure it
-is in your PATH.
+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.
@@ -50,7 +50,7 @@ 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"~:
+updating the ~exedir~ to ~"$HOME/.cabal/bin"~:
#+begin_src sh
#!/bin/sh
@@ -116,17 +116,21 @@ Some cosmetic issues:
*** 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.
+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, including haddock-api and haddock-library is licensed under
-the FreeBSD license (aka BSD 2-Clause). To contribute, see
-CONTRIBUTING.md.
+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