update READMEs
authorSimon Marlow <marlowsd@gmail.com>
Wed, 30 Jun 2010 15:10:24 +0000 (15:10 +0000)
committerSimon Marlow <marlowsd@gmail.com>
Wed, 30 Jun 2010 15:10:24 +0000 (15:10 +0000)
README
report/README

diff --git a/README b/README
index c1c81c3..b1d82a5 100644 (file)
--- a/README
+++ b/README
@@ -1,12 +1,43 @@
-Notes on building the report
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Haskell Report README
+~~~~~~~~~~~~~~~~~~~~~
 
-Tools needed: 
-      
-      * flex
-      * GHC
-      * TeX (install "tetex" on a Linux distribution to get everything
-        you need).
+These are the sources to the Haskell report, including all the source
+files you will need to generate either the PDF or the HTML version of
+the report.
+
+
+Tools you will need
+~~~~~~~~~~~~~~~~~~~
+
+PDF version: a decent LaTeX installation with pdflatex.  We use the
+following additional packages:
+
+  - times
+  - makeidx
+  - graphicx
+  - url
+  - color
+  - hyperref
+
+Also you need the following tools
+
+  - makeindex
+
+all of which are usually available with a good TeX distribution
+(e.g. TeX Live).
+
+The following are also required for building the tools:
+
+  - flex
+  - GHC
+
+The HTML version additionall requires
+
+  - tex4ht (e.g. install 'tex4ht' on a Debian or Ubuntu system, or 
+            'tetex-tex4ht' on a Fedora system)
+
+Building the report
+~~~~~~~~~~~~~~~~~~~
 
 Firstly:
 
@@ -19,23 +50,12 @@ Then you should be able to say
         $ cd report
         $ make
 
-to build the PS (haskell.ps) and HTML (in haskell-report-html)
-versions.  To get PDF, use ps2pdf on the PS version.
+This will create:
 
-When you check in a patch to the darcs repo, darcs will automatically
-try to re-build the tools and report.  If it fails for any reason, then
-your patch will be rejected.  (This is controlled by the top-level
-Makefile target 'default', and the darcs preferences.)  If you think
-your patch is fine, but the build system is broken, then you might need
-to login to darcs.haskell.org and do some fixing by hand.
-
-[
-  There are various other Makefile rules; for example 'make release' at
-  the top level was supposed to build a complete release of the "Revised
-  Haskell 98 Report", although it doesn't work out of the box.  For
-  Haskell', we'll want to modify these Makefiles to do what we want in
-  due course.
-]
+   - PDF version: report/haskell.pdf
+   
+   - HTML version: report/ht/haskell.html
+     (NB. requires report/ht/*.{html,png,css})
 
 
 Roadmap
@@ -46,21 +66,13 @@ SOURCE FILES
     report/            The Language and Libraries Reports (now together
                        in a single document)
     
-    libraries/         OUT OF DATE (from Dec 2002): ignore this directory
-    
     tools/             Tools needed to build the Reports
                        (cd into here and type make)
     
     Makefile           Build a distribution of the Reports
 
-    report/haskell-prime-draft.html    A summary page to glue all the outputs together
-
-    report/h98.gif     A GIF for a Haskell 98 logo
-    report/hprime.png  A PNG for a Haskell Prime logo
-
 
-OUTPUT FILES
-    haskell-prime-draft/       A directory containing the distribution
-    haskell-report-html/       A directory containing the HTML
+.verb files
+~~~~~~~~~~~
 
 
index e03bcb0..e2c78e2 100644 (file)
@@ -1,25 +1,28 @@
+Haskell Report Sources
+~~~~~~~~~~~~~~~~~~~~~~
 
-This is the Haskell 2010 report, source distribution.  
+.verb files
+~~~~~~~~~~~
 
-This has all files needed to generate either the postscript or the
-html version of the Haskell report.  Some of these files are generated
-from others - these are marked with a (*) and are included in case the
-tool used to generate the file is unavailable.
+.verb files are converted to .tex by the preprocessor "verbatim" in
+../tools.  When generating HTML via tex4ht, we use a slightly
+different version of the preprocesor, in ../tools/verb-tex4ht.
 
-To generate the postscript report you need lex, perl, latex,
-makeindex, and dvips.
 
-To generate the html report you need Hugs 1.4 (probably any Haskell
-1.4 compiler will do).
+make targets
+~~~~~~~~~~~~
 
-To change the date on the report, you must change:
-       * haskell.verb (line 429-ish)
-       * index.html (line 8-ish)
-       * html.config (~foot item)
-       
+   all       make both HTML and PDF versions
+   html      make the HTML version
+   pdf       make the PDF version
+   clean     remove generated files
+   haddock   re-generate the library documentation using Haddock
+             (see Makefile for instructions)
 
-Source files for the report:
-plain-haskell.verb  -- Top level of the report
+Roadmap
+~~~~~~~
+
+haskell.verb  -- Top level of the report
 
 Sections of the report:
 intro.verb
@@ -29,17 +32,22 @@ decls.verb
 modules.verb
 basic.verb
 io-13.verb
+ffi.verb
 standard-prelude.verb
 syntax-iso.verb
-literate.verb
+fixity.verb
 derived.verb
 pragmas.verb
 haskell.bib
 
+Library documentation, generated by Haddock:
+
+libs/*.verb       -- documentation for each library module
+haddck.sty        -- definitions for macros used by Haddock
+
 Extra .verb files:
 iso-chars.verb    -- Some bogus definitions for ISO chars.  Probably not 
                   -- needed since I removed them from the syntax. 
-layout.verb       -- a section on layout repeated in the appendix
 index-extra.verb  -- extra stuff to get indexed (see also's)
 index-intro.verb  -- header for index
 
@@ -60,74 +68,18 @@ cover.eps (*)
 
 Html support:
 
-html.config        -- configuration file for tex.hs.
-haskell.aux (*)    -- The aux file generated by latex; used by html translator
-haskell.bbl (*)    -- used by html translator.  Hand edited to add
-                   -- html headers at front.
-prelude-index.idx  -- Html file containing index of prelude.  #'s are
-                   -- expanded by index.hs
-index.html         -- Top level of the html report (hand generated)
-lambda.gif         -- background for title page
-title.gif          -- title graphic 
+ht/haskell.cfg     -- tex4ht configuration file
+ht/haddock.sty     -- customised Haddock style for HTML output
+
+index.html         -- (unused now) Top level of the html report (hand generated)
+lambda.gif         -- (unused now) background for title page
 
 Other files:
 
 Makefile         -- Lots of extra cruft no longer used. 
-haskell.dvi (*)  -- in case you just want to run dvips
-haskell.ind (*)  -- is case you don't have makeindex 
-haskell.idx (*)  -- makes building easier
-
-
-To build the .dvi you need to patch the makefile to call the proper
-version of perl.  You will have some `non-grokked' instances in the
-perl.  Remember that you have to run latex twice.  If anyone converts
-the perl program to perl5 please send it to us!
-
-Report any problems to peterson-john@cs.yale.edu
-
-
-Building HTML files
-~~~~~~~~~~~~~~~~~~~
-Build the html by creating a `html' subdirectory, copy the .html and
-.gif files to it, and run tex.hs twice (like tex - to get forward refs
-right).  Run index.hs to generate the function index.  You're done.
-The 'make html' does most of this.
-
-There are three files you need to work on:
-
-       report/html.config
-
-Edit the title in the headers and footers. 
-You can hack in whatever html you want for page headers and
-footers .  You can also hack on the output directory setting (htmldir)
-to direct the output wherever you want.  You'll have to fiddle
-"index.hs" if you do this, though.  You can also add the line
-
-       style = microsoftsymbols,article
-
-This exploits the symbol font that microsoft uses in its browser.
-Much nicer for some of the equations.  Probably a good idea since most
-browsers handle the symbol font OK nowadays.
-
-       report/prelude-index.idx
-
-You will need to edit this a little bit; probably just a few renamings
-and deleting stuff that lives in the libraries now.  Add a few more 
-examples if you're feeling energetic.
-
-As to the building process:
-
-To build the html report: (using the .aux file and all the .verb files) 
-
-cd <report directory>
-runhugs tex.hs
-runhugs tex.hs
-runhugs index.hs
-
-Like latex, you have to run tex.hs twice.  Unless you make massive
-changes, though, you can probably just do it once.  I'm sure ghc will
-compile tex.hs if you want to speed things up. 
 
+Report any problems to the most recent editor, or failing that, one of
+the past editors of the report.
 
 
 Making figures