305 lines
17 KiB
HTML
305 lines
17 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Advanced Weaving with Patterns</title>
|
|
<meta name="viewport" content="width=device-width initial-scale=1">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta http-equiv="Content-Language" content="en-gb">
|
|
<link href="../inweb.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body>
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-src/Figures/Octagram184x184.png" width=72 height=72">
|
|
</a></h1>
|
|
<ul><li><a href="index.html"><span class="selectedlink">inweb</span></a></li>
|
|
</ul><h2>Foundation Module</h2><ul>
|
|
<li><a href="../foundation-module/index.html">foundation</a></li>
|
|
<li><a href="../foundation-test/index.html">foundation-test</a></li>
|
|
</ul><h2>Example Webs</h2><ul>
|
|
<li><a href="../goldbach/index.html">goldbach</a></li>
|
|
<li><a href="../twinprimes/twinprimes.html">twinprimes</a></li>
|
|
</ul><h2>Repository</h2><ul>
|
|
<li><a href="https://github.com/ganelson/inweb"><img src="../github.png" height=18> github</a></li>
|
|
</ul><h2>Related Projects</h2><ul>
|
|
<li><a href="../../../inform/docs/index.html">inform</a></li>
|
|
<li><a href="../../../intest/docs/index.html">intest</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
|
|
<!--Weave of 'Advanced Weaving with Patterns' generated by 7-->
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#M">Manual</a></li><li><b>Advanced Weaving with Patterns</b></li></ul><p class="purpose">Customise the booklets woven from a web.</p>
|
|
|
|
<ul class="toc"><li><a href="#SP1">§1. Weave patterns</a></li><li><a href="#SP4">§4. Cover sheets</a></li><li><a href="#SP5">§5. Indexing</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="inwebparagraph"><a id="SP1"></a><b>§1. Weave patterns. </b>As noted, the two most useful weave patterns are <code class="display"><span class="extract">-weave-as HTML</span></code> and
|
|
<code class="display"><span class="extract">-weave-as TeX</span></code>, and these are both supplied built in to Inweb. When you
|
|
weave something with <code class="display"><span class="extract">-weave-as P</span></code>, for some pattern name <code class="display"><span class="extract">P</span></code>, Inweb first
|
|
looks to see if the web in question defines a custom pattern of that name.
|
|
For example,
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="element">$</span><span class="plain"> </span><span class="functiontext">inweb/Tangled/inweb</span><span class="plain"> inweb/Examples/goldbach</span><span class="identifier"> -weave-as</span><span class="plain"> Tapestry</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">would look for a directory called:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">inweb/Examples/goldbach/Patterns/Tapestry</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">If that is found, Inweb expects it to define <code class="display"><span class="extract">Tapestry</span></code>. If not, Inweb next
|
|
tries:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">inweb/Patterns/Tapestry</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">since <code class="display"><span class="extract">inweb/Patterns</span></code> is where the built-in patterns are kept. If it can't
|
|
find either, Inweb issues an error.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP2"></a><b>§2. </b>Patterns are a relatively new feature of Inweb, but allow for considerable
|
|
customisation of the woven output. In brief, a pattern directory is expected
|
|
to contain a configuration file called <code class="display"><span class="extract">pattern.txt</span></code>. This consists of a
|
|
series of simple one-line commands.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Most custom patterns open with the command:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">from Whatever</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">which tells Inweb that this new pattern inherits from an existing one named
|
|
<code class="display"><span class="extract">Whatever</span></code>. (Do not get these into loops, with A inheriting from B and B
|
|
also inheriting from A.) The rule is then that if Inweb needs a file to do
|
|
with weaving, it looks first in the new custom pattern, and then, failing
|
|
that, in the pattern inherited from. As a result, the custom pattern need
|
|
only contain actual differences.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">There should then always be a command reading:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">format = HTML</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">or whatever other file format is required (for the TeX pattern, for example,
|
|
this reads <code class="display"><span class="extract">format = PDF</span></code>). A few other settings can also be made with <code class="display"><span class="extract">=</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(a) <code class="display"><span class="extract">numbered = yes</span></code> causes the weaver to apply numbers to section headings:
|
|
the first included will be number 1, and so on. Default is <code class="display"><span class="extract">no</span></code>.
|
|
</li></ul>
|
|
<ul class="items"><li>(b) <code class="display"><span class="extract">abbrevs = no</span></code> causes the weaver to suppress all mention of abbreviated
|
|
sections ranges, such as <code class="display"><span class="extract">2/tpc</span></code>, which aren't useful for documentation (for
|
|
example). Default is <code class="display"><span class="extract">yes</span></code>.
|
|
</li></ul>
|
|
<ul class="items"><li>(c) <code class="display"><span class="extract">tex-command = C</span></code> tells the weaver that the TeX typesetting system should
|
|
be invoked with the shell command <code class="display"><span class="extract">C</span></code>. Default is <code class="display"><span class="extract">tex</span></code>.
|
|
</li></ul>
|
|
<ul class="items"><li>(d) <code class="display"><span class="extract">pdftex-command = C</span></code> tells the weaver that the TeX typesetting system should
|
|
be invoked with the shell command <code class="display"><span class="extract">C</span></code> when what we want is a PDF, not a DVI
|
|
file. Default is <code class="display"><span class="extract">pdftex</span></code>.
|
|
</li></ul>
|
|
<ul class="items"><li>(e) <code class="display"><span class="extract">open-command = C</span></code> tells the weaver to use the shell command <code class="display"><span class="extract">C</span></code> if it
|
|
wants to open the woven file (i.e., on the user's computer) after it finishes.
|
|
Default is <code class="display"><span class="extract">open</span></code>, which works nicely for MacOS.
|
|
</li></ul>
|
|
<ul class="items"><li>(f) <code class="display"><span class="extract">default-range = R</span></code> tells the weaver to assume the range <code class="display"><span class="extract">R</span></code>, if the user
|
|
tries to weave a multi-section web with this pattern. (For example, the standard
|
|
HTML pattern sets <code class="display"><span class="extract">default-range = sections</span></code>.)
|
|
</li></ul>
|
|
<ul class="items"><li>(g) The equals sign can also be used to override values of the bibliographic data
|
|
for the web. These changes are only temporary for the period in which the weave
|
|
is going on; they enable us to give custom titles to different weaves from the
|
|
same web. For example:
|
|
</li></ul>
|
|
<pre class="display">
|
|
<span class="plain">Title = Grammar</span>
|
|
<span class="plain">Booklet Title = A formal grammar for Inform 7</span>
|
|
<span class="plain">Author = The Inform Project</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP3"></a><b>§3. </b>The command:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">use X</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">tells Inweb that the file X, also stored in the pattern directory, should
|
|
be copied into any website being woven. For example, the HTML pattern says
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">use crumbs.gif</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">to instruct Inweb that an image used by the pages generated needs to be
|
|
copied over.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Finally, the command
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">embed css</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">tells Inweb that in any HTML file produced, the CSS necessary should be
|
|
embedded into the HTML, not linked as an external file. This is tidier for
|
|
patterns like TeX, where there will only be at most one HTML file produced,
|
|
and there's no need for an external CSS file.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP4"></a><b>§4. Cover sheets. </b>If a weave has a range bigger than a single section — for example, if it's
|
|
a weave of a chapter, or of the complete web — then it will include a
|
|
"cover sheet". In the case of a PDF being made via TeX, this will actually
|
|
be an extra page at the front of the PDF; for HTML, of course, it will just
|
|
be additional material at the top of the web page.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The template for the cover sheet should be given in a file in the pattern
|
|
folder called <code class="display"><span class="extract">cover-sheet.tex</span></code>, <code class="display"><span class="extract">cover-sheet.html</span></code> or similar. Within it,
|
|
double-square brackets can be used to represent values from the bibliographic
|
|
data at the top of the web's Contents section. For example:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">\noindent{{\stitlefont </span><span class="functiontext">[[Author]]</span><span class="plain">}}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">In addition:
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) <code class="display"><span class="extract">[[Cover Sheet]]</span></code> expands to the parent pattern's cover sheet — this is
|
|
convenient if all you want to do is to add a note at the bottom of the
|
|
standard look.
|
|
</li><li>(b) <code class="display"><span class="extract">[[Booklet Title]]</span></code> expands to text such as "Chapter 3", appropriate
|
|
to the weave being made.
|
|
</li><li>(c) <code class="display"><span class="extract">[[Capitalized Title]]</span></code> is a form of the title in block capital letters.
|
|
</li></ul>
|
|
<p class="inwebparagraph"><a id="SP5"></a><b>§5. Indexing. </b>Some weaves are accompanied by indexes. For example, a standard weave into
|
|
sections (for the HTML pattern) generates an <code class="display"><span class="extract">index.html</span></code> contents page,
|
|
linking to the weaves for the individual sections. How is this done?
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Inweb looks in the pattern for a template file called either
|
|
<code class="display"><span class="extract">chaptered-index.html</span></code> or <code class="display"><span class="extract">unchaptered-index.html</span></code>, according to whether the
|
|
web's sections are in chapters or simply in a single directory of <code class="display"><span class="extract">Sections</span></code>.
|
|
If it doesn't find this, it looks for a template simply called <code class="display"><span class="extract">index.html</span></code>,
|
|
using that template in either case.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">An index is then made by taking this template file and running it through
|
|
the "template interpreter". This is basically a filter: that is, it
|
|
works through one line at a time, and most of the time it simply copies
|
|
the input to the output. The filtering consists of making the following
|
|
replacements. Any text in the form <code class="display"><span class="extract">[[...]]</span></code> is substituted with the
|
|
value <code class="display"><span class="extract">...</span></code>, which can be any of:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(a) A bibliographic variable, set at the top of the <code class="display"><span class="extract">Contents.w</span></code> section.
|
|
</li></ul>
|
|
<ul class="items"><li>(b) One of the following details about the entire-web PDF (see below):
|
|
</li></ul>
|
|
<pre class="display">
|
|
<span class="functiontext">[[Complete Leafname]]</span><span class="plain"> </span><span class="functiontext">[[Complete Extent]]</span><span class="plain"> </span><span class="functiontext">[[Complete PDF Size]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(b) One of the following details about the "current chapter" (again, see below):
|
|
</li></ul>
|
|
<pre class="display">
|
|
<span class="functiontext">[[Chapter Title]]</span><span class="plain"> </span><span class="functiontext">[[Chapter Purpose]]</span><span class="plain"> </span><span class="functiontext">[[Chapter Leafname]]</span>
|
|
<span class="functiontext">[[Chapter Extent]]</span><span class="plain"> </span><span class="functiontext">[[Chapter PDF Size]]</span><span class="plain"> </span><span class="functiontext">[[Chapter Errors]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li> The leafname is that of the typeset PDF; the extent is a page count;
|
|
the errors result is a usually blank report.
|
|
</li></ul>
|
|
<ul class="items"><li>(c) One of the following details about the "current section" (again, see below):
|
|
</li></ul>
|
|
<pre class="display">
|
|
<span class="functiontext">[[Section Title]]</span><span class="plain"> </span><span class="functiontext">[[Section Purpose]]</span><span class="plain"> </span><span class="functiontext">[[Section Leafname]]</span>
|
|
<span class="functiontext">[[Section Extent]]</span><span class="plain"> </span><span class="functiontext">[[Section PDF Size]]</span><span class="plain"> </span><span class="functiontext">[[Section Errors]]</span>
|
|
<span class="functiontext">[[Section Lines]]</span><span class="plain"> </span><span class="functiontext">[[Section Paragraphs]]</span><span class="plain"> </span><span class="functiontext">[[Section Mean]]</span>
|
|
<span class="functiontext">[[Section Source]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li> Lines and Paragraphs are counts of the number of each; the Source
|
|
substitution is the leafname of the original <code class="display"><span class="extract">.w</span></code> file. The Mean is the
|
|
average number of lines per paragraph: where this is large, the section
|
|
is rather raw and literate programming is not being used to the full.
|
|
</li></ul>
|
|
<p class="inwebparagraph"><a id="SP6"></a><b>§6. </b>But the template interpreter isn't merely "editing the stream", because
|
|
it can also handle repetitions. The following commands must occupy entire
|
|
lines:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><code class="display"><span class="extract">[[Repeat Chapter]]</span></code> and <code class="display"><span class="extract">[[Repeat Section]]</span></code> begin blocks of lines which
|
|
are repeated for each chapter or section: the material to be repeated
|
|
continues to the matching <code class="display"><span class="extract">[[End Repeat]</span></code> line. The ``current chapter or
|
|
section'' mentioned above is the one selected in the current innermost
|
|
loop of that description.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><code class="display"><span class="extract">[[Select ...]]</span></code> and <code class="display"><span class="extract">[[End Select]</span></code> form a block which behaves like
|
|
a repetition, but happens just once, for the named chapter or section.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">For example, the following pattern:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">To take chapter 3 as an example, for instance, we find -</span>
|
|
<span class="functiontext">[[Select 3]]</span>
|
|
<span class="functiontext">[[Repeat Section]]</span>
|
|
<span class="plain">Section </span><span class="functiontext">[[Section Title]]</span><span class="plain">, </span><span class="functiontext">[[Section Code]]</span><span class="plain">, </span><span class="functiontext">[[Section Lines]]</span><span class="plain"> lines.</span>
|
|
<span class="functiontext">[[End Repeat]]</span>
|
|
<span class="functiontext">[[End Select]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">weaves a report somewhat like this:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">To take chapter 3 as an example, for instance, we find -</span>
|
|
<span class="plain">Section Lexer, 3/lex, 1011 lines.</span>
|
|
<span class="plain">Section Read Source Text, 3/read, 394 lines.</span>
|
|
<span class="plain">Section Lexical Writing Back, 3/lwb, 376 lines.</span>
|
|
<span class="plain">Section Lexical Services, 3/lexs, 606 lines.</span>
|
|
<span class="plain">Section Vocabulary, 3/vocab, 338 lines.</span>
|
|
<span class="plain">Section Built-In Words, 3/words, 1207 lines.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<hr class="tocbar">
|
|
<ul class="toc"><li><a href="M-mwiw.html">Back to 'Making Weaves into Websites'</a></li><li><a href="M-spl.html">Continue with 'Supporting Programming Languages'</a></li></ul><hr class="tocbar">
|
|
<!--End of weave-->
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|