<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="index.html">inweb</a></li><li><ahref="index.html#M">Manual</a></li><li><b>Webs, Tangling and Weaving</b></li></ul></div>
<pclass="purpose">How to use Inweb to weave or tangle a web already written.</p>
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. All-in-one webs. </b>A program written for use with Inweb is called a "web". Inweb was primarily
<spanclass="plain-syntax"></span><spanclass="element-syntax">Author</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> Graham Nelson</span>
<spanclass="plain-syntax"></span><spanclass="element-syntax">Purpose</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> A minimal example of a C program written for inweb.</span>
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. </b>This of course is just a regular C "hello world" program written below
from the <spanclass="extract"><spanclass="extract-syntax">inweb</span></span> web.) More on this below, but the use of an <spanclass="extract"><spanclass="extract-syntax">@</span></span> character
<pclass="commentary">And <spanclass="extract"><spanclass="ConsoleText-extract-syntax">inweb/Examples/hellow.c</span></span> is now a regular C program which can then be
something else, we could have used <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-tangle-to F</span></span> to specify a file <spanclass="extract"><spanclass="ConsoleText-extract-syntax">F</span></span>
<ulclass="items"><li>(a) First, the use of the <spanclass="extract"><spanclass="ConsoleText-extract-syntax">#line</span></span> C preprocessor feature, which ensures that
happens, there was no need in the case of <spanclass="extract"><spanclass="ConsoleText-extract-syntax">main</span></span>, but nor was there any harm.)
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. </b>So much for tangling: we can also weave. <spanclass="extract"><spanclass="extract-syntax">hellow</span></span> is so uninteresting
<pclass="commentary">As with tangling, we can override this destination with <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-weave-to F</span></span>, telling
to do anyway) and call it <spanclass="extract"><spanclass="ConsoleText-extract-syntax">F</span></span>; or we can similarly <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-weave-into D</span></span>, telling
Inweb to weave a set of file into the directory <spanclass="extract"><spanclass="ConsoleText-extract-syntax">D</span></span>, rather than the usual
<spanclass="extract"><spanclass="ConsoleText-extract-syntax">Woven</span></span> subdirectory of the web in question.
<pclass="commentary">By default, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-weave</span></span> makes an HTML representation of the program. (On a larger
by following a "pattern", and it has several patterns built in, notably <spanclass="extract"><spanclass="ConsoleText-extract-syntax">HTML</span></span>,
<spanclass="extract"><spanclass="ConsoleText-extract-syntax">Ebook</span></span> and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">TeX</span></span>.
<pclass="commentary">Running Inweb with <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-weave-as P</span></span> tells it to weave with pattern <spanclass="extract"><spanclass="ConsoleText-extract-syntax">P</span></span>; the
plain command <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-weave</span></span> is equivalent to <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-weave-as HTML</span></span>. The <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Ebook</span></span> pattern
<pclass="commentary">Inweb automatically creates <spanclass="extract"><spanclass="ConsoleText-extract-syntax">twinprimes.tex</span></span> and runs it through <spanclass="extract"><spanclass="ConsoleText-extract-syntax">pdftex</span></span>
to produce <spanclass="extract"><spanclass="ConsoleText-extract-syntax">twinprimes.pdf</span></span>: it reads over the TeX log file to see how
many pages that comes to, and reports back. All being well, the <spanclass="extract"><spanclass="ConsoleText-extract-syntax">.tex</span></span>
and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">.log</span></span> files are silently removed, leaving just <spanclass="extract"><spanclass="ConsoleText-extract-syntax">twinprimes.pdf</span></span> behind.
<pclass="commentary firstcommentary"><aid="SP4"class="paragraph-anchor"></a><b>§4. Multi-section webs. </b>The <spanclass="extract"><spanclass="ConsoleText-extract-syntax">twinprimes.inweb</span></span> example was a program so small that it could
<spanclass="extract"><spanclass="ConsoleText-extract-syntax">.w</span></span>. One source file is special, must always be called <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Contents.w</span></span>,
subdirectories called <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Manual</span></span>, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Preliminaries</span></span>, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Chapter 1</span></span>, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Chapter 2</span></span>, ...,
<spanclass="extract"><spanclass="ConsoleText-extract-syntax">Appendix A</span></span>, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Appendix B</span></span>, ...; preliminaries and appendices being optional.
Two in particular, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Woven</span></span> and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Tangled</span></span>, are automatically created by Inweb
<spanclass="plain-syntax"></span><spanclass="element-syntax">Author</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> Graham Nelson</span>
<spanclass="plain-syntax"></span><spanclass="element-syntax">Purpose</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> For handling intermediate Inform code</span>
<pclass="commentary">Note that the program's <spanclass="extract"><spanclass="extract-syntax">Title</span></span> need not be the same as the directory-name
name. The <spanclass="extract"><spanclass="extract-syntax">Purpose</span></span> should be brief enough to fit onto one line. <spanclass="extract"><spanclass="extract-syntax">Licence</span></span> can
also have the US spelling, <spanclass="extract"><spanclass="extract-syntax">License</span></span>; Inweb treats these as equivalent.
<pclass="commentary">The <spanclass="extract"><spanclass="extract-syntax">Language</span></span> is the programming language in which the code is written: much
more on that later on, but for now, the important ones are probably <spanclass="extract"><spanclass="extract-syntax">C</span></span>, <spanclass="extract"><spanclass="extract-syntax">InC</span></span>
and <spanclass="extract"><spanclass="extract-syntax">Plain Text</span></span>.
<pclass="commentary firstcommentary"><aid="SP6"class="paragraph-anchor"></a><b>§6. </b>After the header block of details, then, we have the roster of sections.
<spanclass="extract"><spanclass="extract-syntax">Scan Documentation.w</span></span> in the <spanclass="extract"><spanclass="extract-syntax">Sections</span></span> directory.
<pclass="commentary firstcommentary"><aid="SP7"class="paragraph-anchor"></a><b>§7. Tangling. </b>At this point, it may be worth experimenting with a second mathematical
<pclass="commentary firstcommentary"><aid="SP8"class="paragraph-anchor"></a><b>§8. </b>It is legal in some circumstances to tangle only part of a web. This is done
<pclass="commentary firstcommentary"><aid="SP9"class="paragraph-anchor"></a><b>§9. </b>In some C programs, it's useful to require that a header file be added to
<pclass="commentary">to the contents page of a web. The heacer file <spanclass="extract"><spanclass="extract-syntax">H</span></span> in question should then
<pclass="commentary firstcommentary"><aid="SP10"class="paragraph-anchor"></a><b>§10. Weaving. </b>As with all-in-one webs, the commands for weaving are like so:
<pclass="commentary firstcommentary"><aid="SP11"class="paragraph-anchor"></a><b>§11. </b>After setting <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-weave</span></span> or <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-weave-as</span></span>, we can also optionally choose a
<pclass="commentary">The opposite extreme from <spanclass="extract"><spanclass="ConsoleText-extract-syntax">all</span></span> is <spanclass="extract"><spanclass="ConsoleText-extract-syntax">sections</span></span>. This still weaves the entire
<pclass="commentary">Those abbreviated names <spanclass="extract"><spanclass="extract-syntax">S-tgc</span></span> and <spanclass="extract"><spanclass="extract-syntax">S-tsoe</span></span> are cut down from the full
<pclass="commentary">An intermediate level of granularity is the range <spanclass="extract"><spanclass="extract-syntax">chapters</span></span>, which makes
example, the range <spanclass="extract"><spanclass="extract-syntax">2</span></span> means "just Chapter 2". The Preliminaries alone is <spanclass="extract"><spanclass="extract-syntax">P</span></span>;
the Manual, <spanclass="extract"><spanclass="extract-syntax">M</span></span>. Appendix A, B, C are <spanclass="extract"><spanclass="extract-syntax">A</span></span>, <spanclass="extract"><spanclass="extract-syntax">B</span></span>, <spanclass="extract"><spanclass="extract-syntax">C</span></span> and so on. (This is why
example, <spanclass="extract"><spanclass="extract-syntax">S/tgc</span></span> and <spanclass="extract"><spanclass="extract-syntax">S/tsoe</span></span> in the Goldbach web example, or <spanclass="extract"><spanclass="extract-syntax">2/ec</span></span> for
predict, run with <spanclass="extract"><spanclass="extract-syntax">-sequential</span></span> to have them simply be <spanclass="extract"><spanclass="extract-syntax">X/s1</span></span>, <spanclass="extract"><spanclass="extract-syntax">X/s2</span></span>, ...,
within each chapter, where <spanclass="extract"><spanclass="extract-syntax">X</span></span> is the chapter range.
<pclass="commentary firstcommentary"><aid="SP13"class="paragraph-anchor"></a><b>§13. Weave tags. </b>An alternative to a range is to specify a tag. Rather than weaving contiguous
paragraph containing a <spanclass="extract"><spanclass="extract-syntax">typedef struct</span></span> with the tag <spanclass="extract"><spanclass="extract-syntax">Structures</span></span>. So,
illustration is automatically tagged <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Figures</span></span>, and any paragraph in an
<spanclass="extract"><spanclass="ConsoleText-extract-syntax">InC</span></span> web which defines Preform grammar is automatically tagged <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Preform</span></span>.
<pclass="commentary">Here the tag is just <spanclass="extract"><spanclass="extract-syntax">Algorithms</span></span>, but when a <spanclass="extract"><spanclass="extract-syntax">-weave-to Algorithms</span></span> is
<pclass="commentary">Beyond that, an entire section can be tagged from the <spanclass="extract"><spanclass="extract-syntax">Contents.w</span></span> page.
<pclass="commentary">Note that if we <spanclass="extract"><spanclass="extract-syntax">-weave-to</span></span> a tag which does not exist - or rather, which no
<pclass="commentary firstcommentary"><aid="SP14"class="paragraph-anchor"></a><b>§14. Modules. </b>Up to now, the webs described have all been self-contained: one web makes
On the other hand, the Inform project also includes a module called <spanclass="extract"><spanclass="extract-syntax">inter</span></span>
which is used only by the core compiler <spanclass="extract"><spanclass="extract-syntax">inform7</span></span> and by a wrapper utility
also called <spanclass="extract"><spanclass="extract-syntax">inter</span></span>; in fact, <spanclass="extract"><spanclass="extract-syntax">inform7</span></span> is entirely divided up into modules,
<pclass="commentary firstcommentary"><aid="SP15"class="paragraph-anchor"></a><b>§15. </b>It makes little sense to tangle a module on its own. Instead, a web which
<pclass="commentary firstcommentary"><aid="SP16"class="paragraph-anchor"></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 <spanclass="extract"><spanclass="ConsoleText-extract-syntax">W</span></span> to import a module <spanclass="extract"><spanclass="ConsoleText-extract-syntax">M</span></span>,
it looks for a web directory called <spanclass="extract"><spanclass="ConsoleText-extract-syntax">M-module</span></span> (note the hyphen). For
example, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">Import: fruit</span></span> would look for the directory <spanclass="extract"><spanclass="ConsoleText-extract-syntax">fruit-module</span></span>. Inweb
</li><li>(2) In the directory containing <spanclass="extract"><spanclass="ConsoleText-extract-syntax">W</span></span> (i.e., one directory higher up).
</li><li>(3) Directly inside Inweb's own web directory.
</li><li>(4) In the directory specified by <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-import-from D</span></span> at the command line, if any.
<pclass="commentary firstcommentary"><aid="SP17"class="paragraph-anchor"></a><b>§17. The section catalogue. </b>Inweb can do a handful of other things. One is to list the contents of a web:
<ulclass="items"><li>(a) <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-catalogue</span></span> (or <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-catalog</span></span>) lists the sections in the web.
</li><li>(b) <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-structures</span></span> lists the sections, and all of the structure definitions
</li><li>(c) <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-functions</span></span> lists the sections, with all structure definitions and also
<pclass="commentary">In addition, for debugging purposes, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">-scan</span></span> shows how Inweb is parsing lines
<pclass="commentary firstcommentary"><aid="SP18"class="paragraph-anchor"></a><b>§18. Makefile. </b>As mentioned earlier, Inweb can construct a suitable makefile for a web:
<pclass="commentary">creates a makefile for the web <spanclass="extract"><spanclass="ConsoleText-extract-syntax">W</span></span> and stores it in <spanclass="extract"><spanclass="ConsoleText-extract-syntax">M</span></span>. For example,
<pclass="commentary">but this can be changed by using <spanclass="extract"><spanclass="extract-syntax">-prototype S</span></span>, which tells Inweb to use
<spanclass="extract"><spanclass="extract-syntax">S</span></span> as the script. If a <spanclass="extract"><spanclass="extract-syntax">-prototype</span></span> is given, then there's no need to
<pclass="commentary firstcommentary"><aid="SP19"class="paragraph-anchor"></a><b>§19. Gitignore. </b>A similar convenience exists for users who want to use the git source control
<pclass="commentary firstcommentary"><aid="SP20"class="paragraph-anchor"></a><b>§20. README files. </b>Repositories at Github customarily have <spanclass="extract"><spanclass="ConsoleText-extract-syntax">README.mk</span></span> files, in Markdown
<pclass="commentary">expands a script called <spanclass="extract"><spanclass="ConsoleText-extract-syntax">READMEscript.txt</span></span> into <spanclass="extract"><spanclass="ConsoleText-extract-syntax">README.mk</span></span>. Alternatively,
<pclass="commentary firstcommentary"><aid="SP21"class="paragraph-anchor"></a><b>§21. </b>Everything in the script is copied over verbatim except where the <spanclass="extract"><spanclass="ConsoleText-extract-syntax">@</span></span> character
<spanclass="extract"><spanclass="ConsoleText-extract-syntax">args</span></span> is a comma-separated list of fragments of text, which can themselves
contain further uses of <spanclass="extract"><spanclass="ConsoleText-extract-syntax">@</span></span>. (If these fragments of text need to contain
commas or brackets, they can be put into single quotes: <spanclass="extract"><spanclass="ConsoleText-extract-syntax">@thus(4,',')</span></span> has
two arguments, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">4</span></span> and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">,</span></span>.) Three functions are built in:
<ulclass="items"><li>(a) <spanclass="extract"><spanclass="ConsoleText-extract-syntax">@version(A)</span></span> expands to the version number of <spanclass="extract"><spanclass="ConsoleText-extract-syntax">A</span></span>, which is normally the
</li><li>(b) <spanclass="extract"><spanclass="ConsoleText-extract-syntax">@purpose(A)</span></span> is the same, but for the <spanclass="extract"><spanclass="ConsoleText-extract-syntax">[[Purpose]]</span></span> of a web. It's
</li><li>(c) <spanclass="extract"><spanclass="ConsoleText-extract-syntax">@var(A,D)</span></span> is more general, and reads the bibliographic datum <spanclass="extract"><spanclass="ConsoleText-extract-syntax">D</span></span> from
the web indicated by <spanclass="extract"><spanclass="ConsoleText-extract-syntax">A</span></span>. In fact, <spanclass="extract"><spanclass="ConsoleText-extract-syntax">@version(A)</span></span> is an abbreviation for
<spanclass="extract"><spanclass="ConsoleText-extract-syntax">@var(A,Version Number)</span></span> and <spanclass="extract"><spanclass="ConsoleText-extract-syntax">@purpose(A)</span></span> for <spanclass="extract"><spanclass="ConsoleText-extract-syntax">@var(A,Purpose)</span></span>, so this
<pclass="commentary firstcommentary"><aid="SP22"class="paragraph-anchor"></a><b>§22. </b>It is also possible to define new functions. For example:
<pclass="commentary">The definition lies between <spanclass="extract"><spanclass="extract-syntax">@define</span></span> and <spanclass="extract"><spanclass="extract-syntax">@end</span></span> commands. This one takes
to as <spanclass="extract"><spanclass="extract-syntax">@title</span></span>, <spanclass="extract"><spanclass="extract-syntax">@path</span></span> and <spanclass="extract"><spanclass="extract-syntax">@topic</span></span>. Functions are free to use other
it is actually expanded. A definition of one function <spanclass="extract"><spanclass="extract-syntax">A</span></span> can refer to another
function <spanclass="extract"><spanclass="extract-syntax">B</span></span> not yet defined; but any actual use of <spanclass="extract"><spanclass="extract-syntax">A</span></span> must be made after
both <spanclass="extract"><spanclass="extract-syntax">A</span></span> and <spanclass="extract"><spanclass="extract-syntax">B</span></span> have been defined. So, basically, declare before use.
<pclass="commentary firstcommentary"><aid="SP23"class="paragraph-anchor"></a><b>§23. Semantic version numbering and build metadata. </b>When Inweb reads in a web, it also looks for a file called <spanclass="extract"><spanclass="extract-syntax">build.txt</span></span> in
<pclass="commentary">The bibliographic variables <spanclass="extract"><spanclass="extract-syntax">Prerelease</span></span> and so on are then set from this
<pclass="commentary">then the semver would be <spanclass="extract"><spanclass="extract-syntax">6.2.12-alpha.1+6Q26</span></span>. This is accessible within
<pclass="commentary firstcommentary"><aid="SP24"class="paragraph-anchor"></a><b>§24. </b>A special advancing mechanism exists to update build numbers and dates.
Running Inweb with <spanclass="extract"><spanclass="extract-syntax">-advance-build W</span></span> checks the build date for web <spanclass="extract"><spanclass="extract-syntax">W</span></span>:
<pclass="commentary">Running <spanclass="extract"><spanclass="extract-syntax">-advance-build-file B</span></span> does this for a stand-alone build file <spanclass="extract"><spanclass="extract-syntax">B</span></span>,