Commit 64ca4381 authored by Simon Marlow's avatar Simon Marlow
Browse files

update READMEs

parent 55650918
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
~~~~~~~~~~~
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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment