867 lines
41 KiB
HTML
867 lines
41 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>P/iti</title>
|
|
<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>
|
|
|
|
<!--Weave of 'P/wtaw' generated by 7-->
|
|
<ul class="crumbs"><li><a href="../webs.html">★</a></li><li><a href="index.html">inweb 7</a></li><li><a href="index.html#P">Preliminaries</a></li><li><b>Webs, Tangling and Weaving</b></li></ul><p class="purpose">How to use Inweb to weave or tangle a web already written.</p>
|
|
|
|
<ul class="toc"><li><a href="#SP1">§1. All-in-one webs</a></li><li><a href="#SP4">§4. Multi-section webs</a></li><li><a href="#SP7">§7. Tangling</a></li><li><a href="#SP10">§10. Weaving</a></li><li><a href="#SP13">§13. Weave tags</a></li><li><a href="#SP14">§14. Modules</a></li><li><a href="#SP17">§17. The section catalogue</a></li><li><a href="#SP18">§18. Makefile</a></li><li><a href="#SP19">§19. Gitignore</a></li><li><a href="#SP20">§20. GitHub Pages support</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="inwebparagraph"><a id="SP1"></a><b>§1. All-in-one webs. </b>A program written for use with Inweb is called a "web". Inweb was primarily
|
|
designed for large, multisection webs, but it can also be used in a much
|
|
simpler way on smaller webs. In this documentation we'll call those
|
|
"all-in-one webs", meaning that there is just a single source code file for
|
|
the program.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Such a file should be a UTF-8 encoded plain text file with the file
|
|
extension <code class="display"><span class="extract">.inweb</span></code>. The following is a "hello world" example, which can
|
|
be found in the Inweb distribution as <code class="display"><span class="extract">inweb/Examples/hellow.inweb</span></code>:
|
|
</p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Title: hellow</span>
|
|
<span class="plain">Author: Graham Nelson</span>
|
|
<span class="plain">Purpose: A minimal example of a C program written for inweb.</span>
|
|
<span class="plain">Language: C</span>
|
|
|
|
<span class="plain">@ =</span>
|
|
<span class="plain">#include <stdio.h></span>
|
|
|
|
<span class="plain">int main(int argc, char *argv[]) {</span>
|
|
<span class="plain">printf("Hello world!\n");</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP2"></a><b>§2. </b>This of course is just a regular C "hello world" program written below
|
|
the <code class="display"><span class="extract">@ =</span></code> marker, and some metadata written above it. The metadata above
|
|
is called the "contents section": for a larger web, it would expand out
|
|
to something more like a contents page, though here it's more like a
|
|
title page. The Title, Author and Purpose make no functional difference
|
|
to the program produced - they are purely descriptive - but the Language
|
|
setting is another matter, as we shall see.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The contents end, and the code begins, when the first "paragraph" begins.
|
|
Code in an Inweb web is divided into paragraphs. The core Inform compiler
|
|
currently has 8362 paragraphs, whereas <code class="display"><span class="extract">hellow</span></code> has just one. (If you are
|
|
reading this documentation in a web page or a PDF, you will see that it's
|
|
divided up into little numbered sections: those are individual paragraphs
|
|
from the <code class="display"><span class="extract">inweb</span></code> web.) More on this below, but the use of an <code class="display"><span class="extract">@</span></code> character
|
|
in column 1 of the web file is what marks a paragraph break.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">As mentioned earlier, there are two basic things we can do with a web:
|
|
tangle, to make a program ready to compile and run; and weave, to make
|
|
a comfortably legible version for human eyes instead. Let's now tangle:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb inweb/Examples/hellow.inweb -tangle</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The reply should be like so:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">web "hellow": 1 section(s) : 1 paragraph(s) : 9 line(s)</span>
|
|
<span class="plain">tangling <inweb/Examples/hellow.c> (written in C)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">And <code class="display"><span class="extract">inweb/Examples/hellow.c</span></code> is now a regular C program which can then be
|
|
compiled. If we had wanted it to be written somewhere else, or called
|
|
something else, we could have used <code class="display"><span class="extract">-tangle-to F</span></code> to specify a file <code class="display"><span class="extract">F</span></code>
|
|
to create instead.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">In general, you never need to look at or edit tangled code, but if
|
|
we take a look at this one to see what has happened, two things are worth
|
|
noting.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(a) First, the use of the <code class="display"><span class="extract">#line</span></code> C preprocessor feature, which ensures that
|
|
any compilation errors occurring will be reported at the correct point of
|
|
origin in the original Inweb file, not in the tangled file.
|
|
</li></ul>
|
|
<ul class="items"><li>(b) Secondly, notice that the <code class="display"><span class="extract">main</span></code> function has automatically been
|
|
predeclared at the top of the file. Because Inweb does this for C programs,
|
|
the programmer can freely call functions defined lower down in the source
|
|
code, without having to write tiresome predeclarations or header files. (As it
|
|
happens, there was no need in the case of <code class="display"><span class="extract">main</span></code>, but nor was there any harm.)
|
|
</li></ul>
|
|
|
|
<pre class="display">
|
|
<span class="comment">Tangled output generated by inweb: do not edit</span>
|
|
<span class="plain">#include <stdio.h></span>
|
|
<span class="plain">#line 9 "inweb/Examples/hellow.inweb"</span>
|
|
<span class="plain">int main(int argc, char *argv[]) ;</span>
|
|
<span class="plain">#line 8 "inweb/Examples/hellow.inweb"</span>
|
|
|
|
<span class="plain">int main(int argc, char *argv[]) {</span>
|
|
<span class="plain">printf("Hello world!\n");</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP3"></a><b>§3. </b>So much for tangling: we can also weave. <code class="display"><span class="extract">hellow</span></code> is so uninteresting
|
|
to look at that this seems a good point to switch to <code class="display"><span class="extract">inweb/Examples/twinprimes.inweb</span></code>,
|
|
a C program to find twin prime numbers. If we weave:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb inweb/Examples/twinprimes.inweb -weave</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The reply should be like so:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">web "twinprimes": 1 section(s) : 4 paragraph(s) : 48 line(s)</span>
|
|
<span class="plain">[Complete Program: HTML -> inweb/Examples/twinprimes.html]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">As with tangling, we can override this destination with <code class="display"><span class="extract">-weave-to F</span></code>, telling
|
|
Inweb to weave into just a single file (which in this instance it was going
|
|
to do anyway) and call it <code class="display"><span class="extract">F</span></code>; or we can similarly <code class="display"><span class="extract">-weave-into D</span></code>, telling
|
|
Inweb to weave a set of file into the directory <code class="display"><span class="extract">D</span></code>, rather than the usual
|
|
<code class="display"><span class="extract">Woven</span></code> subdirectory of the web in question.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">By default, <code class="display"><span class="extract">-weave</span></code> makes an HTML representation of the program. (On a larger
|
|
web, with multiple sections, it would make a set of linked pages, but here
|
|
there's just one.) This can then be looked at with a browser such as Chrome or
|
|
Safari. HTML is not the only format we can produce. Inweb performs the weave
|
|
by following a "pattern", and it has several patterns built in:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">HTML Ebook TeX</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Running Inweb with <code class="display"><span class="extract">-weave-as P</span></code> tells it to weave with pattern <code class="display"><span class="extract">P</span></code>; the
|
|
plain command <code class="display"><span class="extract">-weave</span></code> is equivalent to <code class="display"><span class="extract">-weave-as HTML</span></code>. The <code class="display"><span class="extract">Ebook</span></code> pattern
|
|
makes an EPUB file suitable for readers such as Apple's Books app, but that
|
|
would be overkill for such a tiny program. Instead:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb inweb/Examples/twinprimes.inweb -weave-as TeX</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This will only work if you have the mathematical typesetting system TeX
|
|
installed, and in particular, the <code class="display"><span class="extract">pdftex</span></code> tool. (This comes as part of
|
|
the standard TeXLive distribution, so simply "installing TeX" on your
|
|
platform will probably install <code class="display"><span class="extract">pdftex</span></code> automatically.) Now the response
|
|
is like so:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">web "twinprimes": 1 section(s) : 4 paragraph(s) : 48 line(s)</span>
|
|
<span class="plain">[Complete Program: PDF -> inweb/Examples/twinprimes.tex: 1pp 103K]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Inweb automatically creates <code class="display"><span class="extract">twinprimes.tex</span></code> and runs it through <code class="display"><span class="extract">pdftex</span></code>
|
|
to produce <code class="display"><span class="extract">twinprimes.pdf</span></code>: it reads over the TeX log file to see how
|
|
many pages that comes to, and reports back. All being well, the <code class="display"><span class="extract">.tex</span></code>
|
|
and <code class="display"><span class="extract">.log</span></code> files are silently removed, leaving just <code class="display"><span class="extract">twinprimes.pdf</span></code> behind.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP4"></a><b>§4. Multi-section webs. </b>The <code class="display"><span class="extract">twinprimes.inweb</span></code> example was a program so small that it could
|
|
comfortably fit into one source file, but for really large programs, that
|
|
would be madness. The core Inform compiler, for example, runs to about
|
|
210,000 lines of code, and distributes those across 418 source files
|
|
called "sections", together with a special 419th section which forms
|
|
its contents page. It's a matter of personal taste how much should be
|
|
in a section, but an ideal section file might contain 500 to 1000 lines
|
|
of material and weave to a standalone essay, describing and implementing
|
|
a single well-defined component of the whole program.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">In this documentation, we'll call such webs "multi-section".
|
|
</p>
|
|
|
|
<p class="inwebparagraph">A multi-section web is stored as a directory, whose name should be (a
|
|
short version of) the name of the program. For example, Inweb's own
|
|
source is in a directory called <code class="display"><span class="extract">inweb</span></code>. A web directory is a tidy,
|
|
self-contained area in which the program can be written, compiled and
|
|
used.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Inweb expects that a multi-section web will contain at least two source
|
|
files, each of which is a UTF-8 encoded text file with the file extension
|
|
<code class="display"><span class="extract">.w</span></code>. One source file is special, must always be called <code class="display"><span class="extract">Contents.w</span></code>,
|
|
and must be directly stored in the web directory. All other section files
|
|
are stored in subdirectories of the web directory:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(a) If the web is still relatively small, there may only be a few of these,
|
|
stored in a single subdirectory called <code class="display"><span class="extract">Sections</span></code>.
|
|
</li></ul>
|
|
<ul class="items"><li>(b) Alternatively (not additionally), a larger web can use chapter
|
|
subdirectories called <code class="display"><span class="extract">Preliminaries</span></code>, <code class="display"><span class="extract">Chapter 1</span></code>, <code class="display"><span class="extract">Chapter 2</span></code>, ...,
|
|
<code class="display"><span class="extract">Appendix A</span></code>, <code class="display"><span class="extract">Appendix B</span></code>, ...; preliminaries and appendices being optional.
|
|
(There can't be a Chapter 0, though there can be Appendix A, B, C, ..., O.)
|
|
</li></ul>
|
|
<p class="inwebparagraph">A multi-section web can contain a variety of other subdirectories as needed.
|
|
Two in particular, <code class="display"><span class="extract">Woven</span></code> and <code class="display"><span class="extract">Tangled</span></code>, are automatically created by Inweb
|
|
as needed to store the results of tangling and weaving, respectively: they
|
|
are not intended to hold any material of lasting value, and can be emptied
|
|
at any time and regenerated later.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP5"></a><b>§5. </b>Uniquely, the <code class="display"><span class="extract">Contents.w</span></code> section provides neither typeset output nor
|
|
compiled code: it is instead a roster telling Inweb about the rest of the
|
|
web, and how the other sections are organised. It has a completely different
|
|
syntax from all other sections. (It's essentially a fuller version of the
|
|
top part of an all-in-one web file as demonstrated above, but now it
|
|
occupies the whole file.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The contents section opens with some bibliographic data. For example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Title: inter</span>
|
|
<span class="plain">Author: Graham Nelson</span>
|
|
<span class="plain">Purpose: For handling intermediate Inform code</span>
|
|
<span class="plain">Language: InC</span>
|
|
<span class="plain">Licence: Artistic License 2.0</span>
|
|
<span class="plain">Version Number: 1</span>
|
|
<span class="plain">Version Name: Axion</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This is a simply a block of name-value pairs specifying some bibliographic
|
|
details; there is then a skipped line, and the roster of sections begins.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Note that the program's <code class="display"><span class="extract">Title</span></code> need not be the same as the directory-name
|
|
for the web, which is useful if the program has a long or file-system-unfriendly
|
|
name. The <code class="display"><span class="extract">Purpose</span></code> should be brief enough to fit onto one line. <code class="display"><span class="extract">Licence</span></code> can
|
|
also have the US spelling, <code class="display"><span class="extract">License</span></code>; Inweb treats these as equivalent.
|
|
Version number and name are, of course, optional.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The <code class="display"><span class="extract">Language</span></code> is the programming language in which the code is written. At
|
|
present Inweb supports:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">C C++ InC Perl Inform 6 Inform 7 Plain Text</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Perhaps "supports" ought to be in quotation marks, because Inweb doesn't
|
|
need to know much about the underlying programming language. It would be
|
|
easy to add others; this selection just happens to be the ones we need for
|
|
the Inform project.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP6"></a><b>§6. </b>After the header block of details, then, we have the roster of sections.
|
|
This is like a contents page — the order is the order in which the sections
|
|
are presented on any website, or in any of the larger PDFs woven. For a short,
|
|
unchaptered web, we might have for instance:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Sections</span>
|
|
<span class="plain"> Program Control</span>
|
|
<span class="plain"> Command Line and Configuration</span>
|
|
<span class="plain"> Scan Documentation</span>
|
|
<span class="plain"> HTML and Javascript</span>
|
|
<span class="plain"> Renderer</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">And then Inweb will expect to find, for instance, the section file
|
|
<code class="display"><span class="extract">Scan Documentation.w</span></code> in the <code class="display"><span class="extract">Sections</span></code> directory.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">A larger web, however, won't have a "Sections" directory. It may have a
|
|
much longer roster, such as:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Preliminaries</span>
|
|
<span class="plain"> Preface</span>
|
|
<span class="plain"> Thematic Index</span>
|
|
<span class="plain"> Licence and Copyright Declaration</span>
|
|
<span class="plain"> BNF Grammar</span>
|
|
|
|
<span class="plain">Chapter 1: Definitions</span>
|
|
<span class="plain">"In which some globally-used constants are defined and the standard C libraries</span>
|
|
<span class="plain">are interfaced with, with all the differences between platforms (Mac OS X,</span>
|
|
<span class="plain">Windows, Linux, Solaris, Sugar/XO and so forth) taken care of once and for all."</span>
|
|
<span class="plain"> Basic Definitions</span>
|
|
<span class="plain"> Platform-Specific Definitions</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">... and so on...
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Appendix A: The Standard Rules (Independent Inform 7)</span>
|
|
<span class="plain">"This is the body of Inform 7 source text automatically included with every</span>
|
|
<span class="plain">project run through the NI compiler, and which defines most of what end users</span>
|
|
<span class="plain">see as the Inform language."</span>
|
|
<span class="plain"> SR0 - Preamble</span>
|
|
<span class="plain"> SR1 - Physical World Model</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">... and so on. Here the sections appear in directories called Preliminaries,
|
|
Chapter 1, Chapter 2, ..., Appendix A. (These are the only possibilities:
|
|
Inweb doesn't allow other forms of name for blocks of sections. There can't be
|
|
a Chapter 0, though there can be Appendix B, C, ..., O.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">In case of any doubt we can use the following command-line switch to see
|
|
how Inweb is actually reading the sections of a web <code class="display"><span class="extract">W</span></code>:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb W -catalogue -verbose</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP7"></a><b>§7. Tangling. </b>At this point, it may be worth experimenting with a second mathematical
|
|
example: <code class="display"><span class="extract">inweb/Examples/goldbach</span></code>, which is to do with a problem in number
|
|
theory called the Goldbach Conjecture. This is a multi-section web, though
|
|
really only for the sake of an example: it's still a very small web.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">This is once again a C program. Actually building and running this is a
|
|
little trouble, of course, and because there are multiple source files, it's
|
|
not so easy to keep track of whether the program is built up to date.
|
|
So a convenience of Inweb is that it can make makefiles to help with this:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb inweb/Examples/goldbach -makefile inweb/Examples/goldbach/goldbach.mk</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">With this done,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ make -f inweb/Examples/goldbach/goldbach.mk</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">tangles and then compiles the program as necessary. The tangling part of that
|
|
is nothing fancy - as before, it's just
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb inweb/Examples/goldbach -tangle</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Assuming all goes well:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Examples/goldbach/Tangled/goldbach</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">should then print out some results.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP8"></a><b>§8. </b>It is legal in some circumstances to tangle only part of a web. This is done
|
|
by specifying a "range", much as will be seen later with weaving - but
|
|
because it's not normally meaningful to tangle only part of a program, the
|
|
possible ranges are much more restricted. In fact, the only partial tangles
|
|
allowed are for chapters or sections marked in the <code class="display"><span class="extract">Contents.w</span></code> as being
|
|
"Independent". For example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Appendix A: The Standard Rules (Independent Inform 7)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">declares that Appendix A is a sort of sidekick program, written in the
|
|
language "Inform 7". As a result, it won't be included in a regular <code class="display"><span class="extract">-tangle</span></code>,
|
|
and to obtain it we have to:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">inweb/Tangled/inweb inform7 -tangle A</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9"></a><b>§9. </b>In some C programs, it's useful to require that a header file be added to
|
|
a tangle. This can be done by adding:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Header: H</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">to the contents page of a web. The heacer file <code class="display"><span class="extract">H</span></code> in question should then
|
|
be stored in the web's <code class="display"><span class="extract">Headers</span></code> subdirectory. (At one time, the Foundation
|
|
module used this to bring in a Windows-only header file.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP10"></a><b>§10. Weaving. </b>As with all-in-one webs, the commands for weaving are like so:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb inweb/Examples/goldbach -weave</span>
|
|
<span class="plain">$ inweb inweb/Examples/goldbach -weave-as TeX</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This will produce single HTML or PDF files of the woven form of the whole
|
|
program. (Note that the PDF file now has a cover page: on a web with just
|
|
a single section, this wouldn't happen.) But with a growing web, that can
|
|
be cumbersome.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP11"></a><b>§11. </b>After setting <code class="display"><span class="extract">-weave</span></code> or <code class="display"><span class="extract">-weave-as</span></code>, we can also optionally choose a
|
|
range. The default range is <code class="display"><span class="extract">all</span></code>, so up to now we have implicitly
|
|
been running weaves like these:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb inweb/Examples/goldbach -weave all</span>
|
|
<span class="plain">$ inweb inweb/Examples/goldbach -weave-as TeX all</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The opposite extreme from <code class="display"><span class="extract">all</span></code> is <code class="display"><span class="extract">sections</span></code>. This still weaves the entire
|
|
web, but now cuts it up into individual files, one for each section. For
|
|
example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb inweb/Examples/goldbach -weave sections</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">makes a miniature website of four files:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">inweb/Examples/goldbach/Woven/index.html</span>
|
|
<span class="plain">inweb/Examples/goldbach/Woven/inweb.css</span>
|
|
<span class="plain">inweb/Examples/goldbach/Woven/S-tgc.html</span>
|
|
<span class="plain">inweb/Examples/goldbach/Woven/S-tsoe.html</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Those abbreviated names <code class="display"><span class="extract">S-tgc</span></code> and <code class="display"><span class="extract">S-tsoe</span></code> are cut down from the full
|
|
names of the sections involved, "The Goldbach Conjecture" and "The Sieve
|
|
of Eratosthenes". Similarly,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb inweb/Examples/goldbach -weave-as TeX sections</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">creates the files:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">inweb/Examples/goldbach/Woven/index.html</span>
|
|
<span class="plain">inweb/Examples/goldbach/Woven/S-tgc.pdf</span>
|
|
<span class="plain">inweb/Examples/goldbach/Woven/S-tsoe.pdf</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The index file here is a table of contents offering links to the PDFs.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">An intermediate level of granularity is the range <code class="display"><span class="extract">chapters</span></code>, which makes
|
|
sense only for chaptered webs, and puts each chapter into its own file.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP12"></a><b>§12. </b>Ranges can also be used to weave only part of a web:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(a) In a chaptered web, chapters are abbreviated to just their numbers: for
|
|
example, the range <code class="display"><span class="extract">2</span></code> means "just Chapter 2". The Preliminaries alone is <code class="display"><span class="extract">P</span></code>.
|
|
Appendix A, B, C are <code class="display"><span class="extract">A</span></code>, <code class="display"><span class="extract">B</span></code>, <code class="display"><span class="extract">C</span></code> and so on. (This is why Appendices can
|
|
only run up to O.)
|
|
</li></ul>
|
|
<ul class="items"><li>(b) In an unchaptered web, <code class="display"><span class="extract">S</span></code> means "all the sections". This is almost but not
|
|
quite the same as <code class="display"><span class="extract">all</span></code>: the cover sheet (a sort of title page) is omitted.
|
|
</li></ul>
|
|
<ul class="items"><li>(c) The abbreviation for a section makes a range of just that section. For
|
|
example, <code class="display"><span class="extract">S/tgc</span></code> and <code class="display"><span class="extract">S/tsoe</span></code> in the Goldbach web example, or <code class="display"><span class="extract">2/ec</span></code> for
|
|
the "Enumerated Constants" section of Chapter 2 of Inweb itself. Note that
|
|
running Inweb with <code class="display"><span class="extract">-catalogue</span></code> shows all the sections of a web, and their
|
|
abbreviations.
|
|
</li></ul>
|
|
<p class="inwebparagraph"><a id="SP13"></a><b>§13. Weave tags. </b>An alternative to a range is to specify a tag. Rather than weaving contiguous
|
|
pieces of the web, this collates together all those paragraphs with a given
|
|
tag. The result is a booklet of extracts.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Most paragraphs are never tagged. A tag is simply a word; paragraphs can have
|
|
multiple tags, but for each individual tags they either have it or don't.
|
|
A very few tags are automatically applied by Inweb:
|
|
</p>
|
|
|
|
<p class="inwebparagraph">If the program is for a C-like language, Inweb automatically tags any
|
|
paragraph containing a <code class="display"><span class="extract">typedef struct</span></code> with the tag <code class="display"><span class="extract">Structures</span></code>. So,
|
|
for example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb inweb -weave-tag Structures</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">weaves just the structure definitions culled from a much larger web; this
|
|
can make a convenient reference. Similarly, any paragraph containing an
|
|
illustration is automatically tagged <code class="display"><span class="extract">Figures</span></code>, and any paragraph in an
|
|
<code class="display"><span class="extract">InC</span></code> web which defines Preform grammar is automatically tagged <code class="display"><span class="extract">Preform</span></code>.
|
|
(In the Inform project, this is used to generate the PDF of the formal
|
|
syntax of the language.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">All other tags must be typed by hand. If the line introducing a paragraph
|
|
is marked at the end with <code class="display"><span class="extract">^"Fun"</span></code>, then that paragraph will be tagged
|
|
as <code class="display"><span class="extract">Fun</span></code>, and so on. Paragraphs can have multiple tags:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@ ^"Algorithms" ^"History"</span>
|
|
<span class="plain">The original version of the program used an in-place insertion sort, but</span>
|
|
<span class="plain">...</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">A tag can optionally supply a caption. For example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@ ^"Algorithms: Sorting rulebooks"</span>
|
|
<span class="plain">The original version of the program used an in-place insertion sort, but</span>
|
|
<span class="plain">...</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Here the tag is just <code class="display"><span class="extract">Algorithms</span></code>, but when a <code class="display"><span class="extract">-weave-to Algorithms</span></code> is
|
|
performed, the caption text "Sorting rulebooks" will be used in a subheading
|
|
in the resulting booklet.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Beyond that, an entire section can be tagged from the <code class="display"><span class="extract">Contents.w</span></code> page.
|
|
For example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Sections</span>
|
|
<span class="plain"> The Goldbach Conjecture</span>
|
|
<span class="plain"> The Sieve of Eratosthenes ^"Greek"</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">tags every paragraph in the section "The Sieve of Eratosthenes" with the
|
|
tag <code class="display"><span class="extract">Greek</span></code>. In this instance, a caption is not allowed.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Note that if we <code class="display"><span class="extract">-weave-to</span></code> a tag which does not exist - or rather, which no
|
|
paragraph in the range has - then rather than producing an empty document,
|
|
Inweb will halt with an "empty weave request" error.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP14"></a><b>§14. Modules. </b>Up to now, the webs described have all been self-contained: one web makes
|
|
one program, and contains the code in its entirety. But Inweb also supports
|
|
"modules". A module is simply a web which provides a compoment of a program
|
|
but is not a program in its own right.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">For example, all of the Inform tools (including Inweb itself) make use of
|
|
a module called <code class="display"><span class="extract">foundation</span></code>, which is written in InC and provides
|
|
facilities for managing memory, manipulating strings, filenames, and so on.
|
|
On the other hand, the Inform project also includes a module called <code class="display"><span class="extract">inter</span></code>
|
|
which is used only by the core compiler <code class="display"><span class="extract">inform7</span></code> and by a wrapper utility
|
|
also called <code class="display"><span class="extract">inter</span></code>; in fact, <code class="display"><span class="extract">inform7</span></code> is entirely divided up into modules,
|
|
some of which are used only by itself.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP15"></a><b>§15. </b>It makes little sense to tangle a module on its own. Instead, a web which
|
|
wishes to use a module needs to declare this on its <code class="display"><span class="extract">Contents.w</span></code> page. This
|
|
is done with a list of "imports", after the metadata but before the list
|
|
of sections. For example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">Import: foundation</span>
|
|
|
|
<span class="plain">Chapter 1</span>
|
|
<span class="plain"> Startup</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">...and so on. When this new web is tangled, the module's code will tangled
|
|
into it. Any functions or variables defined in the module will thus be
|
|
available to the new web.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">However, it makes perfectly good sense to weave a module. For example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb inweb/foundation-module -weave sections</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP16"></a><b>§16. </b>That's everything there is to say about modules, except where Inweb looks
|
|
to find them. When it reads a request from a web <code class="display"><span class="extract">W</span></code> to import a module <code class="display"><span class="extract">M</span></code>,
|
|
it looks for a web directory called <code class="display"><span class="extract">M-module</span></code> (note the hyphen). For
|
|
example, <code class="display"><span class="extract">Import: fruit</span></code> would look for the directory <code class="display"><span class="extract">fruit-module</span></code>. Inweb
|
|
tries the following locations, in sequence, until it finds it:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(1) Directly inside <code class="display"><span class="extract">W</span></code>.
|
|
</li><li>(2) In the directory containing <code class="display"><span class="extract">W</span></code> (i.e., one directory higher up).
|
|
</li><li>(3) Directly inside Inweb's own web directory.
|
|
</li><li>(4) In the directory specified by <code class="display"><span class="extract">-import-from D</span></code> at the command line, if any.
|
|
</li></ul>
|
|
<p class="inwebparagraph"><a id="SP17"></a><b>§17. The section catalogue. </b>Inweb can do a handful of other things. One is to list the contents of a web:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(a) <code class="display"><span class="extract">-catalogue</span></code> (or <code class="display"><span class="extract">-catalog</span></code>) lists the sections in the web.
|
|
</li></ul>
|
|
<ul class="items"><li>(b) <code class="display"><span class="extract">-structures</span></code> lists the sections, and all of the structure definitions
|
|
made in them (for C-like languages).
|
|
</li></ul>
|
|
<ul class="items"><li>(c) <code class="display"><span class="extract">-functions</span></code> lists the sections, with all structure definitions and also
|
|
all function definitions.
|
|
</li></ul>
|
|
<p class="inwebparagraph">In addition, for debugging purposes, <code class="display"><span class="extract">-scan</span></code> shows how Inweb is parsing lines
|
|
of source code in the web, and <code class="display"><span class="extract">-verbose</span></code> makes it generally print out more
|
|
descriptive output.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP18"></a><b>§18. Makefile. </b>As mentioned earlier, Inweb can construct a suitable makefile for a web:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb W -makefile M</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">creates a makefile for the web <code class="display"><span class="extract">W</span></code> and stores it in <code class="display"><span class="extract">M</span></code>. For example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb inweb -makefile inweb/inweb.mk</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The makefile is constructed using a prototype file called a "makescript".
|
|
Ordinarily the script used will be the one stored in
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">W/makescript.txt</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">or, if no such file exists, the default one stored in Inweb:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">inweb/Materials/makescript.txt</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">but this can be changed by using <code class="display"><span class="extract">-prototype S</span></code>, which tells Inweb to use
|
|
<code class="display"><span class="extract">S</span></code> as the script. If a <code class="display"><span class="extract">-prototype</span></code> is given, then there's no need to
|
|
specify any one web for Inweb to use: this allows Inweb to construct more
|
|
elaborate makefiles for multi-web projects. (This is how the main makefile
|
|
for the Inform project is constructed.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">To see how makescripts work, it's easiest simply to look at the default one.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP19"></a><b>§19. Gitignore. </b>A similar convenience exists for users who want to use the git source control
|
|
tool with a web: for example, uploading it to Github.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The files produced by weaving or tangling a web are not significant and should
|
|
probably not be subject to source control: they should be "ignored", in git
|
|
terminology. This means writing a special file called <code class="display"><span class="extract">.gitignore</span></code> which
|
|
specifies the files to be ignored. The following does so for a web <code class="display"><span class="extract">W</span></code>:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb W -gitignore W/.gitignore</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Once again, Inweb does this by working from a script, this time called
|
|
<code class="display"><span class="extract">gitignorescript.txt</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP20"></a><b>§20. GitHub Pages support. </b>If a project is hosted at GitHub, then the GitHub Pages service is the ideal
|
|
place to serve a woven copy of the project to the world. To that end,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb W -weave-docs</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">performs a weave which is special in two ways:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<ul class="items"><li>(a) It uses the pattern called <code class="display"><span class="extract">GitHubPages</span></code>, and
|
|
</li><li>(b) Material is by default placed in <code class="display"><span class="extract">W/docs/NAME</span></code>, where <code class="display"><span class="extract">NAME</span></code> is the
|
|
short title of the project.
|
|
</li></ul>
|
|
<p class="inwebparagraph">The reason for this scheme is that GitHub Pages, if enabled, serves a
|
|
website using part or all of a git repository. Here, we just want part of
|
|
the project's repository to be served: that being so, GitHub mandates that
|
|
we use a top-level directory in the repository called <code class="display"><span class="extract">docs</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><code class="display"><span class="extract">-weave-docs</span></code> expects that there will be a page at <code class="display"><span class="extract">W/docs/webs.html</span></code> to
|
|
give readers a choice of which web to browse — since some Inweb projects
|
|
contain multiple webs. There will later be a way to create the <code class="display"><span class="extract">webs.html</span></code>
|
|
poge automatically, but for now it's made by hand.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Note that:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">$ inweb/Tangled/inweb W -weave-docs -weave-into P</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">substitutes the path <code class="display"><span class="extract">P</span></code> for <code class="display"><span class="extract">W/docs/NAME</span></code>. But the files created there still
|
|
expect that to be able to link to a <code class="display"><span class="extract">../webs.html</span></code>, that is, in the directory
|
|
above them.
|
|
</p>
|
|
|
|
<hr class="tocbar">
|
|
<ul class="toc"><li><a href="P-iti.html">Back to 'Introduction to Inweb'</a></li><li><a href="P-htwaw.html">Continue with 'How to Write a Web'</a></li></ul><hr class="tocbar">
|
|
<!--End of weave-->
|
|
</body>
|
|
</html>
|
|
|