summary refs log tree commit diff stats
path: root/config/nimdoc.cfg
blob: d47dccb635f4d7ebdb395d35a202ad97c166959d (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
# This is the config file for the documentation generator.
# (c) 2012 Andreas Rumpf
# Feel free to edit the templates as you need.

split.item.toc = "20"  
# too long entries in the table of contents wrap around
# after this number of characters

doc.section = """
<div class="section" id="$sectionID">
<h1><a class="toc-backref" href="#$sectionTitleID">$sectionTitle</a></h1>
<dl class="item">
$content
</dl></div>
"""

doc.section.toc = """
<li>
  <a class="reference" href="#$sectionID" id="$sectionTitleID">$sectionTitle</a>
  <ul class="simple">
    $content
  </ul>
</li>
"""

doc.item = """
<dt id="$itemID"><pre>$header</pre></dt>
<dd>
$desc
</dd>
"""

doc.item.toc = """
  <li><a class="reference" href="#$itemID">$name</a></li>
"""

doc.toc = """
<div class="navigation" id="navigation">
<ul class="simple">
$content
</ul>
</div>"""

doc.body_toc = """
$tableofcontents
<div class="content" id="content">
$moduledesc
$content
</div>
"""

doc.body_no_toc = """
$moduledesc
$content
"""

doc.file = """<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--  This file is generated by Nimrod. -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>$title</title>
<style type="text/css">

span.DecNumber {color: blue}
span.BinNumber {color: blue}
span.HexNumber {color: blue}
span.OctNumber {color: blue}
span.FloatNumber {color: blue}
span.Identifier  {color: black}
span.Keyword {font-weight: bold}
span.StringLit {color: blue}
span.LongStringLit {color: blue}
span.CharLit {color: blue}
span.EscapeSequence {color: black}
span.Operator {color: black}
span.Punctation {color: black}
span.Comment, span.LongComment {font-style:italic; color: green}
span.RegularExpression  {color: DarkViolet}
span.TagStart {color: DarkViolet}
span.TagEnd {color: DarkViolet}
span.Key  {color: blue}
span.Value  {color: black}
span.RawData {color: blue}
span.Assembler  {color: blue}
span.Preprocessor {color: DarkViolet}
span.Directive  {color: DarkViolet}
span.Command, span.Rule, span.Hyperlink, span.Label, span.Reference, 
span.Other  {color: black}

div.navigation {
  -moz-border-radius: 5px 5px 5px 5px;
  float: left; 
  width: 30%;
  margin: 0; padding: 0;
  border: 3px outset #7F7F7F;
  background-color: #7F7F7F;
}

div.navigation ul {
  list-style-type: none;
  padding-left: 1em;
}
div.navigation ul li a, div.navigation ul li a:visited {
  font-weight: bold;
  color: #FFFFFF;
  text-decoration: none;
}
div.navigation ul li a:hover {
  font-weight: bold;
  text-decoration: none;
  color: gold;
}

div.content {
  margin-left: 30%;
  padding: 0 1em;
  border-left: 4em;
}

dl.item dd, dl.item dd p {
  margin-top:3px;
}
dl.item dd pre {
  margin-left: 15pt;
  border: 0px;
}
dl.item dt, dl.item dt pre {
  margin:  20pt 0 0 5pt;
}

pre, span.tok {
  background-color: #F9F9F9;
  border-color: #C4C4C4;
  border-style: solid;
  border-width: 1px 1px 1px 2px;
  color: black;
  line-spacing: 110%;
  padding: 2px;
}

span.red {
  color: #A80000;
}

hr {background-color:#9D9D9D; border:0 none; color:#9D9D9D; height:1px; width:100%;}

/*
:Author: David Goodger
:Contact: goodger@python.org
:Date: Date: 2006-05-21 22:44:42 +0200 (Sun, 21 May 2006)
:Revision: Revision: 4564
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th { border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first { margin-top: 0 ! important }
.last, .with-subtitle { margin-bottom: 0 ! important }
.hidden { display: none }
a.toc-backref { text-decoration: none ; color: black }
blockquote.epigraph { margin: 2em 5em ; }
dl.docutils dd { margin-bottom: 0.5em }
div.abstract { margin: 2em 5em }
div.abstract p.topic-title { font-weight: bold ; text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ; border: medium outset ; padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title { font-weight: bold ; font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title { color: red ; font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication { margin: 2em 5em ; text-align: center ; font-style: italic }
div.dedication p.topic-title { font-weight: bold ; font-style: normal }
div.figure { margin-left: 2em ; margin-right: 2em }
div.footer, div.header { clear: both; font-size: smaller }
div.line-block { display: block ; margin-top: 1em ; margin-bottom: 1em }
div.line-block div.line-block { margin-top: 0 ; margin-bottom: 0 ;
  margin-left: 1.5em }
div.sidebar { margin-left: 1em ; border: medium outset ;
  padding: 1em ; background-color: #ffffee ; /*width: 40% ;*/ float: right ;
  clear: right }

div.sidebar p.rubric { font-family: sans-serif ; font-size: medium }
div.system-messages { margin: 5em }
div.system-messages h1 { color: red }
div.system-message { border: medium outset ; padding: 1em }
div.system-message p.system-message-title { color: red ; font-weight: bold }
div.topic { margin: 2em;}
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }
h1.title { text-align: center }
h2.subtitle { text-align: center }
/* hr.docutils { width: 75% } */
img.align-left { clear: left }
img.align-right { clear: right }
ol.simple, ul.simple { margin-bottom: 1em }
ol.arabic { list-style: decimal }
ol.loweralpha { list-style: lower-alpha }
ol.upperalpha { list-style: upper-alpha }
ol.lowerroman { list-style: lower-roman }
ol.upperroman { list-style: upper-roman }
p.attribution { text-align: right ; margin-left: 50% }
p.caption { font-style: italic }
p.credits { font-style: italic ; font-size: smaller }
p.label { white-space: nowrap }
p.rubric { font-weight:bold;font-size:larger;color:maroon;text-align:center}
p.sidebar-title {font-family: sans-serif ;font-weight: bold ;font-size: larger }
p.sidebar-subtitle {font-family: sans-serif ; font-weight: bold }
p.topic-title {
font-weight: bold;
background-color: #6D6D6D;
border-bottom: 1px solid #000000;
border-top: 1px solid black;
color: white;
text-align: center;
margin: 0;
}
pre.address { margin-bottom: 0;margin-top:0;font-family:serif;font-size:100% }
pre.literal-block, pre.doctest-block {margin-left: 2em ;margin-right: 2em }
span.classifier {font-family: sans-serif;font-style: oblique }
span.classifier-delimiter {font-family: sans-serif;font-weight: bold }
span.interpreted {font-family: sans-serif }
span.option {white-space: nowrap }
span.pre {white-space: pre }
span.problematic {color: red }
span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation { border-left: solid 1px gray; margin-left: 1px }
table.docinfo {margin: 2em 4em }
table.docutils {margin-top: 0.5em;margin-bottom: 0.5em; border: 0 solid #9d9d9d; border-collapse: collapse; }
table.footnote {border-left: solid 1px black;margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {padding-left: 0.5em;padding-right: 0.5em;
  vertical-align: top;}

table.docutils td, table.docutils th { border-bottom:1px solid #9D9D9D; }
/* color: #4d4d4d} */

/* table.docutils td:hover, table.docinfo td:hover {color: #000000} */
  

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold;text-align: left;white-space: nowrap;padding-left: 0 }
  
table.docutils th
{
color: black;
font-weight:normal;
background-color: #E3E3E3;
border-top: 1px solid #1d1d1d;
border-bottom: 1px solid #1d1d1d;
}
  
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {font-size: 100% }
ul.auto-toc { list-style-type: none }
/*a.reference { color: #E00000; font-weight:bold;}
a.reference:hover {color: #E00000;background-color: #ffff00;display: margin;
  font-weight:bold;}*/

</style>

</head>
<body>
<div class="document" id="documentId">
<h1 class="title">$title</h1>
$content
<small>Generated: $date $time UTC</small>
</div>
</body>
</html>
"""
pan class="p"></CODE>. David returns <P><PRE>(smil smi sm s sm smi smil) </PRE> <P>to Donna, who has been waiting all this time to evaluate <P><PRE>(se 'smile (downup 'smil) 'smile) </PRE> <P>Her waiting microseconds are over. She hires a <CODE>sentence</CODE> specialist and returns <P><PRE>(smile smil smi sm s sm smi smil smile) </PRE> <P><P> If you have a group of friends whose names all start with &quot;D,&quot; you can try this out yourselves. The rules of the game are pretty simple. Remember that each one of you can have only one single value for <CODE>wd</CODE>. Also, only one of you is in charge of the game at any point. When you hire somebody, that new person is in charge of the game until he or she tells you the answer to his or her question. If some of you have names that don't start with &quot;D,&quot; you can be specialists in <CODE>sentence</CODE> or <CODE>butlast</CODE> or something. Play hard, play fair, nobody hurt. <P> <H2>Tracing</H2> <P>The little-people model explains recursion very well, as long as you're willing to focus your attention on the job of one little person, taking the next little person's subtask as a &quot;black box&quot; that you assume is carried out correctly. Your willingness to make that assumption is a necessary step in becoming truly comfortable with recursive programming. <P>Still, some people are very accustomed to a <EM>sequential</EM> model of computing. In that model, there's only one computer, not a lot of little people, and that one computer has to carry out one step at a time. If you're one of those people, you may find it hard to take the subtasks on faith. You want to know exactly what happens when! There's nothing wrong with such healthy scientific skepticism about recursion. <P>If you're a sequential thinker, you can <EM>trace</EM> procedures to get <A NAME="g7"></A> detailed information about the sequence of events.<A NAME="text1" HREF="convince-recur.html#ft1">[1]</A> But if you're happy with the way we've been talking about recursion up to now, and if you find that this section doesn't contribute to your understanding of recursion, don't worry about it. Our experience shows that this way of thinking helps some people but not everybody.<A NAME="text2" HREF="convince-recur.html#ft2">[2]</A> Before we get to recursive procedures, let's just trace some nonrecursive ones: <P><PRE>(define (double wd) (word wd wd)) &gt; (trace double) &gt; (double 'frozen) <SMALL><CODE>(double frozen) frozenfrozen </CODE></SMALL>FROZENFROZEN </PRE> <P>The argument to <CODE>trace</CODE> specifies a procedure. When you invoke <CODE>trace</CODE>, that procedure becomes &quot;traced&quot;; this means that every time you invoke the procedure, Scheme will print out the name of the procedure and the actual arguments. When the procedure returns a <A NAME="g8"></A> value, Scheme will print that value.<A NAME="text3" HREF="convince-recur.html#ft3">[3]</A> <P>Tracing isn't very interesting if we're just invoking a traced procedure once. But look what happens when we trace a procedure that we're using more than once: <P><PRE>&gt; (double (double (double 'yum))) <SMALL><CODE>(double yum) yumyum (double yumyum) yumyumyumyum (double yumyumyumyum) yumyumyumyumyumyumyumyum </CODE></SMALL> YUMYUMYUMYUMYUMYUMYUMYUM </PRE> <P>This time, there were three separate invocations of <CODE>double</CODE>, and we saw each one as it happened. First we <CODE>double</CODE>d <CODE>yum</CODE>, and the answer was <CODE>yumyum</CODE>. Then we <CODE>double</CODE>d <CODE>yumyum</CODE>, and so on. Finally, after we invoked <CODE>double</CODE> for the last time, its result was printed by the read-eval-print loop. <P> <P>When you're finished investigating a procedure, you can turn off tracing by invoking <A NAME="g9"></A><CODE>untrace</CODE> with the procedure as argument: <P><PRE>&gt; (untrace double) </PRE> <P>Let's try tracing a recursive procedure: <P><PRE>(define (downup wd) (if (= (count wd) 1) (se wd) (se wd (downup (bl wd)) wd))) &gt; (trace downup) &gt; (downup 'trace) <SMALL><CODE>(downup trace) | (downup trac) | | (downup tra) | | | (downup tr) | | | | (downup t) | | | | (t) | | | (tr t tr) | | (tra tr t tr tra) | (trac tra tr t tr tra trac) (trace trac tra tr t tr tra trac trace) </CODE></SMALL>(TRACE TRAC TRA TR T TR TRA TRAC TRACE) </PRE> <P>When a procedure calls itself recursively, depending on the <A NAME="g10"></A><A NAME="g11"></A>phase of the moon,<A NAME="text4" HREF="convince-recur.html#ft4">[4]</A> Scheme may indent the trace display to show the levels of procedure calling, and draw a line of vertical bars (&quot;<CODE>|</CODE>&quot;) from a procedure's invocation to its return value below. This is so you can look at a procedure invocation and see what value it returned, or vice versa. <P>How does the trace help us understand what is going on in the recursion? First, by reading the trace results from top to bottom, you can see the actual sequence of events when the computer is carrying out your Scheme program. For example, you can see that we start trying to figure out <CODE>(downup 'trace)</CODE>; the first thing printed is the line that says we're starting that computation. But, before we get a result from that, four more <CODE>downup</CODE> computations have to begin. The one that begins last finishes first, returning <CODE>(t)</CODE>; then another one returns a value; the one that started first is the last to return. <P>You can also read the trace horizontally instead of vertically, focusing on the levels of indentation. If you do this, then instead of a sequence of independent events (such-and-such starts, such-and-such returns a value) you see the <EM>inclusion</EM> of processes within other ones. The smallest <CODE>downup</CODE> invocation is entirely inside the next-smallest one, and so on. The initial invocation of <CODE>downup</CODE> includes all of the others. <P>Perhaps you're thinking that <CODE>downup</CODE>'s pattern of inclusion is the only one possible for recursive procedures. That is, perhaps you're thinking that every invocation includes exactly one smaller invocation, and <EM>that</EM> one includes a yet-smaller one, and so on. But actually the pattern can be more complicated. Here's an example. The <EM><A NAME="g12"></A><A NAME="g13"></A>Fibonacci numbers</EM> are a sequence of numbers in which the first two numbers are 1 and each number after that is the sum of the two before it: <P><CENTER>1, 1, 2, 3, 5, 8, 13, 21, 34, 55, ...</CENTER> <P> (They're named after <A NAME="g14"></A>Leonardo Pisano. You'd think they'd be called &quot;Pisano numbers,&quot; but Leonardo had a kind of alias, Leonardo Fibonacci, just to confuse people.) Here's a procedure to compute the <EM>n</EM>th Fibonacci number: <P><PRE>(define (<A NAME="g15"></A>fib n) (if (&lt;= n 2) 1 (+ (fib (- n 1)) (fib (- n 2))))) </PRE> <P>Here's a trace of computing the fourth Fibonacci number: <PRE>&gt; (fib 4) <SMALL><CODE>(fib 4) | (fib 2) | 1 | (fib 3) | | (fib 1) | | 1 | | (fib 2) | | 1 | 2 3 </CODE></SMALL>3 </PRE> <P>(By the way, this trace demonstrates that in the dialect of Scheme we used, the argument subexpressions of the <CODE>+</CODE> expression in <CODE>fib</CODE> are evaluated from right to left, because the smaller <CODE>fib</CODE> arguments come before the larger ones in the trace.) <P>As you can see, we still have invocations within other invocations, but the pattern is not as simple as in the <CODE>downup</CODE> case. If you're having trouble making sense of this pattern, go back to thinking about the problem in terms of little people; who hires whom? <P> <P><H2>Pitfalls</H2> <P>Whenever you catch yourself using the words &quot;go back&quot; or &quot;goes back&quot; in describing how some procedure works, bite your tongue. A recursive invocation isn't a going back; it's a separate process. The model behind &quot;go back&quot; is that the same little person starts over again at the beginning of the procedure body. What actually happens is that a new little person carries out the same procedure. It's an important difference because when the second little person finishes, the first may still have more work to do. <P>For example, when we used little people to show the working of <CODE>downup</CODE>, Dennis computes the result <CODE>(smi sm s sm smi)</CODE> and returns that value to David; at that point, David still has work to do before returning his own result to Donna. <P>The <CODE>trace</CODE> mechanism doesn't work for <A NAME="g16"></A><A NAME="g17"></A>special forms. For example, you can't say <P><PRE>(trace or) </PRE> <P>although you can, and often will, trace primitive procedures that aren't special forms. <P><H2>Boring Exercises</H2> <P><B>13.1</B>&nbsp;&nbsp;Trace the <CODE>explode</CODE> procedure from page <A HREF="../ssch11/recursion.html#explodepage">there</A> and invoke <P><PRE>(explode 'ape) </PRE> <P>How many recursive calls were there? What were the arguments to each recursive call? Turn in a transcript showing the <CODE>trace</CODE> listing. <P> <B>13.2</B>&nbsp;&nbsp;How many <CODE>pigl</CODE>-specialist little people are involved in evaluating the following expression? <P><PRE>(pigl 'throughout) </PRE> <P>What are their arguments and return values, and to whom does each give her result? <P> <B>13.3</B>&nbsp;&nbsp;Here is our first version of <CODE>downup</CODE> from Chapter 11. It doesn't work because it has no base case. <P><PRE>(define (downup wd) (se wd (downup (bl wd)) wd)) &gt; (downup 'toe) ERROR: Invalid argument to BUTLAST: &quot;" </PRE> <P>Explain what goes wrong to generate that error. In particular, why does Scheme try to take the <CODE>butlast</CODE> of an empty word? <P> <B>13.4</B>&nbsp;&nbsp;Here is a Scheme procedure that never finishes its job: <P><PRE>(define (forever n) (if (= n 0) 1 (+ 1 (forever n)))) </PRE> <P>Explain why it doesn't give any result. (If you try to trace it, make sure you know how to make your version of Scheme stop what it's doing and give you another prompt.) <P> <H2>Real Exercises</H2> <P><B>13.5</B>&nbsp;&nbsp;It may seem strange that there is one little person per <EM>invocation</EM> of a procedure, instead of just one little person per procedure. For certain problems, the person-per-procedure model would work fine. <P>Consider, for example, this invocation of <CODE>pigl</CODE>: <P><PRE>&gt; (pigl 'prawn) AWNPRAY </PRE> <P>Suppose there were only one <CODE>pigl</CODE> specialist in the computer, named Patricia. Alonzo hires Patricia and gives her the argument <CODE>prawn</CODE>. She sees that it doesn't begin with a vowel, so she moves the first letter to the end, gets <CODE>rawnp</CODE>, and tries to <CODE>pigl</CODE> that. Again, it doesn't begin with a vowel, so she moves another letter to the end and gets <CODE>awnpr</CODE>. That <EM>does</EM> begin with a vowel, so she adds an <CODE>ay</CODE>, returning <CODE>awnpray</CODE> to Alonzo. <P>Nevertheless, this revised little-people model doesn't always work. Show how it fails to explain what happens in the evaluation of <P><PRE>(downup 'smile) </PRE> <P> <B>13.6</B>&nbsp;&nbsp;As part of computing <CODE>(factorial 6)</CODE>, Scheme computes <CODE>(factorial 2)</CODE> and gets the answer <CODE>2</CODE>. After Scheme gets that answer, how does it know what to do next? <P> <HR> <A NAME="ft1" HREF="convince-recur.html#text1">[1]</A> Unfortunately, <CODE>trace</CODE> isn't part of the Scheme standard, so it doesn't behave the same way in every version of Scheme.<P> <A NAME="ft2" HREF="convince-recur.html#text2">[2]</A> Even if tracing doesn't help you with recursion, you'll find that it's a useful technique in debugging any procedure.<P> <A NAME="ft3" HREF="convince-recur.html#text3">[3]</A> In this example the return value was printed twice, because the procedure we traced was invoked directly at the Scheme prompt. Its return value would have been printed once anyway, just because that's what Scheme always does. It was printed another time because of the tracing. In this book we've printed the trace-specific output in smaller type and lower-case to help you understand which is what, but of course on the actual computer you're on your own.<P> <A NAME="ft4" HREF="convince-recur.html#text4">[4]</A> That's computer science slang for &quot;depending on a number of factors that I consider too complicated to bother explaining&quot; or &quot;depending on a number of factors that I don't understand myself.&quot; Some computer systems automatically print the phase of the moon on program listings as an aid for programmers with &quot;POM-dependent&quot; programs. What we meant in this case is that it depends both on your version of Scheme and on the exact form of your recursive procedure.<P> <P><A HREF="../ss-toc2.html">(back to Table of Contents)</A><P> <A HREF="../ssch12/leap.html"><STRONG>BACK</STRONG></A> chapter thread <A HREF="../ssch14/recur-patterns.html"><STRONG>NEXT</STRONG></A> <P> <ADDRESS> <A HREF="../index.html">Brian Harvey</A>, <CODE>bh@cs.berkeley.edu</CODE> </ADDRESS> </BODY> </HTML>