Late Dec release
[haskell-report.git] / report / literate.verb
1 %
2 % $Header: /home/cvs/root/haskell-report/report/literate.verb,v 1.4 2001/12/21 16:00:25 simonpj Exp $
3 %
4 %**<title>The Haskell 98 Report: Literate Comments</title>
5 %*section C
6 %**~header
7 \section{Literate comments}
8 \label{literate}
9 \index{literate comments}
10
11 The ``literate comment''
12 convention, first developed by Richard Bird and Philip Wadler for
13 Orwell, and inspired in turn by Donald Knuth's ``literate
14 programming'', is an alternative style for encoding \Haskell{} source
15 code. 
16 The literate style encourages comments by making them the default.  A
17 line in which ``@>@'' is the first character is treated as part of the
18 program; all other lines are comment.
19
20 The program text is recovered
21 by taking only those lines beginning with ``@>@'', 
22 and replacing the leading ``@>@'' with a space.
23 Layout and comments apply
24 exactly as described in Appendix~\ref{syntax} in the resulting text.
25
26 To capture some cases where one omits an ``@>@'' by mistake, it is an
27 error for a program line to appear adjacent to a non-blank comment line,
28 where a line is taken as blank if it consists only of whitespace.
29
30 By convention, the style of comment is indicated by the file
31 extension, with ``@.hs@'' indicating a usual Haskell file and
32 ``@.lhs@'' indicating a literate Haskell file.  Using this style, a
33 simple factorial program would be:
34 \bprog
35 @
36    This literate program prompts the user for a number
37    and prints the factorial of that number:
38
39 > main :: IO ()
40
41 > main = do putStr "Enter a number: "
42 >           l <- readLine
43 >           putStr "n!= "
44 >           print (fact (read l))
45           
46   This is the factorial function.
47
48 > fact :: Integer -> Integer
49 > fact 0 = 1
50 > fact n = n * fact (n-1)
51 @
52 \eprog
53
54
55 An alternative style of literate programming is particularly
56 suitable for use with the LaTeX text processing system.
57 In this convention, only those parts of the literate program that are
58 entirely enclosed between @\begin{code}@$\ldots$@\end{code}@ delimiters are
59 treated as program text; all other lines are comment.  More precisely:
60 \begin{itemize}
61 \item Program code begins on the first line following a line that begins @\begin{code}@.
62 \item Program code ends just before a subsequent line that begins @\end{code}@ (ignoring
63 string literals, of course).
64 \end{itemize}
65 It is not necessary
66 to insert additional blank lines before or after these delimiters, though
67 it may be stylistically desirable.  For example,
68 \bprog
69 @
70 \documentstyle{article}
71
72 \begin{document}
73
74 \section{Introduction}
75
76 This is a trivial program that prints the first 20 factorials.
77
78 \begin{code}
79 main :: IO ()
80 main =  print [ (n, product [1..n]) | n <- [1..20]]
81 \end{code}
82
83 \end{document}
84 @
85 \eprog
86 This style uses the same file extension.  It is not advisable to mix
87 these two styles in the same file.
88
89 %**~footer