/usr/share/doc/racket/scribble/lp.html is in racket-doc 6.1-4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <!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>5 Literate Programming</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="lp.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"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-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="index.html" class="tocviewlink" data-pltdoc="x">Scribble:<span class="mywbr"> </span> The Racket Documentation Tool</a></td></tr></table></div><div class="tocviewsublisttop" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="getting-started.html" class="tocviewlink" data-pltdoc="x">Getting Started</a></td></tr><tr><td align="right">2 </td><td><a href="reader.html" class="tocviewlink" data-pltdoc="x">@ Syntax</a></td></tr><tr><td align="right">3 </td><td><a href="generic-prose.html" class="tocviewlink" data-pltdoc="x">High-<wbr></wbr>Level Scribble API</a></td></tr><tr><td align="right">4 </td><td><a href="plt-manuals.html" class="tocviewlink" data-pltdoc="x">Scribbling Documentation</a></td></tr><tr><td align="right">5 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Literate Programming</a></td></tr><tr><td align="right">6 </td><td><a href="internals.html" class="tocviewlink" data-pltdoc="x">Low-<wbr></wbr>Level Scribble API</a></td></tr><tr><td align="right">7 </td><td><a href="running.html" class="tocviewlink" data-pltdoc="x">Running <span class="stt">scribble</span></a></td></tr><tr><td align="right"></td><td><a href="doc-index.html" class="tocviewlink" data-pltdoc="x">Index</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>5 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Literate Programming</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">5.1 </td><td><a href="#%28part._scribble_lp_.Language%29" class="tocviewlink" data-pltdoc="x"><span class="RktModLink"><span class="RktSym">scribble/<span class="mywbr"> </span>lp</span></span> Language</a></td></tr><tr><td align="right">5.2 </td><td><a href="#%28part._scribble_lp-include_.Module%29" class="tocviewlink" data-pltdoc="x"><span class="RktModLink"><span class="RktSym">scribble/<span class="mywbr"> </span>lp-<wbr></wbr>include</span></span> Module</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="Smaller"><a href="#%28elem._%28chunk._~3cf~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><f></a></span></td></tr><tr><td><span class="Smaller"><a href="#%28elem._%28chunk._~3cfs-body~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><fs-body></a></span></td></tr><tr><td><span class="tocsublinknumber">5.1<tt> </tt></span><a href="#%28part._scribble_lp_.Language%29" class="tocsubseclink" data-pltdoc="x"><span class="RktModLink"><span class="RktSym">scribble/<span class="mywbr"> </span>lp</span></span> Language</a></td></tr><tr><td><a href="#%28form._%28%28lib._scribble%2Flp..rkt%29._chunk%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktStxLink">chunk</span></span></a></td></tr><tr><td><a href="#%28form._%28%28lib._scribble%2Flp..rkt%29._.C.H.U.N.K%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktStxLink">CHUNK</span></span></a></td></tr><tr><td><span class="tocsublinknumber">5.2<tt> </tt></span><a href="#%28part._scribble_lp-include_.Module%29" class="tocsubseclink" data-pltdoc="x"><span class="RktModLink"><span class="RktSym">scribble/<span class="mywbr"> </span>lp-<wbr></wbr>include</span></span> Module</a></td></tr><tr><td><a href="#%28form._%28%28lib._scribble%2Flp-include..rkt%29._lp-include%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktStxLink">lp-<wbr></wbr>include</span></span></a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="Compatibility_Libraries.html" title="backward to "4.8 Compatibility Libraries"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Scribble: The Racket Documentation Tool"" data-pltdoc="x">up</a> <a href="internals.html" title="forward to "6 Low-Level Scribble API"" data-pltdoc="x">next →</a></span> </div><h3 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""lp"">5<tt> </tt><a name="(part._lp)"></a>Literate Programming</h3><p>Programs written using <a href="#%28mod-path._scribble%2Flp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp</span></a> are simultaneously
two things: a program and a document describing the program.</p><p>Programs in <a href="#%28mod-path._scribble%2Flp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp</span></a> are viewed in two different
ways, either by running the program directly or by including it with
<span class="RktSym"><a href="#%28form._%28%28lib._scribble%2Flp-include..rkt%29._lp-include%29%29" class="RktStxLink" data-pltdoc="x">lp-include</a></span>. When running the program, all of the
<span class="RktSym"><a href="#%28form._%28%28lib._scribble%2Flp..rkt%29._chunk%29%29" class="RktStxLink" data-pltdoc="x">chunk</a></span> expressions are collected and stitched together into a
program, and the rest of the module is discarded. When using
<span class="RktSym"><a href="#%28form._%28%28lib._scribble%2Flp-include..rkt%29._lp-include%29%29" class="RktStxLink" data-pltdoc="x">lp-include</a></span>, the entire contents of the module are preserved
and are treated like an ordinary Scribble document, where
<span class="RktSym"><a href="#%28form._%28%28lib._scribble%2Flp..rkt%29._chunk%29%29" class="RktStxLink" data-pltdoc="x">chunk</a></span>s are typeset in a manner similar to <span class="RktSym"><a href="scribble_manual_code.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._codeblock%29%29" class="RktStxLink" data-pltdoc="x">codeblock</a></span>.</p><p>For example, consider this program:</p><p><table cellspacing="0" cellpadding="0"><tr><td><p><span class="hspace"> </span><span class="stt">#lang scribble/lp</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt"></span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">Literate programs have chunks of code, like this one:</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt"></span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">@chunk[<f></span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt">(define (f x)</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt"><fs-body>)]</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt"></span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">and this one:</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt"></span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">@chunk[<fs-body></span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt">(* x x)]</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt"></span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">that, when assembled, produce a complete program, in this case:</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt"></span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt">@racketblock[(define (f x)</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span><span class="hspace"> </span><span class="stt">(* x x))]</span></p></td></tr><tr><td><p><span class="hspace"> </span><span class="stt"></span></p></td></tr></table></p><p>When this file is <span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.1" class="RktStxLink Sq" data-pltdoc="x">require</a></span>d in the normal manner, it defines a
function <span class="RktSym">f</span> that squares its argument, and the documentation
is ignored. When it is included with <span class="RktSym"><a href="#%28form._%28%28lib._scribble%2Flp-include..rkt%29._lp-include%29%29" class="RktStxLink" data-pltdoc="x">lp-include</a></span>, it looks
like this:</p><blockquote class="LPBoxed"><p>Literate programs have chunks of code, like this one:</p><p><div class="SIntrapara"><a name="(elem._(chunk._~3cf~3e~3a1))"></a><span style="font-weight: bold"><span style="font-style: italic"><a href="#%28elem._%28chunk._~3cf~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><f></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">define</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">f</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><a href="#%28elem._%28chunk._~3cfs-body~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><fs-body></a><span class="RktPn">)</span></td></tr></table></blockquote></div></p><p>and this one:</p><p><div class="SIntrapara"><a name="(elem._(chunk._~3cfs-body~3e~3a1))"></a><span style="font-weight: bold"><span style="font-style: italic"><a href="#%28elem._%28chunk._~3cfs-body~3e~3a1%29%29" class="plainlink" data-pltdoc="x"><fs-body></a></span> ::=</span></div><div class="SIntrapara"><blockquote class="SCodeFlow"><p><span class="RktPn">(</span><span class="RktSym">*</span><span class="hspace"> </span><span class="RktSym">x</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span></p></blockquote></div></p><p>that, when assembled, produce a complete program, in this case:</p><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym">define</span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">f</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span></td></tr><tr><td><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym">*</span><span class="hspace"> </span><span class="RktSym">x</span><span class="hspace"> </span><span class="RktSym">x</span><span class="RktPn">)</span><span class="RktPn">)</span></td></tr></table></blockquote></blockquote><h4 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""scribble_lp_Language"">5.1<tt> </tt><a name="(part._scribble_lp_.Language)"></a><a name="(mod-path._scribble/lp)"></a><a href="#%28mod-path._scribble%2Flp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp</span></a> Language</h4><p><div class="SIntrapara"><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=6.1" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="hspace"> </span><a href="#%28mod-path._scribble%2Flp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp</span></a></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <span class="stt">scribble-lib</span></span></td></tr></table></div><div class="SIntrapara">The <a href="#%28mod-path._scribble%2Flp%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp</span></a> language
provides core support for literate programming.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._scribble/lp..rkt)._chunk))"></a><span title="Provided from: scribble/lp | Package: scribble-lib"><span class="RktSym"><a href="#%28form._%28%28lib._scribble%2Flp..rkt%29._chunk%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">chunk</a></span></span><span class="hspace"> </span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktVar">form</span><span class="hspace"> </span><span class="RktMeta">...</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Introduces a chunk, binding <span class="RktVar">id</span> for use in other
chunks. Normally, <span class="RktVar">id</span> starts with <span class="RktInBG"><span class="hspace"></span><span class="RktIn"><</span><span class="hspace"></span></span> and ends with
<span class="RktInBG"><span class="hspace"></span><span class="RktIn">></span><span class="hspace"></span></span>.</div></p><p>When running a scribble program only the code inside the
chunks is run; the rest is ignored.</p><p>If <span class="RktVar">id</span> is <span class="RktSym"><*></span>, then this chunk is
used as the main chunk in the file. If <span class="RktSym"><*></span>
is never used, then the first chunk in the file is treated
as the main chunk. If some chunk is not referenced from
the main chunk (possibly indirectly via other chunks that
the main chunk references), then it is not included in the
program and thus is not run.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._scribble/lp..rkt)._.C.H.U.N.K))"></a><span title="Provided from: scribble/lp | Package: scribble-lib"><span class="RktSym"><a href="#%28form._%28%28lib._scribble%2Flp..rkt%29._.C.H.U.N.K%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">CHUNK</a></span></span><span class="hspace"> </span><span class="RktVar">id</span><span class="hspace"> </span><span class="RktVar">form</span><span class="hspace"> </span><span class="RktMeta">...</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Like <span class="RktSym"><a href="#%28form._%28%28lib._scribble%2Flp..rkt%29._chunk%29%29" class="RktStxLink" data-pltdoc="x">chunk</a></span>, but allows the use of <span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=stx-patterns.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fqqstx..rkt%2529._unsyntax%2529%2529&version=6.1" class="RktStxLink Sq" data-pltdoc="x">unsyntax</a></span> in the
code part. If you want to use <span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=stx-patterns.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fqqstx..rkt%2529._unsyntax%2529%2529&version=6.1" class="RktStxLink Sq" data-pltdoc="x">unsyntax</a></span> to escape to Scribble,
use <span class="RktSym">UNSYNTAX</span>.</div></p><h4 x-source-module="(lib "scribblings/scribble/scribble.scrbl")" x-part-tag=""scribble_lp-include_Module"">5.2<tt> </tt><a name="(part._scribble_lp-include_.Module)"></a><a name="(mod-path._scribble/lp-include)"></a><a href="#%28mod-path._scribble%2Flp-include%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp-include</span></a> Module</h4><p><div class="SIntrapara"><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.1" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="#%28mod-path._scribble%2Flp-include%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp-include</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <span class="stt">scribble-lib</span></span></td></tr></table></div><div class="SIntrapara">The
<a href="#%28mod-path._scribble%2Flp-include%29" class="RktModLink" data-pltdoc="x"><span class="RktSym">scribble/lp-include</span></a> library is normally used within a
Scribble document—<wbr></wbr>that is, a module that starts with something like
<a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=6.1" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="stt"> </span><span class="RktSym">scribble/base</span> or <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=6.1" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="stt"> </span><span class="RktSym">scribble/manual</span>, instead of <a href="http://download.racket-lang.org/docs/6.1/html/local-redirect/index.html?doc=guide&rel=Module_Syntax.html%23%2528part._hash-lang%2529&version=6.1" class="RktModLink Sq" data-pltdoc="x"><span class="RktMod">#lang</span></a><span class="stt"> </span><span class="RktSym"><a href="scribble_manual_code.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._racket%29%29" class="RktStxLink" data-pltdoc="x">racket</a></span>.</div></p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>syntax</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(form._((lib._scribble/lp-include..rkt)._lp-include))"></a><span title="Provided from: scribble/lp-include | Package: scribble-lib"><span class="RktSym"><a href="#%28form._%28%28lib._scribble%2Flp-include..rkt%29._lp-include%29%29" class="RktStxDef RktStxLink" data-pltdoc="x">lp-include</a></span></span><span class="hspace"> </span><span class="RktVar">filename</span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Includes the source of <span class="RktVar">filename</span> as the typeset version of the literate
program.</div></p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.1", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.1");">top</a></span><span class="navright"> <a href="Compatibility_Libraries.html" title="backward to "4.8 Compatibility Libraries"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Scribble: The Racket Documentation Tool"" data-pltdoc="x">up</a> <a href="internals.html" title="forward to "6 Low-Level Scribble API"" data-pltdoc="x">next →</a></span> </div></div></div><div id="contextindicator"> </div></body></html>
|