AwesomeAdam54321/inweb-bootstrap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
inweb-bootstrap/docs/inweb/M-wtaw.html
Graham Nelson 97e7ee892c Added -sequential section range option
2020-04-03 16:29:03 +01:00

1019 lines
49 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>M/iti</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="../webs.html">Sources</a></h1>
<ul>
<li><a href="../inweb/index.html">inweb</a></li>
</ul>
<h2>Foundation</h2>
<ul>
<li><a href="../foundation-module/index.html">foundation-module</a></li>
<li><a href="../foundation-test/index.html">foundation-test</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of 'M/wtaw' generated by 7-->
<ul class="crumbs"><li><a href="../webs.html">Source</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#M">Manual</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">&#167;1. All-in-one webs</a></li><li><a href="#SP4">&#167;4. Multi-section webs</a></li><li><a href="#SP7">&#167;7. Tangling</a></li><li><a href="#SP10">&#167;10. Weaving</a></li><li><a href="#SP13">&#167;13. Weave tags</a></li><li><a href="#SP14">&#167;14. Modules</a></li><li><a href="#SP17">&#167;17. The section catalogue</a></li><li><a href="#SP18">&#167;18. Makefile</a></li><li><a href="#SP19">&#167;19. Gitignore</a></li><li><a href="#SP20">&#167;20. README files</a></li><li><a href="#SP23">&#167;23. GitHub Pages support</a></li><li><a href="#SP24">&#167;24. Semantic version numbering and build metadata</a></li></ul><hr class="tocbar">
<p class="inwebparagraph"><a id="SP1"></a><b>&#167;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 &lt;stdio.h&gt;</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>&#167;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 &lt;inweb/Examples/hellow.c&gt; (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 &lt;stdio.h&gt;</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>&#167;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 -&gt; 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 -&gt; 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>&#167;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">Manual</span></code>, <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, ..., L.)
</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>&#167;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>&#167;6. </b>After the header block of details, then, we have the roster of sections.
This is like a contents page &mdash; 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. (There can't be a Chapter 0, though
there can be Appendix B, C, ..., O; there can also be a Manual chapter, in
the sense of documentation.)
</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>&#167;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>&#167;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>&#167;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>&#167;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>&#167;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>&#167;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>;
the Manual, <code class="display"><span class="extract">M</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 L.)
</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. If it's a nuisance that these section ranges are hard to
predict, run with <code class="display"><span class="extract">-sequential</span></code> to have them simply be <code class="display"><span class="extract">X/s1</span></code>, <code class="display"><span class="extract">X/s2</span></code>, ...,
within each chapter, where <code class="display"><span class="extract">X</span></code> is the chapter range.
</li></ul>
<p class="inwebparagraph"><a id="SP13"></a><b>&#167;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>&#167;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>&#167;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>&#167;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>&#167;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>&#167;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>&#167;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>&#167;20. README files. </b>Repositories at Github customarily have <code class="display"><span class="extract">README.mk</span></code> files, in Markdown
syntax, explaining what they are. These of course should probably include
current version numbers, and it's a pain keeping that up to date. For
really complicated repositories, containing multiple webs, some automation
is essential, and once again Inweb can oblige.
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">$ inweb/Tangled/inweb W -write-me W/README.mk</span>
</pre>
<p class="inwebparagraph">expands a script called <code class="display"><span class="extract">READMEscript.txt</span></code> into <code class="display"><span class="extract">README.mk</span></code>. Alternatively,
the script can be specified explicitly:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">$ inweb/Tangled/inweb W -prototype MySpecialThang.txt -write-me W/README.mk</span>
</pre>
<p class="inwebparagraph"></p>
<p class="inwebparagraph"><a id="SP21"></a><b>&#167;21. </b>Everything in the script is copied over verbatim except where the <code class="display"><span class="extract">@</span></code> character
is used, which was chosen because it isn't significant in Github's form of
Markdown. <code class="display"><span class="extract">@name(args)</span></code> is like a function call (or, in more traditional
language, a macro): it expands out to something depending on the arguments.
<code class="display"><span class="extract">args</span></code> is a comma-separated list of fragments of text, which can themselves
contain further uses of <code class="display"><span class="extract">@</span></code>. (If these fragments of text need to contain
commas or brackets, they can be put into single quotes: <code class="display"><span class="extract">@thus(4,',')</span></code> has
two arguments, <code class="display"><span class="extract">4</span></code> and <code class="display"><span class="extract">,</span></code>.) Three functions are built in:
</p>
<p class="inwebparagraph"></p>
<ul class="items"><li>(a) <code class="display"><span class="extract">@version(A)</span></code> expands to the version number of <code class="display"><span class="extract">A</span></code>, which is normally the
path to a web; it then produces the value of the <code class="display"><span class="extract">[[Version Number]]</span></code> for
that web. But <code class="display"><span class="extract">A</span></code> can also be the filename of an Inform extension, provided
that it ends in <code class="display"><span class="extract">.i7x</span></code>, or a few other Inform-specific things for which
Inweb is able to deduce a version number.
</li></ul>
<ul class="items"><li>(b) <code class="display"><span class="extract">@purpose(A)</span></code> is the same, but for the <code class="display"><span class="extract">[[Purpose]]</span></code> of a web. It's
blank for everything else.
</li></ul>
<ul class="items"><li>(c) <code class="display"><span class="extract">@var(A,D)</span></code> is more general, and reads the bibliographic datum <code class="display"><span class="extract">D</span></code> from
the web indicated by <code class="display"><span class="extract">A</span></code>. In fact, <code class="display"><span class="extract">@version(A)</span></code> is an abbreviation for
<code class="display"><span class="extract">@var(A,Version Number)</span></code> and <code class="display"><span class="extract">@purpose(A)</span></code> for <code class="display"><span class="extract">@var(A,Purpose)</span></code>, so this
is really the only one needed.
</li></ul>
<p class="inwebparagraph"><a id="SP22"></a><b>&#167;22. </b>It is also possible to define new functions. For example:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">@define book(title, path, topic)</span>
<span class="plain">* @title - @topic. Ebook in Indoc format, stored at path @path.</span>
<span class="plain">@end</span>
</pre>
<p class="inwebparagraph">The definition lies between <code class="display"><span class="extract">@define</span></code> and <code class="display"><span class="extract">@end</span></code> commands. This one takes
three parameters, and inside the definition, their values can be referred
to as <code class="display"><span class="extract">@title</span></code>, <code class="display"><span class="extract">@path</span></code> and <code class="display"><span class="extract">@topic</span></code>. Functions are free to use other
functions:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">@define primary(program, language)</span>
<span class="plain">* @program - @purpose(@program) - __@version(@program)__</span>
<span class="plain">@end</span>
</pre>
<p class="inwebparagraph">However, each function needs to have been defined before any line on which
it is actually expanded. A definition of one function <code class="display"><span class="extract">A</span></code> can refer to another
function <code class="display"><span class="extract">B</span></code> not yet defined; but any actual use of <code class="display"><span class="extract">A</span></code> must be made after
both <code class="display"><span class="extract">A</span></code> and <code class="display"><span class="extract">B</span></code> have been defined. So, basically, declare before use.
</p>
<p class="inwebparagraph"><a id="SP23"></a><b>&#167;23. 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 &mdash; 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>
<p class="inwebparagraph"><a id="SP24"></a><b>&#167;24. Semantic version numbering and build metadata. </b>When Inweb reads in a web, it also looks for a file called <code class="display"><span class="extract">build.txt</span></code> in
the web's directory; if that isn't there, it looks for the same file in the
current working directory; if that's not there either, never mind.
</p>
<p class="inwebparagraph">Such a file contains up to three text fields, all optional:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">Prerelease: alpha.1</span>
<span class="plain">Build Date: 23 March 2020</span>
<span class="plain">Build Number: 6Q26</span>
</pre>
<p class="inwebparagraph">The bibliographic variables <code class="display"><span class="extract">Prerelease</span></code> and so on are then set from this
file. (They can equally well be set by the Contents section of the web, and
if so then that takes priority.)
</p>
<p class="inwebparagraph">The Prerelease and Build Number, if given, are used in combination with the
Version Number (set in the Contents) to produce the semantic version number,
or semver, for the web. For example, if the Contents included:
</p>
<p class="inwebparagraph"></p>
<pre class="display">
<span class="plain">Version Number: 6.2.12</span>
</pre>
<p class="inwebparagraph">then the semver would be <code class="display"><span class="extract">6.2.12-alpha.1+6Q26</span></code>. This is accessible within
the web as the variable <code class="display"><span class="extract">Semantic Version Number</span></code>.
</p>
<p class="inwebparagraph"><a id="SP25"></a><b>&#167;25. </b>A special advancing mechanism exists to update build numbers and dates.
Running Inweb with <code class="display"><span class="extract">-advance-build W</span></code> checks the build date for web <code class="display"><span class="extract">W</span></code>:
if it differs from today, then it is changed to today, and the build code
is advanced by one.
</p>
<p class="inwebparagraph">Running <code class="display"><span class="extract">-advance-build-file B</span></code> does this for a stand-alone build file <code class="display"><span class="extract">B</span></code>,
without need of a web.
</p>
<hr class="tocbar">
<ul class="toc"><li><a href="M-iti.html">Back to 'Introduction to Inweb'</a></li><li><a href="M-htwaw.html">Continue with 'How to Write a Web'</a></li></ul><hr class="tocbar">
<!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink