312 lines
18 KiB
HTML
312 lines
18 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Making Weaves into Websites</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="../index.html">
|
|
<img src="../docs-src/Figures/Octagram184x184.png" width=72 height=72">
|
|
</a></h1>
|
|
<ul><li><a href="index.html"><span class="selectedlink">inweb</span></a></li>
|
|
</ul><h2>Foundation Module</h2><ul>
|
|
<li><a href="../foundation-module/index.html">foundation</a></li>
|
|
<li><a href="../foundation-test/index.html">foundation-test</a></li>
|
|
</ul><h2>Example Webs</h2><ul>
|
|
<li><a href="../goldbach/index.html">goldbach</a></li>
|
|
<li><a href="../twinprimes/twinprimes.html">twinprimes</a></li>
|
|
<li><a href="../eastertide/index.html">eastertide</a></li>
|
|
</ul><h2>Repository</h2><ul>
|
|
<li><a href="https://github.com/ganelson/inweb"><img src="../github.png" height=18> github</a></li>
|
|
</ul><h2>Related Projects</h2><ul>
|
|
<li><a href="../../../inform/docs/index.html">inform</a></li>
|
|
<li><a href="../../../intest/docs/index.html">intest</a></li>
|
|
|
|
</ul>
|
|
</nav>
|
|
<main role="main">
|
|
|
|
<!--Weave of 'Making Weaves into Websites' generated by Inweb-->
|
|
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="index.html">inweb</a></li><li><a href="index.html#M">Manual</a></li><li><b>Making Weaves into Websites</b></li></ul><p class="purpose">How to present one or more weaves on a shared website, for example using GitHub Pages.</p>
|
|
|
|
<ul class="toc"><li><a href="M-mwiw.html#SP1">§1. GitHub Pages</a></li><li><a href="M-mwiw.html#SP2">§2. Colonies</a></li><li><a href="M-mwiw.html#SP6">§6. The navigation sidebar</a></li><li><a href="M-mwiw.html#SP9">§9. The trail of breadcrumbs</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="inwebparagraph"><a id="SP1"></a><b>§1. GitHub Pages. </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: the <code class="display"><span class="extract">docs</span></code> subdirectory
|
|
of a repository is simply served as a website, once this is enabled from the
|
|
owner's Github control panel.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">First, the simple case: our repository is a single web, called <code class="display"><span class="extract">example</span></code>.
|
|
We suppose that the current working directory is one up from this, and contains
|
|
the installation of <code class="display"><span class="extract">inweb</span></code> as well as <code class="display"><span class="extract">example</span></code>. Then:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="element">$</span><span class="plain"> </span><span class="functiontext">ls</span>
|
|
<span class="plain">inweb example</span>
|
|
<span class="element">$</span><span class="plain"> </span><span class="functiontext">inweb/Tangled/inweb</span><span class="plain"> example</span><span class="identifier"> -weave-as</span><span class="plain"> GitHubPages</span><span class="identifier"> -weave-into</span><span class="plain"> example/docs</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">will do the trick. (<code class="display"><span class="extract">GitHubPages</span></code> is a pattern refining the default <code class="display"><span class="extract">HTML</span></code> one.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP2"></a><b>§2. Colonies. </b>A collection of webs gathered in one place is, for want of a better word,
|
|
called a "colony". (Some social species of spiders form colonies, and share
|
|
webs which are collectively woven.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Inweb provides support for colonies, and this enables us to manage the more
|
|
complicated case where there are multiple webs in a repository, but which need
|
|
to share the same <code class="display"><span class="extract">docs</span></code> area. Now the problem to tackle is that we have two
|
|
or more webs in our <code class="display"><span class="extract">example</span></code> repository, one at <code class="display"><span class="extract">example/aleph</span></code>, the other
|
|
at <code class="display"><span class="extract">example/beth</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The first thing to do is to write a colony file — we could put this anywhere
|
|
in the repository, but let's say at <code class="display"><span class="extract">example/colony.txt</span></code>:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">pattern: GitHubPages</span>
|
|
<span class="plain">web: "aleph" at "example/aleph" in "example/docs/aleph"</span>
|
|
<span class="plain">web: "beth" at "example/beth" in "example/docs/beth"</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This is, in effect, a set of presets of Inweb's command-line settings. We can
|
|
now write, for example,
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="element">$</span><span class="plain"> </span><span class="functiontext">inweb/Tangled/inweb</span><span class="identifier"> -colony</span><span class="plain"> example/colony.txt</span><span class="identifier"> -member</span><span class="plain"> beth</span><span class="identifier"> -weave</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">and this is equivalent to
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="element">$</span><span class="plain"> </span><span class="functiontext">inweb/Tangled/inweb</span><span class="plain"> example/beth</span><span class="identifier"> -weave -weave-into</span><span class="plain"> example/docs/beth</span><span class="identifier"> -weave-as</span><span class="plain"> GitHubPages</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The idea is that <code class="display"><span class="extract">-member M</span></code> chooses <code class="display"><span class="extract">M</span></code> as the current web, and automatically
|
|
sets its default settings: <code class="display"><span class="extract">-weave-to</span></code>, <code class="display"><span class="extract">-weave-as</span></code>, <code class="display"><span class="extract">-navigation</span></code> and
|
|
<code class="display"><span class="extract">-breadcrumb</span></code> are all handled like this.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP3"></a><b>§3. </b>These pathnames are taken relative to the current working directory of
|
|
the user (not to the location of the colony file). For <a href="index.html" class="internal">inweb</a>, this
|
|
is conventionally the directory above the actual web, and that's why the
|
|
file needs to say:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">home: inweb/docs</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This overrides the default setting (just <code class="display"><span class="extract">docs</span></code>), and is the path to the
|
|
home page of the Github Docs area for the repository.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP4"></a><b>§4. </b>The use of a colony also enables cross-references from the weave of one
|
|
web to the weave of another, even when they are independent programs. For
|
|
example, a section of code in <code class="display"><span class="extract">beth</span></code> could say:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Handling file system problems is more of a job for //aleph// than</span>
|
|
<span class="plain">for us, so we'll just proceed. (See //aleph: Error Recovery//.)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">and these links would both work. Without the use of a colony file, neither
|
|
one could be recognised, because Inweb wouldn't know what <code class="display"><span class="extract">aleph</span></code> even was.
|
|
To demonstrate that right here, see <a href="../goldbach/S-tsoe.html" class="internal">The Sieve of Eratosthenes (in goldbach)</a>.
|
|
That last sentence was typed as:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">To demonstrate that right here, see //goldbach: The Sieve of Eratosthenes//.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Cross-references to other webs or modules in the same colony can be to chapters
|
|
or sections, or simply to the entire web in question — see <a href="../goldbach/index.html" class="internal">goldbach</a> —
|
|
but not to functions or types in those webs: that would require Inweb to read
|
|
every web in the colony into memory, which would slow it down too much.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP5"></a><b>§5. </b>As a more sustained example, here is the current version of the colony file
|
|
for the Inweb repository:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">home: inweb/docs</span>
|
|
|
|
<span class="plain">navigation: inweb/docs/docs-src/nav.html</span>
|
|
<span class="plain">pattern: GitHubPages</span>
|
|
|
|
<span class="plain">breadcrumbs: none</span>
|
|
<span class="plain">web: "overview" at "inweb/docs/docs-src/index.inweb" in "inweb/docs"</span>
|
|
|
|
<span class="plain">breadcrumbs: "Home: //overview//"</span>
|
|
<span class="plain">web: "inweb" at "inweb" in "inweb/docs/inweb"</span>
|
|
<span class="plain">module: "foundation" at "inweb/foundation-module" in "inweb/docs/foundation-module"</span>
|
|
<span class="plain">web: "foundation-test" at "inweb/foundation-test" in "inweb/docs/foundation-test"</span>
|
|
<span class="plain">web: "goldbach" at "inweb/Examples/goldbach" in "inweb/docs/goldbach"</span>
|
|
<span class="plain">web: "twinprimes" at "inweb/Examples/twinprimes.inweb" in "inweb/docs/twinprimes"</span>
|
|
<span class="plain">web: "eastertide" at "inweb/Examples/eastertide" in "inweb/docs/eastertide"</span>
|
|
|
|
<span class="plain">web: "intest" at "intest" in "intest/docs"</span>
|
|
<span class="plain">web: "inform" at "inform/docs/docs-src/index.inweb" in "inform/docs"</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">As this demonstrates, either webs, or modules, or both, can be declared.
|
|
Each one gives (a) a short name, (b) a location relative to the current
|
|
working directory, and (c) a similar location for its woven collection of
|
|
files. The file can also specify navigation and breadcrumbs material, and
|
|
the pattern; each of these applies to each subsequent declaration until the
|
|
setting in question changes again. (Setting to <code class="display"><span class="extract">none</span></code> removes them.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Also notable here is that the colony contains a single-page web called
|
|
<code class="display"><span class="extract">index.inweb</span></code>. (You can see that it's a single-page web, rather than something
|
|
more substantial, because the location ends <code class="display"><span class="extract">.inweb</span></code> rather than being a
|
|
directory name.) The point of this web is that it weaves to the <code class="display"><span class="extract">index.html</span></code>
|
|
home page; it's referred to in links as being the "overview", because that's
|
|
its name as a web.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP6"></a><b>§6. The navigation sidebar. </b>When assembling large numbers of woven websites together, as is needed for
|
|
example by the main Inform repository's GitHub pages, we need to navigate
|
|
externally as well as internally: that is, the page for one tool will need
|
|
a way to link to pages for other tools.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">This is why the <code class="display"><span class="extract">GitHubPages</span></code> pattern has a navigation sidebar, to the left
|
|
of the main part of each page. The template file contains a special expansion
|
|
written <code class="display"><span class="extract">[[Navigation]]</span></code>, and this expands to the HTML for a column of links.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The pattern also has a row of breadcrumbs along the top, for navigation within
|
|
the current web.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP7"></a><b>§7. </b>By default, Inweb looks for a file called <code class="display"><span class="extract">nav.html</span></code> in two directories: the
|
|
one above the destination, and the destination. If both exist, they are both
|
|
used. If neither exists, the expansion is empty, but no error is produced.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">However, this can be overridden at the command line, with <code class="display"><span class="extract">-navigation N</span></code>,
|
|
where <code class="display"><span class="extract">N</span></code> is the filename for a suitable fragment of navigation HTML, and
|
|
it can also be preset in the Colony file (see above).
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP8"></a><b>§8. </b>Inweb in fact makes it easy to write such navigation files, providing
|
|
commands which mean that little HTML need be written at all. This is the
|
|
one which generates the sidebar visible to the left of the pages on the
|
|
Inweb <code class="display"><span class="extract">docs</span></code> site:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain"><h1>[[Link "overview"]]</span>
|
|
<span class="plain"><img src="[[Docs]]docs-src/Figures/Octagram184x184.png" width=72 height=72"></span>
|
|
<span class="plain"></a></h1></span>
|
|
<span class="plain">[[Item "inweb"]]</span>
|
|
<span class="plain">[[Menu "Foundation Module"]]</span>
|
|
<span class="plain">[[Item "foundation"]]</span>
|
|
<span class="plain">[[Item "foundation-test"]]</span>
|
|
<span class="plain">[[Menu "Example Webs"]]</span>
|
|
<span class="plain">[[Item "goldbach"]]</span>
|
|
<span class="plain">[[Item "twinprimes"]]</span>
|
|
<span class="plain">[[Item "eastertide"]]</span>
|
|
<span class="plain">[[Menu "Repository"]]</span>
|
|
<span class="plain">[[Item "<github.png> github" -> https://github.com/ganelson/inweb]]</span>
|
|
<span class="plain">[[Menu "Related Projects"]]</span>
|
|
<span class="plain">[[Item "inform"]]</span>
|
|
<span class="plain">[[Item "intest"]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">As this shows, there's some HTML for the top left corner area, and then
|
|
a list of items and submenus. <code class="display"><span class="extract">[[Link "overview"]]</span></code> opens a link to the
|
|
colony item called <code class="display"><span class="extract">overview</span></code>; <code class="display"><span class="extract">[[URL "inweb"]]</span></code> writes a minimal-length
|
|
relative URL to reach the named directory, and <code class="display"><span class="extract">[[Docs]]</span></code> to the home page
|
|
of the Github Docs area for the repository. <code class="display"><span class="extract">[[Menu "External"]]</span></code> begins
|
|
a submenu among the items. <code class="display"><span class="extract">[[Item "X"]]</span></code> makes a menu item whose title is
|
|
<code class="display"><span class="extract">X</span></code> and which links to the colony item called <code class="display"><span class="extract">X</span></code>; <code class="display"><span class="extract">[[Item "Y" -> Z]]</span></code> is
|
|
more general, and makes the text <code class="display"><span class="extract">Y</span></code> point to either an external web page,
|
|
recognised by beginning with <code class="display"><span class="extract">http</span></code>, or else a web cross-reference. Thus:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">[[Item "innards" -> //inweb: Programming Languages//]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">would make a menu item called "innards" leading to a section in Chapter 4
|
|
of the Inweb source.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">An item text can begin or end with an icon name, in angle brackets. For
|
|
example:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">[[Item "<github.png> github" -> https://github.com/ganelson/intest]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This icon should be in the <code class="display"><span class="extract">docs</span></code> home of the repository. Note that the
|
|
<code class="display"><span class="extract">GithubPages</span></code> pattern automatically includes the <code class="display"><span class="extract">github.png</span></code> icon, so
|
|
that one's guaranteed to be present.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9"></a><b>§9. The trail of breadcrumbs. </b>Inweb automatically adds web, chapter and section titles to the trail of
|
|
breadcrumbs above each page: for example,
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Beth > Chapter 4 > File Organisation</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">That may be sufficient in itself. However, it's possible to add extra
|
|
crumbs to the left. Suppose we want:
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">Home > Beth > Chapter 4 > File Organisation</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">where Home is a link to <code class="display"><span class="extract">example/docs/index.html</span></code>. One way is to run Inweb
|
|
with <code class="display"><span class="extract">-breadcrumb 'Home:index.html'</span></code>; another is to add this to the Colony
|
|
file, as
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">breadcrumbs: "Home: index.html"</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">We can add more than one, by, e.g., <code class="display"><span class="extract">-breadcrumb 'Home:index.html' -breadcrumb 'Webs: webs.html'</span></code>.
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">breadcrumbs: "Home: index.html" > "Webs: webs.html"</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">The links after the colon can also be Inweb cross-references, so, for example,
|
|
</p>
|
|
|
|
<pre class="display">
|
|
<span class="plain">breadcrumbs: "Overview: //overview//"</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">makes a link to the web/module called <code class="display"><span class="extract">overview</span></code> in the colony file.
|
|
</p>
|
|
|
|
<hr class="tocbar">
|
|
<ul class="toc"><li><a href="M-htwaw.html">Back to 'How to Write a Web'</a></li><li><a href="M-awwp.html">Continue with 'Advanced Weaving with Patterns'</a></li></ul><hr class="tocbar">
|
|
<!--End of weave-->
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|