-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathLPexample.html
7 lines (7 loc) · 17 KB
/
LPexample.html
1
2
3
4
5
6
7
<!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" /><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="scribble-style.css" title="default" /><script type="text/javascript" src="scribble-common.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" style="margin-bottom: 1em;"><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._.Weaving%29" class="tocviewlink" data-pltdoc="x">Weaving</a></td></tr><tr><td align="right">3 </td><td><a href="#%28part._.Tangling%29" class="tocviewlink" data-pltdoc="x">Tangling</a></td></tr><tr><td align="right">4 </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">1<tt> </tt></span><a href="#(part._.Introduction)" class="tocsubseclink" data-pltdoc="x">Introduction</a></td></tr><tr><td><span class="tocsublinknumber">2<tt> </tt></span><a href="#(part._.Weaving)" class="tocsubseclink" data-pltdoc="x">Weaving</a></td></tr><tr><td><span class="tocsublinknumber">3<tt> </tt></span><a href="#(part._.Tangling)" 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">4<tt> </tt></span><a href="#(part._.Conclusions)" class="tocsubseclink" data-pltdoc="x">Conclusions</a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="versionNoNav">5.3.6</span></div><h2><a name="(part._.Literate_.Programming_.Example)"></a>Literate Programming Example</h2><p>This is the result of my recent research on Literate Programming in Racket. The name of this file is <span class="RktSym">LPexample.scrbl</span><span class="RktMeta"></span>. Initially, I struggled with broken links, but that problem has been solved.</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 <span class="RktMeta">scribble/lp</span> language allows programs to be written in the Literate Programming Idiom. The documentation, however, is not very clear. This should not be particularly surprising because Racket’s documentation is sometimes lacking when it comes to features outside the core and when something between very basic material and detailed reference is needed.</p><h3>2<tt> </tt><a name="(part._.Weaving)"></a>Weaving</h3><p>The process of weaving is where <span class="RktMeta">scribble/lp</span> is a bit confusing. Unlike documents in <span class="RktMeta">scribble/base</span> or <span class="RktMeta">scribble/manual</span>, documents written in <span class="RktMeta">scribble/lp</span> cannot be directly rendered to <span class="RktMeta">HTML</span> or <span class="RktMeta">LaTeX</span>. This is why DrRacket does not provide "the easy button" when it sees a <span class="RktMeta">scribble/lp</span> document.</p><p>Documents written using <span class="RktMeta">#lang</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> use the file extension <span class="RktMeta">.rkt</span> not <span class="RktMeta">.scrbl</span>.</p><p><div class="SIntrapara">This means that a Racket Literate Program requires a second document written in either <span class="RktMeta">scribble/base</span> or <span class="RktMeta">scribble/manual</span>. This can be very basic:
</div><div class="SIntrapara"><table cellspacing="0"><tr><td><p><span class="stt"><span class="stt">@(require(for-label 2htdp/image))</span></span></p></td></tr><tr><td><p><span class="stt"><span class="stt">@require[scribble/lp-include]</span></span></p></td></tr><tr><td><p><span class="stt"><span class="stt">@title{Literate Programming Example}</span></span></p></td></tr><tr><td><p><span class="stt"><span class="stt">This is the result of my recent research on Literate Programming in Racket. The name of this file is @code{LPexample.scrbl}. It's not perfect as I still have not solved the problem of broken links, but I'm working on it.</span></span></p></td></tr><tr><td><p><span class="stt"><span class="stt">@lp-include["LPexample.rkt"]</span></span></p></td></tr></table></div></p><p>The file for weaving has a file extension of <span class="RktMeta">.scrbl</span>. To weave <span class="RktMeta">LPexample.rkt</span> we run the <span class="RktMeta">scribble</span> command on its corresponding <span class="RktMeta">.scrbl</span> file. In this case: <span class="RktMeta">LPexample.scrbl</span>.</p><p>Resolving the external references has two parts.</p><ul><li><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> in Racket is analogous to the expansion phase for macros in Racket and other Lisps in that it just focuses on modifying the source code rather than compiling it.</p></li><li><p><div class="SIntrapara">The second step is calling the scribble command with the appropriate flags. The command to weave this document is: </div><div class="SIntrapara"><span class="hspace"> </span><span class="stt">scribble --html +m --redirect-main http://docs.racket-lang.org/ LPexample.scrbl</span></div></p></li></ul><h3>3<tt> </tt><a name="(part._.Tangling)"></a>Tangling</h3><p><div class="SIntrapara">A <span class="RktMeta">scribble/lp</span> file contains both the code for <span style="font-style: italic">tangling</span> into a program or library and the text for <span style="font-style: italic">weaving</span> into a document. Like its parent <span class="RktMeta">scribble</span>, <span class="RktMeta">scribble/lp</span> allows direct input of text. The code to be tangled is delineated:
</div><div class="SIntrapara"><table cellspacing="0"><tr><td><p><span class="stt"><span class="stt">@chunk[<example_main></span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt"><example_requires></span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt"><example_exports></span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt"><example_body>]</span></span></p></td></tr></table></div></p><p>Which matches the source for this output from the weaving process:</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" 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><div class="SIntrapara">Because this is the first </div><div class="SIntrapara"><table cellspacing="0"><tr><td><p><span class="stt"><span class="stt">@chunk</span></span></p></td></tr></table></div><div class="SIntrapara"> it is treated as the <span style="font-style: italic">main chunk</span>. This 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 </div><div class="SIntrapara"><table cellspacing="0"><tr><td><p><span class="stt"><span class="stt">@chunk</span></span></p></td></tr></table></div><div class="SIntrapara"> to serve as the main chunk, then:</div></p><p><table cellspacing="0"><tr><td><p><span class="stt"><span class="stt">@chunk[<*></span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt"><example_requires></span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt"><example_exports></span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt"><example_body>]</span></span></p></td></tr></table></p><p>can be placed anywhere in the document to serve as the main chunk. Having tried it, it really doesn’t add anything for clarity and is unnecessary.</p><p>The reason it is unnecessary is that tangling can entail composing the code in a sequence other than what would normally be used in a <span class="RktMeta">#lang</span><span class="hspace"> </span><span class="RktMeta"></span><a href="http://docs.racket-lang.org/reference/index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">racket</span></a><span class="RktMeta"></span> program. For example, required modules need not be near the top. This chunk:</p><p><table cellspacing="0"><tr><td><p><span class="stt"><span class="stt">@chunk[<example_importExport></span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt">(require 2htdp/image)</span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt">(provide (all-defined-out))]</span></span></p></td></tr></table></p><p>produces, this output from the weaving process:</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" 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><div class="SIntrapara">As shown in the example, source chunks like this:
</div><div class="SIntrapara"><table cellspacing="0"><tr><td><p><span class="stt"><span class="stt">@chunk[<blue_square></span></span></p></td></tr><tr><td><p><span class="stt"><span class="stt">(rectangle 100 100 "solid" "blue")</span></span></p></td></tr></table></div></p><p>which weaves to this:</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><div class="SIntrapara">can be composed into other functions this way:
</div><div class="SIntrapara"><table cellspacing="0"><tr><td><p><span class="stt"><span class="stt">@chunk[<blue_square></span></span></p></td></tr><tr><td><p><span class="stt"><span class="stt">(beside/align "bottom"</span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt">(ellipse 20 70 "solid" "lightsteelblue")</span></span></p></td></tr><tr><td><p><span class="stt"><span class="hspace"> </span><span class="stt"><blue_square>)]</span></span></p></td></tr></table></div></p><p>which weaves out to:</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" 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>4<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>