diff options
| -rw-r--r-- | haddock-api/README.org | 28 |
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 |