[clean up documentation, rename all environment variable to have a consistent JHC_ prefix
John Meacham <john@repetae.net>**20090814023617
 Ignore-this: 1dffad758c102990317e7fdbf658b9a3
] hunk ./docs/using.txt 1
-= Using jhc =
-
-Installation of jhc involves building the jhc binary, placing it somewhere you
-can execute it and putting the libraries somewhere.
-
-=== Building jhc ===
-
-building jhc requires the most recent version of DrIFT 2.2.1 or better, which
-can be gotten at http://repetae.net/john/computer/haskell/DrIFT/, GHC 6.6,
-happy, Perl, and having darcs will help keep updated with the newest version
-and submit patches.
-
-==== Getting the source ====
-
-Because jhc uses subrepositories, you need to use multiple darcs commands to
-pull everything needed to build jhc.
-
-  darcs get http://repetae.net/john/repos/jhc
-  cd jhc
-  darcs get http://repetae.net/john/repos/Doc
-  cd lib
-  darcs get http://darcs.haskell.org/packages/haskell98/
-  darcs get http://darcs.haskell.org/packages/QuickCheck/
-
-The binary and zlib packages also need to be installed.
-
-  http://hackage.haskell.org/cgi-bin/hackage-scripts/package/binary/
-  http://hackage.haskell.org/cgi-bin/hackage-scripts/package/zlib/
-
-==== making it ====
-
-Assuming you have ghc 6.6, happy, and DrIFT installed, you may now run GNU
-make by typing 'gmake' or just 'make' depending on your system and get a
-binary 'jhc' out if nothing went wrong.
-
-Installation is done with 'gmake install' or for a custom installation
-prefix 'gmake install PREFIX=/foo/bar'. This will install jhc and jhci
-in ${PREFIX}/bin and base libraries in ${PREFIX}/lib, from where they
-are automatically included when needed.
-
-=== Installing the libraries - the old way ====
-
-The jhc libraries will be in the 'lib' directory. these may be installed
-anywhere or left in place but the directory where they are installed *must be
-writable by the user of jhc* otherwise the compiler cannot create its
-intermediate files.
-
-Set the environment variable JHCPATH to the location of the library wherever
-you put it, or pass -i<dir> to jhc every time you call it so it can find the
-standard libraries.
-
-The first time you compile something, jhc will automatically create an
-optimized version of the standard libraries in 'ho' files next to their source
-code. This is why the library needs to be somewhere writable. Another effect
-being the first time you run jhc, it will take much longer than future runs.
-
-
-=== Running jhc ===
-
-jhc always runs in a mode similar to 'ghc --make' and will find all
-dependencies automatically. just run jhc on your file containing the Main module.
-
-  jhc -v Main.hs
-
-it is HIGHLY HIGHLY recommended you pass the '-v' flag to jhc. jhc takes a very
-long time to compile programs and without feedback you won't know if there is a
-problem. Much of the debugging output contains Unicode characters, it helps if
-your terminal is UTF8.
-
-While compiling, jhc will drop 'ho' files alongside your source code to speed
-up future compilation. feel free to delete these if you want to. There are
-various options for controlling the writing and reading of these ho files.
-
-=== Environment Variables ===
-
-jhc understands the following environment variables
-
- JHCPATH - path to search for haskell source files, seperated by colons.
-
- JHCLIBPATH - path to search for jhc library files
-
-==== Options ====
-
-general options
-
-<include text `/home/john/bin/jhc --help 2>&1`>
-
-things to pass to -d
-
-<include text `/home/john/bin/jhc -dhelp  2>&1`>
-
-things to pass to -f
-
-<include text `/home/john/bin/jhc -fhelp 2>&1 `>
-
-----
-
-http://repetae.net/john/computer/jhc
-
rmfile ./docs/using.txt
hunk ./Makefile.am 253
-manual: utils/stitch.prl src/FlagDump.mkd src/FlagOpts.mkd options.mkd
-	find . ! -wholename '*/examples/*'  ! -wholename '*/_darcs/*' ! -wholename '*/drift_processed/*'  ! -wholename '*/regress/*'  \( -name '*.hs' -o -name '*.hsc' -o -name '*.mkd' -o -wholename '*/src/data/rts/*.c' \) | xargs perl utils/stitch.prl > manual.mkd
+manual: utils/stitch.prl src/FlagDump.mkd src/FlagOpts.mkd options.mkd docs/*.mkd
+	find . ! -wholename */jhc-*/* ! -wholename '*/examples/*'  ! -wholename '*/_darcs/*' ! -wholename '*/drift_processed/*'  ! -wholename '*/regress/*'  \( -name '*.hs' -o -name '*.hsc' -o -name '*.mkd' -o -wholename '*/src/data/rts/*.c' \) | xargs perl utils/stitch.prl > manual.mkd
hunk ./Makefile.am 257
-man: utils/stitch.prl src/FlagDump.mkd src/FlagOpts.mkd options.mkd docs/man_header.mkd
-	find . ! -wholename '*/examples/*'  ! -wholename '*/_darcs/*' ! -wholename '*/drift_processed/*'  ! -wholename '*/regress/*'  \( -name '*.hs' -o -name '*.hsc' -o -name '*.mkd' -o -wholename '*/src/data/rts/*.c' \) | xargs perl utils/stitch.prl -h docs/man_header.mkd -c Using,Options > jhc_man.mkd
+man: utils/stitch.prl src/FlagDump.mkd src/FlagOpts.mkd options.mkd docs/man_header.mkd docs/*.mkd
+	find . ! -wholename */jhc-*/ ! -wholename '*/examples/*'  ! -wholename '*/_darcs/*' ! -wholename '*/drift_processed/*'  ! -wholename '*/regress/*'  \( -name '*.hs' -o -name '*.hsc' -o -name '*.mkd' -o -wholename '*/src/data/rts/*.c' \) | xargs perl utils/stitch.prl -h docs/man_header.mkd -c Using,Options > jhc_man.mkd
hunk ./docs/make.mkd 10
-    ; jhc -v HelloWorld.hs -o hello
+    ; jhc HelloWorld.hs -o hello
hunk ./docs/make.mkd 12
-Libraries are built by passing jhc a file describing the library via the
---build-hl option. The file format is a simplified version of the cabal format.
-The name of the generated file will be <basename>-<version>.hl.
+Jhc searches for modules in its search path, which defaults to the current
+directory. Modules are searched for based on their names. For instance, the
+module Data.Foo will be searched for in 'Data/Foo.hs'. As an extension, jhc will
+also search for 'Data.Foo.hs'. The search path may be modifed with the '-i'
+command line option, or by setting the 'JHC_PATH' environment variable.
+
+# Using Libraries
hunk ./docs/make.mkd 20
-    ; jhc -v --build-hl mylibrary.cabal
+jhc libraries are distributed as files with an 'hl' suffix, such as
+'base-1.0.hl'. In order to use a haskell  library you simply need to place the
+file in a directory that jhc will search for it. For instance, $HOME/lib/jhc.
+You may set the environment variable  JHC_LIBRARY_PATH to specify alternate
+locations to search for libraries or specify directory to search with the -L
+command line option. -L- will clear the search path.
hunk ./docs/make.mkd 27
+You can then use libraries with the '-p' command line option, for instance if
+you had a library 'mylibrary-1.0.hl' in your search path, the following would
+use it.
hunk ./docs/make.mkd 31
-# installing and using libraries
+    ; jhc -p mylibrary MyProgram.hs -o myprogram
hunk ./docs/make.mkd 33
-jhc libraries are distributed as files with an 'hl' suffix, such as
-'base-1.0.hl'. You simply need to drop this file somewhere that jhc can find
-it. for instance, $HOME/lib/jhc. You can then set $JHCLIBPATH to said
-directory, or specify it on the command line with the '-L' option. Extra
-libraries are specified on the command line with the '-p' option.
hunk ./docs/make.mkd 34
-    ; jhc -v -L/home/john/devel/jhc -pmylibrary MyProgram.hs -o myprogram
+# Environment Variables
+
+Jhc's behavior is modified by several enviornment variables.
hunk ./docs/make.mkd 38
+JHC_OPTS
+: this is read and appended to the command line of jhc invocations.
hunk ./docs/make.mkd 41
+JHC_PATH
+: This specifies the path to search for modules.
+
+JHC_LIBRARY_PATH
+: This specifies the path to search for libraries.
+
+JHC_CACHE
+: This specified the directory jhc will use to cache values. having a valid cache is essential for jhc performance. It defaults to ~/.jhc/cache.
+
+# Building Haskell Libraries
+
+Libraries are built by passing jhc a file describing the library via the
+--build-hl option. The file format is a simplified version of the cabal format.
+The name of the generated file will be basename-version.hl.
hunk ./docs/make.mkd 56
-# Building Projects With make
+    ; jhc --build-hl mylibrary.cabal
hunk ./docs/make.mkd 58
-Using make to build projects with jhc is straightforward, simply add a line like the following in your Makefile
+## Library File Format
hunk ./docs/make.mkd 60
+The library file is a simple list of key value pairs seperated by colon. The fields that jhc cares about are
hunk ./docs/make.mkd 62
-    % : %.hs
-            jhc -v $< -o $@
+    Name: The Name of your library
+    Version: The Version of your library
+    Exposed-Modules: Comma Seperated list of modules to be included in the library and made availabe to users of the library
+    Hidden-Modules: Comma Seperated list of modules that will be used by the library internally, but not be made available outside it.
hunk ./docs/make.mkd 67
-Or, to build a library, something similar to this will do.
+Other fields are stored as-is inside of the generated hl file and can be seen with jhc --show-ho file.hl.
hunk ./docs/make.mkd 69
-    %.hl : %.cabal
-            jhc -v --build-hl $< -o $@
hunk ./docs/unboxed.mkd 3
+# Module Search Path
+
+Modules in jhc are searched for based on their name as in other Haskell
+compilers. However in addition to searching for 'Data/Foo.hs' for the module
+'Data.Foo', jhc will also search for 'Data.Foo.hs'.
+
+# Rank-N Polymorphism
+
+Jhc supports higher ranked polymorphism. jhc will never infer types of higher
+rank, however when the context unambiguously specifies a higher ranked type, it
+will be infered. For instance, user supplied type annotations and arguments to
+data constructors defined to by polymorphic will work.
+
+# Existential types
+
hunk ./docs/unboxed.mkd 36
-have types 'Addr__' which is as synonym for 'BitsPtr_'
+have types 'Addr__' which is as synonym for 'BitsPtr_'.
hunk ./docs/unboxed.mkd 44
-defaults to Int__.
+defaults to Int__. Whether the type is fully specifed follows the same rules as
+rank-n types.
hunk ./src/E/Type.hs 23
-{-@Internals
+{- @Internals
hunk ./src/Options.hs 284
-    x <- lookupEnv "JHCOPTS"
+    x <- lookupEnv "JHC_OPTS"
hunk ./src/Options.hs 329
+
+
hunk ./src/Options.hs 333
-    cd <- lookupEnv "HOCACHEDIR"
+    cd <- lookupEnv "JHC_CACHE"
hunk ./src/Options.hs 413
-    p <- lookupEnv "JHCPATH"
+    p <- lookupEnv "JHC_PATH"
hunk ./src/Options.hs 421
-    ps <- lookupEnv "JHCLIBPATH"
+    ps <- lookupEnv "JHC_LIBRARY_PATH"