-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy pathLPexample.html
More file actions
59 lines (59 loc) · 23.7 KB
/
LPexample.html
File metadata and controls
59 lines (59 loc) · 23.7 KB
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
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=0.8"/><title>Literate Programming Example</title><link rel="stylesheet" type="text/css" href="scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="racket.css" title="default"/><link rel="stylesheet" type="text/css" href="manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="manual-racket.css" title="default"/><script type="text/javascript" src="scribble-common.js"></script><script type="text/javascript" src="manual-racket.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="scribble-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">►</a></td><td></td><td><a href="" class="tocviewselflink" data-pltdoc="x">Literate Programming Example</a></td></tr></table></div><div class="tocviewsublistonly" style="display: none;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="#%28part._.Introduction%29" class="tocviewlink" data-pltdoc="x">Introduction</a></td></tr><tr><td align="right">2 </td><td><a href="#%28part._.How_to_.Do_.It%29" class="tocviewlink" data-pltdoc="x">How to Do It</a></td></tr><tr><td align="right">3 </td><td><a href="#%28part._.Weaving__or_.Producing_.Documentation%29" class="tocviewlink" data-pltdoc="x">Weaving, or Producing Documentation</a></td></tr><tr><td align="right">4 </td><td><a href="#%28part._.Resolving_.External_.References%29" class="tocviewlink" data-pltdoc="x">Resolving External References</a></td></tr><tr><td align="right">5 </td><td><a href="#%28part._.Tangling%29" class="tocviewlink" data-pltdoc="x">Tangling</a></td></tr><tr><td align="right">6 </td><td><a href="#%28part._.Including_.Other_.Files%29" class="tocviewlink" data-pltdoc="x">Including Other Files</a></td></tr><tr><td align="right">7 </td><td><a href="#%28part._.Conclusions%29" class="tocviewlink" data-pltdoc="x">Conclusions</a></td></tr></table></div></div></div><div class="tocsub"><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber"></span><a href="#%28part._.Literate_.Programming_.Example%29" class="tocsubseclink" data-pltdoc="x">Literate Programming Example</a></td></tr><tr><td><span class="tocsublinknumber">1<tt> </tt></span><a href="#%28part._.Introduction%29" class="tocsubseclink" data-pltdoc="x">Introduction</a></td></tr><tr><td><span class="tocsublinknumber">2<tt> </tt></span><a href="#%28part._.How_to_.Do_.It%29" class="tocsubseclink" data-pltdoc="x">How to Do It</a></td></tr><tr><td><span class="tocsublinknumber">3<tt> </tt></span><a href="#%28part._.Weaving__or_.Producing_.Documentation%29" class="tocsubseclink" data-pltdoc="x">Weaving, or Producing Documentation</a></td></tr><tr><td><span class="tocsublinknumber">4<tt> </tt></span><a href="#%28part._.Resolving_.External_.References%29" class="tocsubseclink" data-pltdoc="x">Resolving External References</a></td></tr><tr><td><span class="tocsublinknumber">5<tt> </tt></span><a href="#%28part._.Tangling%29" class="tocsubseclink" data-pltdoc="x">Tangling</a></td></tr><tr><td><span class="Smaller"><a href="#%28elem._%28chunk._~3cexample_main~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><example_main></a></span></td></tr><tr><td><span class="Smaller"><a href="#%28elem._%28chunk._~3cexample_import.Export~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><example_importExport></a></span></td></tr><tr><td><span class="Smaller"><a href="#%28elem._%28chunk._~3cblue_square~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><blue_square></a></span></td></tr><tr><td><span class="Smaller"><a href="#%28elem._%28chunk._~3cexample_body~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><example_body></a></span></td></tr><tr><td><span class="tocsublinknumber">6<tt> </tt></span><a href="#%28part._.Including_.Other_.Files%29" class="tocsubseclink" data-pltdoc="x">Including Other Files</a></td></tr><tr><td><span class="tocsublinknumber">7<tt> </tt></span><a href="#%28part._.Conclusions%29" class="tocsubseclink" data-pltdoc="x">Conclusions</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="versionNoNav">7.2</span></div><h2><a name="(part._.Literate_.Programming_.Example)"></a>Literate Programming Example</h2><p>You are looking at the results of recent experiments with Literate
Programming in Racket. The name of the file you’re reading is
<span class="RktSym">LPexample.scrbl</span><span class="RktMeta"></span>. It’s a wrapper around the real substance of
this program, which is in the included file <span class="RktSym">LPexample.rkt</span><span class="RktMeta"></span>.</p><p><span class="RktMeta">LPexample.rkt</span> is the source file for this document. The Github repository
is <a href="https://github.com/brudgers/LiterateProgrammingExample">here</a>.</p><h3>1<tt> </tt><a name="(part._.Introduction)"></a>Introduction</h3><p>Racket’s <a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="http://docs.racket-lang.org/scribble/lp.html#%28mod-path._scribble%2Flp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp</span></a><span class="RktMeta"></span> and <a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="http://docs.racket-lang.org/scribble/lp.html#%28mod-path._scribble%2Flp2%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp2</span></a><span class="RktMeta"></span> let us write
programs in the <span style="font-style: italic">Literate Programming Idiom</span>. In that idiom, we write
<span style="font-style: italic">documents about our code</span>, presented in an order convenient for humans.
Automated tools rearrange or <span style="font-style: italic">tangle</span> the code up into an order convenient
for the computer. Only with literate programming do you have complete freedom to
refer to things before you define them or define them before you refer to them
in whatever order makes it easiest for you to explain to other humans and for
those humans to understand what you write.</p><h3>2<tt> </tt><a name="(part._.How_to_.Do_.It)"></a>How to Do It</h3><p>Racket’s official documentation on <a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="http://docs.racket-lang.org/scribble/lp.html#%28mod-path._scribble%2Flp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp</span></a><span class="RktMeta"></span> and <a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="http://docs.racket-lang.org/scribble/lp.html#%28mod-path._scribble%2Flp2%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp2</span></a><span class="RktMeta"></span> is not very clear, however, and that’s not surprising: racket’s
official documentation is sometimes lacking for features outside the core or for
topics between the very basic and detailed reference.</p><p>You can do two different things with a literate program: <span style="font-style: italic">tangle</span> it or
<span style="font-style: italic">weave</span> it. Tangling a literate program means either just running it or
spreading its code out on disk in a structure convenient for build tools.
Weaving a literate program means rendering it to <span class="RktMeta">HTML</span>, <span class="RktMeta">LaTeX</span>, or
<span class="RktMeta">PDF</span>, specifically for human consumption.</p><p>Because we want to <span style="font-style: italic">run</span> our programs, we must use the file extension
<span class="RktMeta">.rkt</span>, not <span class="RktMeta">.scrbl</span>, for literate programs. You can run this here
<span class="RktMeta">.rkt</span>, the one you’re reading right now, by typing</p><p><span class="hspace"> </span><span class="stt">racket LPexample.rkt</span></p><p>at the command line, or by clicking the “Run” button when you have the file
open in the DrRacket GUI. It’s probably better to run the program in the GUI
because the program draws pictures that you can’t see in the command line, but
it’s fine either way.</p><h3>3<tt> </tt><a name="(part._.Weaving__or_.Producing_.Documentation)"></a>Weaving, or Producing Documentation</h3><p>Racket’s <span class="RktMeta">scribble</span> command does weaving. You can</p><p><span class="hspace"> </span><span class="stt">scribble --pdf LPexample.rkt</span></p><p>if you want to do, but the result is ugly. It’s much better to wrap this
<span class="RktMeta">.rkt</span> file in a <span class="RktMeta">.scrbl</span> file written in either <a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="http://docs.racket-lang.org/scribble/base.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/base</span></a><span class="RktMeta"></span> or <a href="http://docs.racket-lang.org/guide/Module_Syntax.html#%28part._hash-lang%29" class="RktModLink" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="RktMeta"></span><span class="hspace"> </span><span class="RktMeta"></span><a href="http://docs.racket-lang.org/scribble/manual.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/manual</span></a><span class="RktMeta"></span>, both of which make pretty
output. The <span class="RktMeta">.scrbl</span> wrapper should be very basic:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">#lang scribble/manual</span></p></td></tr><tr><td><p><span class="stt">@(require(for-label 2htdp/image))</span></p></td></tr><tr><td><p><span class="stt">@require[scribble/lp-include]</span></p></td></tr><tr><td><p><span class="stt">@title{Literate Programming Example}</span></p></td></tr><tr><td><p><span class="stt">You are looking at the results of recent experiments with Literate</span></p></td></tr><tr><td><p><span class="stt">Programming in Racket. The name of the file you're reading is</span></p></td></tr><tr><td><p><span class="stt">@code{LPexample.scrbl}. It's a wrapper around the real substance of</span></p></td></tr><tr><td><p><span class="stt">this program, which is in the included file @code{LPexample.rkt}.</span></p></td></tr><tr><td><p><span class="stt">@lp-include["LPexample.rkt"]</span></p></td></tr></table></p><p>To weave <span class="RktMeta">LPexample.rkt</span>, run the <span class="RktMeta">scribble</span> command on its wrapper
<span class="RktMeta">.scrbl</span> file.</p><p><span class="hspace"> </span><span class="stt">scribble --pdf LPexample.scrbl</span></p><p>makes a <span class="RktMeta">PDF</span> version, and</p><p><span class="hspace"> </span><span class="stt">scribble --html +m --redirect-main http://docs.racket-lang.org/ LPexample.scrbl</span></p><p>makes a <span class="RktMeta">HTML</span> version.</p><h3>4<tt> </tt><a name="(part._.Resolving_.External_.References)"></a>Resolving External References</h3><p>Notice the first two <span class="RktMeta">require</span> lines in the <span class="RktMeta">.scrbl</span> wrapper file.</p><p>The first is <span class="RktPn">(</span><span class="RktMeta">require</span><span class="RktPn">(</span><span class="RktMeta">for-label</span><span class="hspace"> </span><span class="RktMeta">2htdp/image</span><span class="RktPn">)</span><span class="RktPn">)</span><span class="RktMeta"></span>, which sets the
<span style="font-style: italic">documentation-phase</span> references. The <span style="font-style: italic">documentation phase</span> is
analogous to the macro-expansion phase in Racket and other Lisps: it just
rewrites source code rather than compiling it.</p><p>The second is <span class="RktMeta">require</span><span class="RktPn">[</span><span class="RktMeta">scribble/lp-include</span><span class="RktPn">]</span><span class="RktMeta"></span>, which empowers the weaver,
<span class="RktMeta">scribble</span>, to include more files.</p><h3>5<tt> </tt><a name="(part._.Tangling)"></a>Tangling</h3><p>A <span class="RktMeta">scribble/lp</span> or <span class="RktMeta">scribble/lp2</span> file, with <span class="RktMeta">.rkt</span> extension,
contains both the code for <span style="font-style: italic">tangling</span> and the text for
<span style="font-style: italic">weaving</span> into a document. Write code in <span class="RktMeta">chunks</span>, like this:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">@chunk[<example_main></span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt"><example_importExport></span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt"><example_body>]</span></p></td></tr></table></p><p>Weaving with <span class="RktMeta">scribble</span> makes that chunk look pretty:</p><p><div class="SIntrapara"><a name="(elem._(chunk._~3cexample_main~3e~3a1))"></a><span style="font-weight: bold"><span style="font-style: italic"><a href="#%28elem._%28chunk._~3cexample_main~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><example_main></a></span> ::=</span></div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><a href="#%28elem._%28chunk._~3cexample_import.Export~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><example_importExport></a></td></tr><tr><td><a href="#%28elem._%28chunk._~3cexample_body~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><example_body></a></td></tr></table></blockquote></div></p><p>The first line in any <span class="RktMeta">chunk</span> form is the globally unique name of the chunk
you’re defining, wrapped in angle brackets. The rest of the lines in a chunk
are either references (in angle brackets) to other chunks, or literal
code, as seen below.</p><p>Because <span class="RktMeta"><example_main></span> is the first chunk in the <span class="RktMeta">.rkt</span> file, Racket
treats it as the <span style="font-style: italic">main chunk</span>. That fact is mentioned briefly near the
bottom of the
<a href="http://docs.racket-lang.org/scribble/lp.html"><span class="RktMeta">scribble/lp</span>
documentation</a>. If you don’t want the first <span class="RktMeta">chunk</span> to be the main chunk,
then, anywhere in the document write a chunk with the special name <span class="RktMeta"><*></span>:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">@chunk[<*></span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt"><example_importExport></span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt"><example_body>]</span></p></td></tr></table></p><p>That will be the main chunk. You may have zero or one chunks named <span class="RktMeta"><*></span>.
If you have zero, then the first chunk in the file is the main chunk. If you
have one, then none of your chunks depend on position, and that’s a nice property.</p><p>In any event, with literate programming, you present your code in an order
convenient for humans. You may define before referring, or you may refer before
defining. Non-literate programming doesn’t let you refer before defining, usually.</p><p>Tangling puts code in the order required for the compiler or interpreter, that
is, for Racket. For instance, Racket needs <span class="RktMeta">require</span> and <span class="RktMeta">provide</span>
statements near the top, and either of <span class="RktMeta">main-chunk</span> forms above references
a certain chunk named <span class="RktMeta"><example_importExport></span> before all other references.
That chunk contains literal code for the <span class="RktMeta">require</span> and <span class="RktMeta">provide</span>
statements. You may position the definition of that chunk anywhere you like
inside the <span class="RktMeta">.rkt</span> file. Let’s define it now. You write:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">@chunk[<example_importExport></span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">(require 2htdp/image)</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">(provide (all-defined-out))]</span></p></td></tr></table></p><p>and the weaver, <span class="RktMeta">scribble</span>, makes it pretty:</p><p><div class="SIntrapara"><a name="(elem._(chunk._~3cexample_import.Export~3e~3a1))"></a><span style="font-weight: bold"><span style="font-style: italic"><a href="#%28elem._%28chunk._~3cexample_import.Export~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><example_importExport></a></span> ::=</span></div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym">require</span><span class="hspace"> </span><span class="RktSym">2htdp/image</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym">provide</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">all-defined-out</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote></div></p><p>In that example, we referred to the chunk named <span class="RktMeta"><example_importExport>></span>
before we defined it. Now, let’s define one before we use it. You write:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">@chunk[<blue_square></span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">(rectangle 100 100 "solid" "blue")</span></p></td></tr></table></p><p>and the weaver makes it pretty:</p><p><div class="SIntrapara"><a name="(elem._(chunk._~3cblue_square~3e~3a1))"></a><span style="font-weight: bold"><span style="font-style: italic"><a href="#%28elem._%28chunk._~3cblue_square~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><blue_square></a></span> ::=</span></div><div class="SIntrapara"><blockquote class="SCodeFlow"><p><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/teachpack/2htdpimage.html#%28def._%28%28lib._2htdp%2Fimage..rkt%29._rectangle%29%29" class="RktValLink" data-pltdoc="x">rectangle</a></span><span class="hspace"> </span><span class="RktVal">100</span><span class="hspace"> </span><span class="RktVal">100</span><span class="hspace"> </span><span class="RktVal">"solid"</span><span class="hspace"> </span><span class="RktVal">"blue"</span><span class="RktPn">)</span></p></blockquote></div></p><p>Now, compose <span class="RktMeta"><blue_square></span> into another code block. You write:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="stt">@chunk[<example_body></span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">(beside/align "bottom"</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt">(ellipse 20 70 "solid" "lightsteelblue")</span></p></td></tr><tr><td><p><span class="stt"></span><span class="hspace"> </span><span class="stt"><blue_square>)]</span></p></td></tr></table></p><p>and the weaver makes it pretty:</p><p><div class="SIntrapara"><a name="(elem._(chunk._~3cexample_body~3e~3a1))"></a><span style="font-weight: bold"><span style="font-style: italic"><a href="#%28elem._%28chunk._~3cexample_body~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><example_body></a></span> ::=</span></div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/teachpack/2htdpimage.html#%28def._%28%28lib._2htdp%2Fimage..rkt%29._beside%2Falign%29%29" class="RktValLink" data-pltdoc="x">beside/align</a></span><span class="hspace"> </span><span class="RktVal">"bottom"</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://docs.racket-lang.org/teachpack/2htdpimage.html#%28def._%28%28lib._2htdp%2Fimage..rkt%29._ellipse%29%29" class="RktValLink" data-pltdoc="x">ellipse</a></span><span class="hspace"> </span><span class="RktVal">20</span><span class="hspace"> </span><span class="RktVal">70</span><span class="hspace"> </span><span class="RktVal">"solid"</span><span class="hspace"> </span><span class="RktVal">"lightsteelblue"</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><a href="#%28elem._%28chunk._~3cblue_square~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><blue_square></a><span class="RktPn">)</span></td></tr></table></blockquote></div></p><h3>6<tt> </tt><a name="(part._.Including_.Other_.Files)"></a>Including Other Files</h3><p>You can include text for weaving in side files. The text you’re reading right
now is stored in a file named <span class="RktVal">"milk.rkt"</span><span class="RktMeta"></span>. I have found that chunks
defined in such files do not compose properly into the chunks in your primary
file, so it’s not clear how to build up big programs from lots of little files.
We’ll worry about that in the future.</p><h3>7<tt> </tt><a name="(part._.Conclusions)"></a>Conclusions</h3><p><div class="SIntrapara">The two items which required teasing out from the documentation are:
</div><div class="SIntrapara"><ul><li><p>Weaving requires a second file where a file with a <span class="RktMeta">.rkt</span>
file extension is referenced using <span class="RktMeta">lp-include</span>.</p></li><li><p>Tangling treats the first chunk differently unless the <span class="RktMeta"><*></span> special name is used.</p></li></ul></div></p><p>Happy Literate Programming, Ben.</p><p>Update: 13/12/19 - broken links issue fixed and documented thanks to
StackOverflow user Asumu Takikawa.</p></div></div><div id="contextindicator"> </div></body></html>