<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>Advanced Weaving with Patterns</b></li></ul></div>
<pclass="purpose">Customise your weave by creating a new pattern.</p>
<pclass="commentary firstcommentary"><aid="SP1"class="paragraph-anchor"></a><b>§1. Patterns versus formats. </b>Every weave produces output in a "format". The formats are built in to Inweb,
<pclass="commentary firstcommentary"><aid="SP2"class="paragraph-anchor"></a><b>§2. </b>A pattern definition is a directory containing various files, which we'll
<ulclass="items"><li>(a) The location given by the <spanclass="extract"><spanclass="extract-syntax">patterns</span></span> command in the current colony file,
<spanclass="extract"><spanclass="ConsoleText-extract-syntax">inweb/Examples/goldbach/Patterns/Tapestry</span></span> and then <spanclass="extract"><spanclass="ConsoleText-extract-syntax">inweb/Patterns/Tapestry</span></span>.
<pclass="commentary firstcommentary"><aid="SP3"class="paragraph-anchor"></a><b>§3. Basic settings. </b>Patterns allow for extensive customisation of the woven output, especially
<spanclass="plain-syntax"></span><spanclass="element-syntax">name</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> Tapestry based on HTML</span>
<pclass="commentary firstcommentary"><aid="SP4"class="paragraph-anchor"></a><b>§4. </b>There are then a handful of other, optional, settings. The following are
<pclass="commentary">sets the format. At present, this must be <spanclass="extract"><spanclass="extract-syntax">HTML</span></span>, <spanclass="extract"><spanclass="extract-syntax">plain</span></span> (plain text),
<spanclass="extract"><spanclass="extract-syntax">ePub</span></span>, <spanclass="extract"><spanclass="extract-syntax">TeX</span></span>, or <spanclass="extract"><spanclass="extract-syntax">TestingInweb</span></span>.
<pclass="commentary">tells the weaver to assume the range <spanclass="extract"><spanclass="extract-syntax">R</span></span>, if the user tries to weave a
<pclass="commentary firstcommentary"><aid="SP5"class="paragraph-anchor"></a><b>§5. </b>Bibliographic data can also be set, but this applies only to the current
<spanclass="plain-syntax"></span><spanclass="element-syntax">bibliographic data</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> K = V</span>
<pclass="commentary">tells the weaver to override the bibliographic data on any web it weaves, setting
the key <spanclass="extract"><spanclass="extract-syntax">K</span></span> to the value <spanclass="extract"><spanclass="extract-syntax">V</span></span>. For example:
<spanclass="plain-syntax"></span><spanclass="element-syntax">bibliographic data</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> Booklet Title = A formal grammar for Inform 7</span>
<pclass="commentary firstcommentary"><aid="SP6"class="paragraph-anchor"></a><b>§6. </b>It can be useful to do some post-processing after each woven file is made.
For an example, see the <spanclass="extract"><spanclass="extract-syntax">PDFTeX</span></span> pattern, which simply uses the <spanclass="extract"><spanclass="extract-syntax">TeX</span></span> pattern
to make a TeX file, and then runs it through the <spanclass="extract"><spanclass="extract-syntax">pdftex</span></span> command-line tool.
This is done by giving the necessary commands in the pattern file:
<spanclass="plain-syntax"></span><spanclass="element-syntax">name</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> PDFTeX based on TeX</span>
<pclass="commentary">Here <spanclass="extract"><spanclass="extract-syntax">WOVEN</span></span> expands to the filename of the file which has just been woven,
<pclass="commentary firstcommentary"><aid="SP7"class="paragraph-anchor"></a><b>§7. Plugins and assets. </b>Plugins are named bundles of resources which are sometimes added to a weave,
<ulclass="items"><li>(a) includes <spanclass="extract"><spanclass="extract-syntax">MathJax3</span></span> if the woven file needs mathematics notation;
</li><li>(b) includes <spanclass="extract"><spanclass="extract-syntax">Breadcrumbs</span></span> if it has a breadcrumb navigation trail;
</li><li>(c) includes <spanclass="extract"><spanclass="extract-syntax">Carousel</span></span> if it has any image carousels;
</li><li>(d) includes <spanclass="extract"><spanclass="extract-syntax">Popups</span></span> if it has any clickable popups (for example, to show
<ulclass="items"><li>(a) <spanclass="extract"><spanclass="extract-syntax">MathJax3</span></span> is an excellent rendering system for mathematics on the web: see
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">Bigfoot</span></span> may eventually need to be simplified and rewritten: its big feet
<pclass="commentary firstcommentary"><aid="SP8"class="paragraph-anchor"></a><b>§8. </b>So what's in a plugin? A plugin is simply a set of "assets", which are
individual files stored in the plugin's directory. A typical asset might be
a CSS file to help making web pages, or a file of TeX macros to help
typeset a PDF.
</p>
<pclass="commentary">Plugin inclusion happens like this:
</p>
<ulclass="items"><li>(a) for each file Inweb weaves, it includes only the plugins it needs;
</li><li>(b) if it needs <spanclass="extract"><spanclass="extract-syntax">X</span></span>, Inweb includes every asset — meaning, every file whose
name does not begin with a <spanclass="extract"><spanclass="extract-syntax">.</span></span>— from the <spanclass="extract"><spanclass="extract-syntax">X</span></span> subdirectory of the pattern,
or from the <spanclass="extract"><spanclass="extract-syntax">X</span></span> subdirectory of any pattern it is based on;
</li><li>(c) but it never includes the same-named asset twice.
<pclass="commentary firstcommentary"><aid="SP9"class="paragraph-anchor"></a><b>§9. </b>This means it's possible to supply your own version of any plugin you would
own pattern. Files in your version will prevail over files in the built-in one.
</p>
<pclass="commentary">As a simple example, suppose you want a pattern just like <spanclass="extract"><spanclass="extract-syntax">GitHubPages</span></span> but
which uses monospaced fonts throughout, for commentary as well as code. The
<spanclass="plain-syntax"></span><spanclass="element-syntax">name</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> MonoGitHub based on GitHubPages</span>
<pclass="commentary">Then create just one subdirectory of <spanclass="extract"><spanclass="extract-syntax">MonoGitHub</span></span>, called <spanclass="extract"><spanclass="extract-syntax">Base</span></span>, and create
a single file in that called <spanclass="extract"><spanclass="extract-syntax">Fonts.css</span></span>, reading:
<pclass="commentary">And that should work nicely. What happens here is that when pages are woven
with <spanclass="extract"><spanclass="extract-syntax">MonoGitHub</span></span>, they use this custom <spanclass="extract"><spanclass="extract-syntax">Fonts.css</span></span> instead of the one in
the <spanclass="extract"><spanclass="extract-syntax">Base</span></span> plugin from <spanclass="extract"><spanclass="extract-syntax">HTML</span></span>. (<spanclass="extract"><spanclass="extract-syntax">MonoGitHub</span></span> is based on <spanclass="extract"><spanclass="extract-syntax">GitHubPages</span></span>, but
that in turn is based on <spanclass="extract"><spanclass="extract-syntax">HTML</span></span>.) All the other files of <spanclass="extract"><spanclass="extract-syntax">Base</span></span> remain as
they were, and there's no need to provide duplicates here.
<pclass="commentary firstcommentary"><aid="SP10"class="paragraph-anchor"></a><b>§10. </b>But wait, there's more. How is an asset actually "included"? The pattern
<pclass="commentary">This admittedly cryptic line tells Inweb that when it includes plugins for
this pattern, any assets ending <spanclass="extract"><spanclass="extract-syntax">.tex</span></span> should be "embedded", rather than
copied. There are four things it can do:
</p>
<ulclass="items"><li>(1) <spanclass="extract"><spanclass="extract-syntax">copy</span></span>. This is the default, and means that the file is simply copied
into the weave directory, or into the <spanclass="extract"><spanclass="extract-syntax">assets</span></span> directory specified in the
colony file, if the user gave one with <spanclass="extract"><spanclass="extract-syntax">-colony</span></span>.
</li><li>(2) <spanclass="extract"><spanclass="extract-syntax">private copy</span></span>. The same, but this is never put into the shared <spanclass="extract"><spanclass="extract-syntax">assets</span></span>
directory: it's always copied alongside the woven files for the web.
</li><li>(3) <spanclass="extract"><spanclass="extract-syntax">embed</span></span>. The file is not copied. Instead, its entire contents are
pasted into the woven file itself, when the <spanclass="extract"><spanclass="extract-syntax">[[Plugins]]</span></span> placeholder in
the template is expanded (see below). Do not use this for binary files.
</li><li>(4) <spanclass="extract"><spanclass="extract-syntax">collate</span></span>. The file is not copied. Instead, its entire contents are
pasted into the woven file itself, when the <spanclass="extract"><spanclass="extract-syntax">[[Plugins]]</span></span> placeholder in
the template is expanded (see below); but this is done as a further collation,
not a simple transcription, so any placeholders found in the file will
themselves be expanded. Do not use this for binary files.
<pclass="commentary firstcommentary"><aid="SP11"class="paragraph-anchor"></a><b>§11. </b>In addition, the pattern can specify that some text referring to the
<pclass="commentary firstcommentary"><aid="SP12"class="paragraph-anchor"></a><b>§12. Embeddings. </b>Patterns with the HTML format may also want to provide "embeddings". These
are for embedded video/audio or other gadgets, and each different "service" —
<spanclass="extract"><spanclass="extract-syntax">YouTube</span></span>, <spanclass="extract"><spanclass="extract-syntax">SoundCloud</span></span>, and such — is represented by an embedding file.
Inweb looks for these in the pattern's <spanclass="extract"><spanclass="extract-syntax">Embedding</span></span> subdirectory, if there is
one; then it tries in the pattern we are based on, and so on until it gives
<pclass="commentary firstcommentary"><aid="SP13"class="paragraph-anchor"></a><b>§13. Syntax colouring. </b>No two people ever agree on the ideal colour scheme for syntax-colouring,
<pclass="commentary">A pattern based on HTML may provide a subdirectory called <spanclass="extract"><spanclass="extract-syntax">Colouring</span></span>. If it
does, then the contents will be CSS files which provide colour schemes for
different programming languages. The scheme <spanclass="extract"><spanclass="extract-syntax">Colours.css</span></span> is the fallback,
and is used for any language not providing a colour scheme; otherwise, a
language called, say, <spanclass="extract"><spanclass="extract-syntax">Anaconda</span></span> would be coloured by <spanclass="extract"><spanclass="extract-syntax">Anaconda-Colours.css</span></span>.
Inweb looks first in the <spanclass="extract"><spanclass="extract-syntax">Colouring</span></span> directory of the current pattern, then
<spanclass="plain-syntax"></span><spanclass="element-syntax">name</span><spanclass="plain-syntax">:</span><spanclass="string-syntax"> SnakeSkin based on HTML</span>
<pclass="commentary">(or perhaps based on <spanclass="extract"><spanclass="extract-syntax">GitHubPages</span></span>, if you want to host there); and then
<pclass="commentary firstcommentary"><aid="SP14"class="paragraph-anchor"></a><b>§14. </b>Note that Inweb supports multiple languages in the same weave, each having
<pclass="commentary firstcommentary"><aid="SP15"class="paragraph-anchor"></a><b>§15. Templates. </b>The final possible ingredient for a pattern is a "template"; this is a file
Inweb looks for <spanclass="extract"><spanclass="extract-syntax">template-body.html</span></span> (or <spanclass="extract"><spanclass="extract-syntax">.tex</span></span>, or <spanclass="extract"><spanclass="extract-syntax">.txt</span></span>— whatever
file extension is used for files in the current format), and uses that
to top and tail the weaver's output. Not all formats or patterns need that.
produce navigation sidebars in HTML, and to inject HTML into headers for
the sake of plugins. But the author of a pattern can't control that, whereas
she can write her own <spanclass="extract"><spanclass="extract-syntax">template-body.html</span></span> and/or <spanclass="extract"><spanclass="extract-syntax">template-index.html</span></span>.
<pclass="commentary firstcommentary"><aid="SP16"class="paragraph-anchor"></a><b>§16. </b>For example, here is a template file for making an HTML page:
<ulclass="items"><li>(a) <spanclass="extract"><spanclass="extract-syntax">[[Weave Content]]</span></span> expands to the body of the web page — the headings,
<pclass="commentary firstcommentary"><aid="SP17"class="paragraph-anchor"></a><b>§17. </b>Other placeholders, not used in the example above, include:
<ulclass="items"><li>(a) <spanclass="extract"><spanclass="extract-syntax">[[Navigation]]</span></span> expands to the navigation sidebar in use when weaving
<pclass="commentary firstcommentary"><aid="SP18"class="paragraph-anchor"></a><b>§18. </b>The <spanclass="extract"><spanclass="extract-syntax">template-index.html</span></span> file has access to additional placeholders
<spanclass="plain-syntax"></span><spanclass="function-syntax">[[Complete Leafname]]</span><spanclass="plain-syntax"></span><spanclass="function-syntax">[[Complete Extent]]</span><spanclass="plain-syntax"></span><spanclass="function-syntax">[[Complete PDF Size]]</span>
<spanclass="plain-syntax"></span><spanclass="function-syntax">[[Chapter Extent]]</span><spanclass="plain-syntax"></span><spanclass="function-syntax">[[Chapter PDF Size]]</span><spanclass="plain-syntax"></span><spanclass="function-syntax">[[Chapter Errors]]</span>
<spanclass="plain-syntax"></span><spanclass="function-syntax">[[Section Extent]]</span><spanclass="plain-syntax"></span><spanclass="function-syntax">[[Section PDF Size]]</span><spanclass="plain-syntax"></span><spanclass="function-syntax">[[Section Errors]]</span>
<pclass="commentary firstcommentary"><aid="SP19"class="paragraph-anchor"></a><b>§19. </b><spanclass="extract"><spanclass="extract-syntax">[[Repeat Chapter]]</span></span> and <spanclass="extract"><spanclass="extract-syntax">[[Repeat Section]]</span></span> begin blocks of lines which
<pclass="commentary">can all be used to refer to the current module. <spanclass="extract"><spanclass="extract-syntax">[[Module Page]]</span></span> expands
to the relative URL of the module's own woven HTML form, provided that
the module is listed as a member of the current colony file.
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">[[Select ...]]</span></span> and <spanclass="extract"><spanclass="extract-syntax">[[End Select]</span></span> form a block which behaves like
<pclass="commentary firstcommentary"><aid="SP20"class="paragraph-anchor"></a><b>§20. </b>Finally, there is very limited support for conditionals with
<spanclass="extract"><spanclass="extract-syntax">[[If CONDITION]]</span></span>, an optional <spanclass="extract"><spanclass="extract-syntax">Else</span></span>, and a compulsory <spanclass="extract"><spanclass="extract-syntax">Endif</span></span>.
Very few conditions are in fact allowed:
</p>
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">[[If Chapters]]</span></span> tests whether the current web is divided into chapters,
the alternative being that all the sections are in a notional chapter just
called <spanclass="extract"><spanclass="extract-syntax">Sections</span></span>.
</p>
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">[[If Modules]]</span></span> tests whether the current web imports any modules.
</p>
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">[[If Chapter Purpose]]</span></span>, inside a <spanclass="extract"><spanclass="extract-syntax">[[Repeat Chapter]]</span></span>, tests whether the
current chapter has a (non-empty) purpose text. Similarly for <spanclass="extract"><spanclass="extract-syntax">[[If Section Purpose]]</span></span>
and <spanclass="extract"><spanclass="extract-syntax">[[If Module Purpose]].
</span></span></p>
<pclass="commentary"><spanclass="extract"><spanclass="extract-syntax">[[If Module Page]]</span></span>, inside a <spanclass="extract"><spanclass="extract-syntax">[[Repeat Module]]</span></span>, tests whether the module
appears (under its own name, i.e., not by a different name) as a member in
the colony file, if there is one. In effect, this can be used to test whether
it is safe to make a link to the module's own woven pages using <spanclass="extract"><spanclass="extract-syntax">[[Module Page]]</span></span>.
