<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. Ctags. </b>Each time a web is tangled, Inweb writes a <spanclass="extract"><spanclass="ConsoleText-extract-syntax">tags</span></span> file to the web's home
directory, containing a list of <ahref="https://ctags.io"class="external">Universal ctags</a>
for any structures, functions or constant definitions found in the web. You
need do nothing to make this happen, and can ignore the file if it's of no
use. If you are editing a web in certain text editors, though, such as
<ahref="https://www.barebones.com/products/bbedit"class="external">BBEdit</a> for MacOS, then this
should make code completion and definition lookup features work.
</p>
<pclass="commentary">You can however write the file elsewhere:
<pclass="commentary firstcommentary"><aid="SP21"class="paragraph-anchor"></a><b>§21. 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="SP22"class="paragraph-anchor"></a><b>§22. </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="SP23"class="paragraph-anchor"></a><b>§23. </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="SP24"class="paragraph-anchor"></a><b>§24. 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="SP25"class="paragraph-anchor"></a><b>§25. </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>,
