[start adding jhc manual and program to stitch it together
John Meacham <john@repetae.net>**20080221010433] hunk ./Makefile.am 192
-.PHONY: ho-clean hl-clean i update-datestamp
+.PHONY: ho-clean hl-clean i update-datestamp manual
hunk ./Makefile.am 231
+manual: utils/stitch.prl
+	find . ! -wholename '*/test/*'  ! -wholename '*/_darcs/*' ! -wholename '*/drift_processed/*'  ! -wholename '*/regress/*'  \( -name '*.hs' -o -name '*.hsc' -o -name '*.mkd' \) | xargs perl utils/stitch.prl > manual.mkd
addfile ./docs/differences.mkd
hunk ./docs/differences.mkd 1
+{-#Differences
+
+# Differences from Haskell 98
+
+## Library Differences
+
+In addition to a larger set of base libraries roughly modeled on ghc's base.
+jhc provides a number of extensions/minor modifications to the standard
+libraries. These are designed to be mostly backwards compatable and most are
+to the class system.
+
+* Data.Int and Data.Word provide WordPtr, WordMax, IntPtr, and IntMax that
+   coorespond to the C types uintptr_t, uintmax_t, intptr_t, and uintmax_t
+   respectively.
+
+* class methods are fully 'eta expanded' out to the argument count specified
+   by the type. this is often beneficial as instances that need to share
+   partial applications are rare. this behavior can be turned off with the
+   NOETA pragma for specific methods.
+
+* Data.Bits
+    * Num is no longer a super class of Data.Bits. It never should have been.
+    * There are new methods logicalShiftR and arithmeticShiftR that do a logical and
+      arithmetic shift respectively. shiftR will always map to one of those as
+      appropriate.
+    * shiftR and shiftL do not check for negative arguments, if you might want
+      netative argumenst, use the general 'shift' routine. 'shift' also comes
+      in logical and arithmetic varieties.
+
+* fromInt,toInt,fromDouble,toDouble have been added
+   alongside Integer and Rational routines in their respective classes.
+
+* floating point trucation and rounding functions have varieties that don't
+   return an integral type, but rather return something of the same type
+   as its argument. these have the same name but end in 'f'.
+
+
+# Notable Differences from GHC
+
+Jhc differs from GHC in certain ways that are allowed by Haskell 98, but might
+come as a surprise to some.
+
+ * Int's may be only 30 bits and may not observe simple binary truncation on
+   overflow. If you need known bitwidth and binary semantics for your numbers
+   then use the types in Data.Int and Data.Word
+
+ * Char's only preserve values within the unicode range. trying to store
+   values > 0x10FFFF may be truncated.
+
+ * Ints and Words are at most 32 bits, even on 64 bit architectures.
+
+ * All text based IO is performed according to the current locale. this means
+   that unicode works seamlessly, but older programs that assumed IO was
+   performed by simple truncation of chars down to 8 bits will fail. use the
+   explicit binary routines if you need binary IO.
+
+
+# Differences That are Considered Misfeatures
+
+These misfeatures will be fixed at some point.
+
+ * Integer cooresponds to IntMax rather than an arbitrary precision type. as
+   soon as a suitable arbitrary precision library emerges, it will be
+   replaced.
+
+ * Ix is not derivable.
+
+
addfile ./docs/make.mkd
hunk ./docs/make.mkd 1
+{-#Using
+
+# Building Projects With make
+
+using make to build projects with jhc is straightforward, simply add a line like the following in your Makefile
+
+
+    % : %.hs
+            jhc -v $< -o $@
+
+If you wish jhc to automatically generate dependency information, you can do the following
+
+    % : %.hs
+            jhc --deps depend.make -v $< -o $@
+
+    -include depend.make
+
+
+
+    %.hl : %.cabal
+            jhc -v --build-hl $< -o $@
addfile ./docs/unboxed.mkd
hunk ./docs/unboxed.mkd 1
+{-#Extensions
+
+# Unboxed Values
+
+Unboxed values in jhc are specified in a similar fashion to ghc however the
+lexical syntax is not changed to allow # in identifiers. # is still used in
+the syntax for various unboxed constructs, but normal haskell rules apply to
+other haskell values. The convention is to suffix such types with '_' to
+indicate their status as unboxed.
+
+## Unboxed Tuples
+
+Jhc supports unboxed tuples with the same syntax as ghc, (# 2, 4 #) is an
+unboxed tuple of two numbers. unboxed tuples are enabled with -funboxed-tuples
+
+
+## Unboxed Strings
+
+Unboxed strings are enabled with the -funboxed-values flag. they are
+specified like a normal string but have a '#' at the end. Unboxed strings
+have types 'Addr__' which is as synonym for 'BitsPtr_'
+
+## Unboxed Numbers
+
+Unboxed numbers are enabled with the -funboxed-values flag. They are postpended
+with a '#' such as in 3# or 4#. jhc supports a limited form of type inference
+for unboxed numbers, if the type is fully specified by the environment and it
+is a suitable unboxed numeric type then that type is used. otherwise it
+defaults to Int__.
+
addfile ./utils/stitch.prl
hunk ./utils/stitch.prl 1
+#!/usr/bin/perl
+
+use strict;
+use warnings;
+
+my @order = qw(
+    Using
+    Extensions
+    Differences
+    );
+
+my %h;
+
+foreach my $fn (@ARGV) {
+    open my $fh, "<$fn" or die "$!: could not open $fn";
+    while(<$fh>) {
+        /^\{\-#(\w+)\s*$/ or next;
+        my ($section,$text) = ($1,"");
+        while(<$fh>) {
+            /^\-\}\s*$/ and last;
+            $text .= $_;
+        }
+        $h{$section}{text} .= $text;
+        $h{$section}{files} .= ":$fn";
+    }
+}
+
+foreach(@order) {
+    print "\n# $_\n\n";
+    $h{$_}{text} =~ s/^(#+ )/#$1/mg;
+    print $h{$_}{text};
+}
+
+foreach(keys %h) {
+    print STDERR $_," ",$h{$_}{files},"\n";
+}