updating readme

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