switch to new Haddock-generated library docs
[haskell-report.git] / report / README
1
2 This is the Haskell 2010 report, source distribution.  
3
4 This has all files needed to generate either the postscript or the
5 html version of the Haskell report.  Some of these files are generated
6 from others - these are marked with a (*) and are included in case the
7 tool used to generate the file is unavailable.
8
9 To generate the postscript report you need lex, perl, latex,
10 makeindex, and dvips.
11
12 To generate the html report you need Hugs 1.4 (probably any Haskell
13 1.4 compiler will do).
14
15 To change the date on the report, you must change:
16         * haskell.verb (line 429-ish)
17         * index.html (line 8-ish)
18         * html.config (~foot item)
19         
20
21 Source files for the report:
22 plain-haskell.verb  -- Top level of the report
23
24 Sections of the report:
25 intro.verb
26 lexemes.verb
27 exps.verb
28 decls.verb
29 modules.verb
30 basic.verb
31 io-13.verb
32 standard-prelude.verb
33 syntax-iso.verb
34 literate.verb
35 derived.verb
36 pragmas.verb
37 haskell.bib
38
39 Extra .verb files:
40 iso-chars.verb    -- Some bogus definitions for ISO chars.  Probably not 
41                   -- needed since I removed them from the syntax. 
42 layout.verb       -- a section on layout repeated in the appendix
43 index-extra.verb  -- extra stuff to get indexed (see also's)
44 index-intro.verb  -- header for index
45
46 Haskell source files:
47
48 Prelude.hs
49 PreludeList.hs
50 PreludeIO.hs
51 PreludeText.hs
52
53 Figures:
54
55 classes.ppt       --  The original class figure (Powerpoint)
56 classes.eps (*)   --  Postscript version of class-fig
57 classes.gif (*)   --  For html version
58 cover.cdr         --  A nice looking cover for the report
59 cover.eps (*)
60
61 Html support:
62
63 html.config        -- configuration file for tex.hs.
64 haskell.aux (*)    -- The aux file generated by latex; used by html translator
65 haskell.bbl (*)    -- used by html translator.  Hand edited to add
66                    -- html headers at front.
67 prelude-index.idx  -- Html file containing index of prelude.  #'s are
68                    -- expanded by index.hs
69 index.html         -- Top level of the html report (hand generated)
70 lambda.gif         -- background for title page
71 title.gif          -- title graphic 
72
73 Other files:
74
75 Makefile         -- Lots of extra cruft no longer used. 
76 haskell.dvi (*)  -- in case you just want to run dvips
77 haskell.ind (*)  -- is case you don't have makeindex 
78 haskell.idx (*)  -- makes building easier
79
80
81 To build the .dvi you need to patch the makefile to call the proper
82 version of perl.  You will have some `non-grokked' instances in the
83 perl.  Remember that you have to run latex twice.  If anyone converts
84 the perl program to perl5 please send it to us!
85
86 Report any problems to peterson-john@cs.yale.edu
87
88
89 Building HTML files
90 ~~~~~~~~~~~~~~~~~~~
91 Build the html by creating a `html' subdirectory, copy the .html and
92 .gif files to it, and run tex.hs twice (like tex - to get forward refs
93 right).  Run index.hs to generate the function index.  You're done.
94 The 'make html' does most of this.
95
96 There are three files you need to work on:
97
98         report/html.config
99
100 Edit the title in the headers and footers. 
101 You can hack in whatever html you want for page headers and
102 footers .  You can also hack on the output directory setting (htmldir)
103 to direct the output wherever you want.  You'll have to fiddle
104 "index.hs" if you do this, though.  You can also add the line
105
106         style = microsoftsymbols,article
107
108 This exploits the symbol font that microsoft uses in its browser.
109 Much nicer for some of the equations.  Probably a good idea since most
110 browsers handle the symbol font OK nowadays.
111
112         report/prelude-index.idx
113
114 You will need to edit this a little bit; probably just a few renamings
115 and deleting stuff that lives in the libraries now.  Add a few more 
116 examples if you're feeling energetic.
117
118 As to the building process:
119
120 To build the html report: (using the .aux file and all the .verb files) 
121
122 cd <report directory>
123 runhugs tex.hs
124 runhugs tex.hs
125 runhugs index.hs
126
127 Like latex, you have to run tex.hs twice.  Unless you make massive
128 changes, though, you can probably just do it once.  I'm sure ghc will
129 compile tex.hs if you want to speed things up. 
130
131
132
133 Making figures
134 ~~~~~~~~~~~~~~
135 The classes.eps files, which contains the classes hierarchy figure,
136 is made in Powerpoint, from classses.ppt.  To get the .eps file,
137 do the following:
138
139 * Open classes.ppt
140 * Print..
141 * Check the print-to-file box, and save as classes.prn
142 * Edit classes.prn
143         Kill the .prn header and footer (before % PS-Adobe), and after %EOF
144         Kill the entire setup code (from BeginSetup to EndSetup)
145         Kill the showpage near the end
146 * Save as classes.eps
147 * Open with Ghostview
148 * Note the coords of the bottom LH and top RH corner, as reported by
149   Ghostview
150 * Re-edit classes.eps, and put those coords in the
151         %BoundingBox line
152
153 You also need to do
154         Save As.. 
155 in Powerpoint, and save the thing as classes.gif, for the HTML version
156
157
158
159