1009 lines
59 KiB
HTML
1009 lines
59 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>How to Write a Web</title>
|
|
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<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="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Carousel.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<script src="../docs-assets/Carousel.js"></script>
|
|
<link href="../docs-assets/Downloads.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<script>
|
|
MathJax = {
|
|
tex: {
|
|
inlineMath: '$', '$'], ['\\(', '\\)'
|
|
},
|
|
svg: {
|
|
fontCache: 'global'
|
|
}
|
|
};
|
|
</script>
|
|
<script type="text/javascript" id="MathJax-script" async
|
|
src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js">
|
|
</script>
|
|
|
|
<script src="http://code.jquery.com/jquery-1.12.4.min.js"
|
|
integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"></script>
|
|
|
|
<script src="../docs-assets/Bigfoot.js"></script>
|
|
<link href="../docs-assets/Bigfoot.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
|
|
|
|
</head>
|
|
<body class="commentary-font">
|
|
<nav role="navigation">
|
|
<h1><a href="../index.html">
|
|
<img src="../docs-assets/Octagram.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="../docs-assets/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 'How to Write a Web' generated by Inweb-->
|
|
<div class="breadcrumbs">
|
|
<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>How to Write a Web</b></li></ul></div>
|
|
<p class="purpose">How to mark up code for literate programming.</p>
|
|
|
|
<ul class="toc"><li><a href="M-htwaw.html#SP1">§1. The title of a section</a></li><li><a href="M-htwaw.html#SP2">§2. Paragraphing</a></li><li><a href="M-htwaw.html#SP6">§6. Conditional compilation</a></li><li><a href="M-htwaw.html#SP7">§7. Commentary</a></li><li><a href="M-htwaw.html#SP12">§12. Code samples and other extraneous matter</a></li><li><a href="M-htwaw.html#SP13">§13. Links</a></li><li><a href="M-htwaw.html#SP14">§14. Cross-references</a></li><li><a href="M-htwaw.html#SP19">§19. Figures</a></li><li><a href="M-htwaw.html#SP20">§20. Carousels</a></li><li><a href="M-htwaw.html#SP21">§21. Video and audio</a></li><li><a href="M-htwaw.html#SP22">§22. Embedded video and audio</a></li><li><a href="M-htwaw.html#SP24">§24. Downloads</a></li><li><a href="M-htwaw.html#SP25">§25. Mathematics notation</a></li><li><a href="M-htwaw.html#SP26">§26. Footnotes</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>§1. The title of a section. </b>In any section file, there will be a few lines at the top which occur before
|
|
the first paragraph of code begins. (The first paragraph begins on the first
|
|
line which starts with an <span class="extract"><span class="extract-syntax">@</span></span> character.)
|
|
</p>
|
|
|
|
<p class="commentary">The first line should be the title of the section, followed by a full stop.
|
|
For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> The Sieve of Eratosthenes.</span>
|
|
</pre>
|
|
<p class="commentary">A section title must contain only filename-safe characters, and it's probably
|
|
wise to make them filename-safe on all platforms: so don't include either
|
|
kind of slash, or a colon, and in general go easy on punctuation marks.
|
|
</p>
|
|
|
|
<p class="commentary">Optionally, a section heading can also specify its own range abbreviation,
|
|
which must be given in round brackets and followed by a colon:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> (S/sieve): The Sieve of Eratosthenes.</span>
|
|
</pre>
|
|
<p class="commentary">If this is not done (and usually it is not), Inweb will construct a range
|
|
abbreviation itself: in this case, it comes up with <span class="extract"><span class="extract-syntax">S/tsoe</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">Subsequent lines of text are then taken as the optional description of the
|
|
purpose of the code in this section. (This is used on contents pages.) For
|
|
example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> A fairly fast way to determine if small numbers are prime, given storage.</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>§2. Paragraphing. </b>A standard paragraph is introduced with an <span class="extract"><span class="extract-syntax">@</span></span> command, which must place
|
|
that magic character in the first column of the line:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@</span><span class="plain-syntax"> This is some comment at the start of a new paragraph, which...</span>
|
|
</pre>
|
|
<p class="commentary">A fancier paragraph with a subheading attached is introduced using the
|
|
<span class="extract"><span class="extract-syntax">@h</span></span> or <span class="extract"><span class="extract-syntax">@heading</span></span> command instead. (This is simply a long and short version
|
|
of the same command.) The text of the subheading then follows, up to the
|
|
first full stop.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@heading</span><span class="plain-syntax"> Reflections on the method.</span>
|
|
</pre>
|
|
<p class="commentary">Paragraphs can contain three ingredients, all optional, but if given then
|
|
given in this order: comment, definitions, and code. The following
|
|
example shows all three being used:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@h</span><span class="plain-syntax"> Primality.</span>
|
|
<span class="plain-syntax"> We provide this as a function which determines whether a number</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">is prime</span><span class="plain-syntax">:</span>
|
|
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@d</span><span class="plain-syntax"> TRUE 1</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@d</span><span class="plain-syntax"> FALSE 0</span>
|
|
|
|
<span class="plain-syntax"> =</span>
|
|
<span class="plain-syntax"> int isprime(int n) {</span>
|
|
<span class="plain-syntax"> if (n <= 1) return FALSE;</span>
|
|
<span class="plain-syntax"> for (int m = 2; m*m <= n; m++)</span>
|
|
<span class="plain-syntax"> if (n % m == 0)</span>
|
|
<span class="plain-syntax"> return FALSE;</span>
|
|
<span class="plain-syntax"> return TRUE;</span>
|
|
<span class="plain-syntax"> }</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>§3. </b>Definitions are made using one of three commands: <span class="extract"><span class="extract-syntax">@d</span></span> or <span class="extract"><span class="extract-syntax">@define</span></span>; or
|
|
<span class="extract"><span class="extract-syntax">@e</span></span> or <span class="extract"><span class="extract-syntax">@enum</span></span>; or <span class="extract"><span class="extract-syntax">@default</span></span>, which is rarely used and has no abbreviation.
|
|
These create new constants in the program, with the values given: they are
|
|
the equivalent of a <span class="extract"><span class="extract-syntax">#define</span></span> directive in C. <span class="extract"><span class="extract-syntax">@define</span></span> is the simpler form.
|
|
For example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@define</span><span class="plain-syntax"> ENIGMATIC_NUMBER 90125</span>
|
|
</pre>
|
|
<p class="commentary">sets <span class="extract"><span class="extract-syntax">ENIGMATIC_NUMBER</span></span> to 90125. Unlike in the C preprocessor, multi-line
|
|
definitions are automatically handled, so for example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@</span><span class="plain-syntax"> The following macro defines a function:</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@d</span><span class="plain-syntax"> EAT_FRUIT(variety)</span>
|
|
<span class="plain-syntax"> int consume_by_##variety(variety *frp) {</span>
|
|
<span class="plain-syntax"> return frp->eat_by_date;</span>
|
|
<span class="plain-syntax"> }</span>
|
|
<span class="plain-syntax"> =</span>
|
|
<span class="plain-syntax"> banana my_banana; /* initialised somewhere else, let's suppose */</span>
|
|
<span class="plain-syntax"> EAT_FRUIT(banana) /* expands with the definition above */</span>
|
|
<span class="plain-syntax"> void consider_fruit(void) {</span>
|
|
<span class="plain-syntax"> printf("The banana has an eat-by date of %d.", consume_by_banana(&my_banana));</span>
|
|
<span class="plain-syntax"> }</span>
|
|
</pre>
|
|
<p class="commentary">In fact, a definition continues until the next definition, or until the code
|
|
part of the paragraph begins, or until the paragraph ends, whichever comes
|
|
first.
|
|
</p>
|
|
|
|
<p class="commentary">Enumerations with <span class="extract"><span class="extract-syntax">@enum</span></span> are a convenience to define enumerated constants.
|
|
For example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@enum</span><span class="plain-syntax"> JANUARY_MNTH from 0</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@enum</span><span class="plain-syntax"> FEBRUARY_MNTH</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@enum</span><span class="plain-syntax"> MARCH_MNTH</span>
|
|
</pre>
|
|
<p class="commentary">and so on, is equivalent to
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@define</span><span class="plain-syntax"> JANUARY_MNTH 0</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@define</span><span class="plain-syntax"> FEBRUARY_MNTH 1</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@define</span><span class="plain-syntax"> MARCH_MNTH 2</span>
|
|
</pre>
|
|
<p class="commentary">What happens is that <span class="extract"><span class="extract-syntax">@enum</span></span> looks at the tail of the name, from the last
|
|
underscore to the end: in this case, <span class="extract"><span class="extract-syntax">_MNTH</span></span>. The first time an enumerated
|
|
value is asked for with this tail, <span class="extract"><span class="extract-syntax">from</span></span> is used to specify the lowest
|
|
number to be used - in the above case, months begin counting from 0. With
|
|
each subsequent <span class="extract"><span class="extract-syntax">_MNTH</span></span> request, <span class="extract"><span class="extract-syntax">@enum</span></span> allocates the next unused value.
|
|
</p>
|
|
|
|
<p class="commentary">All symbols defined with <span class="extract"><span class="extract-syntax">@define</span></span> or <span class="extract"><span class="extract-syntax">@enum</span></span> are global, and can be used
|
|
from anywhere in the web, including in sections or paragraphs earlier than
|
|
the ones in which they are defined. (The tangler automatically arranges code
|
|
as necessary to make this work.)
|
|
</p>
|
|
|
|
<p class="commentary">A symbol defined with <span class="extract"><span class="extract-syntax">@default</span></span> has the given value only if some other use
|
|
of <span class="extract"><span class="extract-syntax">@d</span></span> or <span class="extract"><span class="extract-syntax">@e</span></span> in the web has not already defined it. For example, if the
|
|
web contains:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@default</span><span class="plain-syntax"> MAX_HEADROOM 100</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@d</span><span class="plain-syntax"> MAX_HEADROOM 99</span>
|
|
</pre>
|
|
<p class="commentary">or
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@d</span><span class="plain-syntax"> MAX_HEADROOM 99</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@default</span><span class="plain-syntax"> MAX_HEADROOM 100</span>
|
|
</pre>
|
|
<p class="commentary">then the value is 99, but if only
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@default</span><span class="plain-syntax"> MAX_HEADROOM 100</span>
|
|
</pre>
|
|
<p class="commentary">then the value is 100.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>§4. </b>Finally, a paragraph can contain code. This is introduced with an equals
|
|
sign: in some sense, the value of the paragraph is the code it contains.
|
|
In many paragraphs, as in the example above, the divider is just
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> =</span>
|
|
</pre>
|
|
<p class="commentary">and this means that the rest of the paragraph is part of the program.
|
|
Ordinarily, this must appear in column 1, but a special abbreviation is
|
|
allowed for paragraphs with no comment and no definitions:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@ =</span>
|
|
</pre>
|
|
<p class="commentary">This is exactly equivalent to:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@</span>
|
|
|
|
<span class="plain-syntax"> =</span>
|
|
</pre>
|
|
<p class="commentary">We can tell the tangler to place the code early in the tangled program,
|
|
rather than at its natural place in the sequence, by annotating
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (early code)</span>
|
|
</pre>
|
|
<p class="commentary">instead of just <span class="extract"><span class="extract-syntax">=</span></span>. (This is occasionally useful where, for example, it's
|
|
necessary to create global variables which will be referred to in other
|
|
sections of code.) The more extreme <span class="extract"><span class="extract-syntax">= (very early code)</span></span> can be used in C
|
|
for complicated header file inclusions, but should be kept to an absolute
|
|
minimum, if only for clarity.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>§5. </b>One last feature, but it's the most important. Some code extracts are
|
|
given names, in angle brackets. If so, then the paragraph is the definition
|
|
of that extract. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@<Dramatic finale@> =</span>
|
|
<span class="plain-syntax"> printf("I'm ruined! Ruined, I say!\n");</span>
|
|
<span class="plain-syntax"> exit(1);</span>
|
|
</pre>
|
|
<p class="commentary">Notice that the equals sign is still there: it's just that the chunk of code
|
|
is given a name, written inside <span class="extract"><span class="extract-syntax">@<</span></span> and <span class="extract"><span class="extract-syntax">@></span></span> "brackets". (This notation
|
|
goes all the way back to Knuth's original WEB.)
|
|
</p>
|
|
|
|
<p class="commentary">What does the tangler do with this? It doesn't place the code as the next
|
|
item in the program. Instead, it expands any mention of <span class="extract"><span class="extract-syntax">@<Dramatic finale@></span></span>
|
|
elsewhere in the section with this block of code. It can be expanded as
|
|
many times as necessary, but only within the same section. Another section
|
|
would be quite free to define its own <span class="extract"><span class="extract-syntax">@<Dramatic finale@></span></span>, but it would
|
|
not be able to see this one.
|
|
</p>
|
|
|
|
<p class="commentary">Why is this important? One of the points of literate programming is to
|
|
subdivide the program on conceptual lines, even within single functions.
|
|
For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@<Perform the sieve@> =</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@<Start with all numbers from 2 upwards in the sieve@></span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> for (int n=2; n*n <= RANGE; n++)</span>
|
|
<span class="plain-syntax"> if (still_in_sieve[n])</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@<Shake out multiples of n@></span><span class="plain-syntax">;</span>
|
|
<span class="plain-syntax"> sieve_performed = TRUE;</span>
|
|
</pre>
|
|
<p class="commentary">This is easier to understand than writing the function all in one go, and
|
|
more practicable than breaking it up into smaller functions.
|
|
</p>
|
|
|
|
<p class="commentary">Named paragraphs behave, in some ways, like macro definitions, and those
|
|
have a bad name nowadays - probably fairly. But Inweb makes them much
|
|
safer to use than traditional macros, because it tangles them into code
|
|
blocks, not just into runs of statements. A variable defined inside a
|
|
named paragraph has, as its scope, just that paragraph. And this:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> if (still_in_sieve[n])</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@<Shake out multiples of n@></span><span class="plain-syntax">;</span>
|
|
</pre>
|
|
<p class="commentary">works safely because <span class="extract"><span class="extract-syntax">@<Shake out multiples of n@></span></span> is, thanks to being a
|
|
code block, semantically a single statement.
|
|
</p>
|
|
|
|
<p class="commentary">Finally, note that if there are no commentary or definitions attached to
|
|
the paragraph then it's not necessary to type the initial <span class="extract"><span class="extract-syntax">@</span></span>. That is,
|
|
this:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@</span>
|
|
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@<Prepare to exit@> =</span>
|
|
</pre>
|
|
<p class="commentary">...is not necessary, and it's sufficient to type just:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@<Prepare to exit@> =</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>§6. Conditional compilation. </b>In some languages, especially C, it's very hard to write a program which will
|
|
run on multiple operating systems without some use of conditional compilation:
|
|
that is, putting some code or definitions inside <span class="extract"><span class="extract-syntax">#ifdef</span></span> clauses or the like.
|
|
</p>
|
|
|
|
<p class="commentary">Inweb can't alter this sad fact of life, but it can make the process tidier.
|
|
If a paragraph has the tag <span class="extract"><span class="extract-syntax">^"ifdef-SYMBOL"</span></span>, then any material in it will
|
|
be tangled in such a way that it takes effect only if <span class="extract"><span class="extract-syntax">SYMBOL</span></span> is defined.
|
|
For example, in a C-language web with the paragraph:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@h</span><span class="plain-syntax"> Windows stuff. ^"ifdef-PLATFORM_WINDOWS"</span>
|
|
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@d</span><span class="plain-syntax"> THREADS_AVAILABLE 12</span>
|
|
<span class="plain-syntax"> =</span>
|
|
<span class="plain-syntax"> void start_threads(int n) {</span>
|
|
<span class="plain-syntax"> ...</span>
|
|
<span class="plain-syntax"> }</span>
|
|
</pre>
|
|
<p class="commentary">...the definition of <span class="extract"><span class="extract-syntax">THREADS_AVAILABLE</span></span> and the function <span class="extract"><span class="extract-syntax">start_threads</span></span>
|
|
would be made only inside a <span class="extract"><span class="extract-syntax">#ifdef PLATFORM_WINDOWS</span></span> clause; the same would
|
|
happen for any typedefs or <span class="extract"><span class="extract-syntax">#include</span></span>s made.
|
|
</p>
|
|
|
|
<p class="commentary">Similarly, tagging a paragraph <span class="extract"><span class="extract-syntax">^"ifndef-SYMBOL"</span></span> causes it to have effect
|
|
only if <span class="extract"><span class="extract-syntax">SYMBOL</span></span> is undefined. A paragraph can have any number of such
|
|
conditions applied to it, and if so then all of the conditions must be met.
|
|
</p>
|
|
|
|
<p class="commentary">Note that since tags can be applied to entire sections of a web, at the
|
|
Contents listing, it's straightforward to give, say, two versions of a
|
|
section file, one with effect on MacOS, one with effect on Windows.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>§7. Commentary. </b>The comment part of a paragraph is ignored by the tangler, and appears only
|
|
in weaves. For the most part, the text is simply copied over verbatim: but
|
|
Inweb quietly tries to improve the appearance of what it copies, and a
|
|
few special notations are allowed, to help with this.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>§8. </b>A doubled hyphen becomes an em-rule; double-quotation marks automatically
|
|
smarten (in TeX format, at least).
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>§9. </b>Lines beginning with what look like bracketed list numbers or letters are
|
|
set as such, running on into little indented paragraphs. Thus
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> (a) Intellectual property has the shelf life of a banana. (Bill Gates)</span>
|
|
<span class="plain-syntax"> (b) He is the very pineapple of politeness! (Richard Brinsley Sheridan)</span>
|
|
<span class="plain-syntax"> (c) Harvard takes perfectly good plums as students, and turns them into</span>
|
|
<span class="plain-syntax"> prunes. (Frank Lloyd Wright)</span>
|
|
</pre>
|
|
<p class="commentary">will be typeset thus:
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) Intellectual property has the shelf life of a banana. (Bill Gates)
|
|
</li><li>(b) He is the very pineapple of politeness! (Richard Brinsley Sheridan)
|
|
</li><li>(c) Harvard takes perfectly good plums as students, and turns them into
|
|
prunes. (Frank Lloyd Wright)
|
|
</li></ul>
|
|
<p class="commentary">A line which begins <span class="extract"><span class="extract-syntax">(...)</span></span> will be treated as a continuation of indented
|
|
matter (following on from some break-off such as a source quotation).
|
|
A line which begins <span class="extract"><span class="extract-syntax">(-X)</span></span> will be treated as if it were <span class="extract"><span class="extract-syntax">(X)</span></span>, but
|
|
indented one tab stop further in, like so:
|
|
</p>
|
|
|
|
<ul class="items"><li>(c) Harvard blah, blah, blah. (Frank Lloyd Wright)
|
|
<ul class="items"><li>(d) Pick a song and sing a yellow nectarine. (Scott Weiland)
|
|
</li></ul>
|
|
</li></ul>
|
|
<p class="commentary">Finally, bracketed asterisks are considered to be bullets. Thus:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> (*) Do I dare to eat a peach? (T. S. Eliot)</span>
|
|
<span class="plain-syntax"> (*) You sit on the veranda drinking tea and your ducklings swim on the pond,</span>
|
|
<span class="plain-syntax"> and everything smells good... and there are gooseberries. (Anton Chekhov)</span>
|
|
</pre>
|
|
<p class="commentary">becomes:
|
|
</p>
|
|
|
|
<ul class="items"><li>● Do I dare to eat a peach? (T. S. Eliot)
|
|
</li><li>● You sit on the veranda drinking tea and your ducklings swim on the pond,
|
|
and everything smells good... and there are gooseberries. (Anton Chekhov)
|
|
</li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>§10. </b>Text placed between vertical strokes will be set in a fixed-space, code
|
|
style font, <span class="extract"><span class="extract-syntax">thus</span></span>. This paragraph appears in the web you are reading thus:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@</span><span class="plain-syntax"> Text placed between vertical strokes will be set in a fixed-space, code</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">style font, |thus|. This paragraph appears in the web you are reading thus</span><span class="plain-syntax">:</span>
|
|
</pre>
|
|
<p class="commentary">This notation may be inconvenient if you need the vertical stroke character
|
|
for something else, especially as the notation is used both in code comments
|
|
and in paragraph commentary. But both notations can be configured in the
|
|
Contents page of a web, thus:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="element-syntax">Code In Code Comments Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> Off</span>
|
|
<span class="element-syntax">Code In Commentary Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> %%</span>
|
|
</pre>
|
|
<p class="commentary">This example would turn off the feature in code comments, but allow it in
|
|
paragraph commentary; we would then need to write...
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">@</span><span class="plain-syntax"> Text placed between vertical strokes will be set in a fixed-space, code</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">style font, %%thus%%. This paragraph appears in the web you are reading thus</span><span class="plain-syntax">:</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>§11. </b>A line written thus:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> >> The monkey carries the blue scarf.</span>
|
|
</pre>
|
|
<p class="commentary">is typeset as an extract of text thus:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>The monkey carries the blue scarf.</p>
|
|
</blockquote>
|
|
|
|
<p class="commentary">(This is a feature used for Inform 7 "code" samples, those being essentially
|
|
natural language text.)
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>§12. Code samples and other extraneous matter. </b>When is code not code? When it's an extract of text being displayed for
|
|
documentation reasons, is the answer. We can include this like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (text)</span>
|
|
<span class="plain-syntax"> Here is my sample bit of text.</span>
|
|
<span class="plain-syntax"> = (undisplayed text)</span>
|
|
</pre>
|
|
<p class="commentary">This is assumed to be plain text, and is syntax-coloured (or rather, not)
|
|
as such, but otherwise it's woven as code. Using the word <span class="extract"><span class="extract-syntax">undisplayed</span></span>
|
|
before <span class="extract"><span class="extract-syntax">text</span></span> tells Inweb to do so less showily, on HTML weaves:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (undisplayed text)</span>
|
|
</pre>
|
|
<p class="commentary">Sometimes, though, we do want syntax colouring. If in fact it is a
|
|
hypothetical piece of code from the program — for example, a demonstration of
|
|
an API, but for reading and not to be compiled — we can instead write:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (text as code)</span>
|
|
</pre>
|
|
<p class="commentary">and the text will then be treated visually exactly as the surrounding
|
|
program is. If, on the other hand, it's a sample piece of code from a
|
|
different language altogether, we can specify which:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (text as ACME)</span>
|
|
</pre>
|
|
<p class="commentary">This will then be syntax-coloured following the rules for ACME (or any
|
|
other language supported by Inweb).
|
|
</p>
|
|
|
|
<p class="commentary">Note that if your web is written in, for example, C, then these are
|
|
subtly different:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (text as C)</span>
|
|
<span class="plain-syntax"> = (text as code)</span>
|
|
</pre>
|
|
<p class="commentary">The difference is that syntax-colouring in the first case doesn't know
|
|
the names of any surrounding functions or data structures; in the second
|
|
case, it knows the names of all those in your program.
|
|
</p>
|
|
|
|
<p class="commentary">Samples of code are, uniquely, allowed to end mid-way in a paragraph (unlike
|
|
real code): placing a <span class="extract"><span class="extract-syntax">=</span></span> on the left margin allows the commentary to resume.
|
|
For example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (text as ACME)</span>
|
|
<span class="plain-syntax"> BEQ .adjustXRegister</span>
|
|
<span class="plain-syntax"> =</span>
|
|
<span class="plain-syntax"> ...which is essential in order to restore the state of</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>§13. Links. </b>URLs in the web are automatically recognised and a weave to HTML will
|
|
make them into links. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> For further reading, see: https://en.wikipedia.org/wiki/How_to_Avoid_Huge_Ships.</span>
|
|
</pre>
|
|
<p class="commentary">For further reading, see: <a href="https://en.wikipedia.org/wiki/How_to_Avoid_Huge_Ships" class="external">https://en.wikipedia.org/wiki/How_to_Avoid_Huge_Ships</a>.
|
|
</p>
|
|
|
|
<p class="commentary">Note that URLs are considered to continue to the next white space, except
|
|
that any final full stops, question or exclamation marks, commas, brackets,
|
|
semicolons, or colons are disregarded. (This is why the above sentence ended
|
|
with a full stop and yet the full stop wasn't part of the reference URL.)
|
|
</p>
|
|
|
|
<p class="commentary">URLs will also be recognised in any text extract marked as <span class="extract"><span class="extract-syntax">hyperlinked</span></span>.
|
|
For example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Compare: https://en.wikipedia.org/wiki/Crocheting_Adventures_with_Hyperbolic_Planes!</span>
|
|
</pre>
|
|
<p class="commentary">produces:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Compare: </span><a href="https://en.wikipedia.org/wiki/Crocheting_Adventures_with_Hyperbolic_Planes!" class="external">https://en.wikipedia.org/wiki/Crocheting_Adventures_with_Hyperbolic_Planes!</a>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>§14. Cross-references. </b>These are like links, but are internal. These are normally written within <span class="extract"><span class="extract-syntax">//</span></span>
|
|
signs and are only available in the commentary of a web. They allow us to
|
|
place cross-references like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> To see how cross-references are implemented, see //Format Methods//,</span>
|
|
<span class="plain-syntax"> or more generally the whole of //Chapter 5//; to decipher the text,</span>
|
|
<span class="plain-syntax"> Inweb uses code from //foundation// at //foundation: Web Modules//.</span>
|
|
</pre>
|
|
<p class="commentary">To see how cross-references are implemented, see <a href="5-fm.html" class="internal">Format Methods</a>,
|
|
or more generally the whole of <a href="5-wt.html" class="internal">Chapter 5: Formats</a>; to decipher the text,
|
|
Inweb uses code from <a href="../foundation-module/index.html" class="internal">foundation</a> at <a href="../foundation-module/8-wm.html" class="internal">Web Modules (in foundation)</a>.
|
|
</p>
|
|
|
|
<p class="commentary">What happened in that last sentence is that Inweb noticed the following:
|
|
</p>
|
|
|
|
<ul class="items"><li>(a) "Format Methods" is the name of a section of code in the Inweb web;
|
|
</li><li>(b) The web also has a "Chapter 5";
|
|
</li><li>(c) It uses a module called "foundation";
|
|
</li><li>(d) And that module has a section called "Web Modules".
|
|
</li></ul>
|
|
<p class="commentary">Inweb then made links accordingly. Chapters, which can be referred to either
|
|
numerically, link to the first section in them; modules likewise. Errors are
|
|
thrown if these references to sections are in any way ambiguous. They are not
|
|
case sensitive.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>§15. </b>Sometimes we want to make a link without literally showing the destination.
|
|
This is simple: for example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> First //the program has to configure itself -> Configuration//, then...</span>
|
|
</pre>
|
|
<p class="commentary">produces: "First <a href="1-cnf.html" class="internal">the program has to configure itself</a>,
|
|
then..."; the text "the program has to configure itself" links to <a href="1-cnf.html" class="internal">Configuration</a>.
|
|
This is especially useful if the destination is given as an explicit URL, which
|
|
is also allowed:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> See //this biographical note -> http://mathshistory.st-andrews.ac.uk/Biographies/Gauss.html//.</span>
|
|
</pre>
|
|
<p class="commentary">See <a href="http://mathshistory.st-andrews.ac.uk/Biographies/Gauss.html" class="external">this biographical note</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>§16. </b>It's also possible to reference function names and type names, provided that
|
|
the language definition supports these (see <a href="M-spl.html" class="internal">Supporting Programming Languages</a>):
|
|
this is certainly the case for C-like languages. For example,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Individual lines of a web are stored in //source_line// structures,</span>
|
|
<span class="plain-syntax"> and mostly created by //Reader::read_file//.</span>
|
|
</pre>
|
|
<p class="commentary">produces: Individual lines of a web are stored in <a href="2-lc.html#SP1" class="internal">source_line</a> structures,
|
|
and mostly created by <a href="2-tr.html#SP6" class="internal">Reader::read_file</a>. And that should link to the
|
|
structure definition and function of these names inside the Inweb program.
|
|
</p>
|
|
|
|
<p class="commentary">Lastly, cross-references can even be made to webs quite separate from the
|
|
current one, but this requires the use of a Colony file.
|
|
See <a href="M-mwiw.html" class="internal">Making Weaves into Websites</a>.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>§17. </b>Cross-references also work inside text extracts marked as <span class="extract"><span class="extract-syntax">hyperlinked</span></span>.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (hyperlinked text)</span>
|
|
<span class="plain-syntax"> See the //Manual// for more on this.</span>
|
|
<span class="plain-syntax"> =</span>
|
|
</pre>
|
|
<p class="commentary">produces:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> See the </span><a href="M-iti.html" class="internal">Manual</a><span class="plain-syntax"> for more on this.</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>§18. </b>Cross-references must begin after white space, or a punctuation mark (other
|
|
than a colon), and must end to be followed by more white space or another
|
|
punctuation mark (this time allowing a colon). In practice, that reduces
|
|
the risk of misunderstanding a <span class="extract"><span class="extract-syntax">//</span></span> occurring in the commentary for some
|
|
other reason. All the same, you might want a different notation, so this
|
|
can be configured in the Contents page of a web, say like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="element-syntax">Cross-References Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> &&&</span>
|
|
</pre>
|
|
<p class="commentary">It's also possible to disable cross-referencing entirely with:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="element-syntax">Cross-References Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> Off</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>§19. Figures. </b>Images to be included in weaves of a web are called "Figures", as they
|
|
would be in a printed book. These images should ideally be in PNG, JPG or PDF
|
|
format and placed in a subdirectory of the web called <span class="extract"><span class="extract-syntax">Figures</span></span>: for instance,
|
|
the weaver would seek <span class="extract"><span class="extract-syntax">Fig_2_3.pdf</span></span> at pathname <span class="extract"><span class="extract-syntax">Figures/Fig_2_3.pdf</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">To embed an image, we write like so:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (figure mars.jpg)</span>
|
|
</pre>
|
|
<p class="commentary">With results like so:
|
|
</p>
|
|
|
|
<p class="center-p"><img src="mars.jpg" alt="mars.jpg"></p>
|
|
|
|
<p class="commentary">Inweb also has some limited ability to control the dimensions of an image:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (figure Whatever.jpg at width 500)</span>
|
|
<span class="plain-syntax"> = (figure Something.jpg at height 2cm)</span>
|
|
</pre>
|
|
<p class="commentary">Dimensions given in cm are scaled at 72 times dimensions given without a
|
|
measurement; in practice, rendering to TeX produces roughly the number of
|
|
centimeters asked for, and rendering to HTML makes the image width or height
|
|
correspond. If you really want to monkey with the aspect ratio,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (figure Whatever.jpg at 20 by 100)</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP20" class="paragraph-anchor"></a><b>§20. Carousels. </b>A carousel is a slide-show of (usually but not always) figures; there's a
|
|
set of slides with captions, only one of which is visible at a time.
|
|
</p>
|
|
|
|
<div class="carousel-container" id="carousel-no-1">
|
|
<div class="carousel-slide fading-slide" style="display: block;">
|
|
<div class="carousel-number">1 / 4</div>
|
|
<div class="carousel-content"><p class="center-p"><img src="rah.jpg" alt="rah.jpg"></p>
|
|
|
|
</div>
|
|
<div class="carousel-caption">Royal Albert Hall, London: King Crimson's 50th Anniversary Concert</div>
|
|
</div>
|
|
<div class="carousel-slide fading-slide" style="display: none;">
|
|
<div class="carousel-number">2 / 4</div>
|
|
<div class="carousel-content"><p class="center-p"><img src="brighton.jpg" alt="brighton.jpg"></p>
|
|
|
|
</div>
|
|
<div class="carousel-caption">Brighton Beach</div>
|
|
</div>
|
|
<div class="carousel-slide fading-slide" style="display: none;">
|
|
<div class="carousel-number">3 / 4</div>
|
|
<div class="carousel-content"><p class="center-p"><img src="pula.jpg" alt="pula.jpg"></p>
|
|
|
|
</div>
|
|
<div class="carousel-caption">Roman Amphitheatre, Pula</div>
|
|
</div>
|
|
<div class="carousel-slide fading-slide" style="display: none;">
|
|
<div class="carousel-number">4 / 4</div>
|
|
<div class="carousel-content"><p class="center-p"><img src="venice.jpg" alt="venice.jpg"></p>
|
|
|
|
</div>
|
|
<div class="carousel-caption">St Mark's Basilica, Venice</div>
|
|
</div>
|
|
<a class="carousel-prev-button" onclick="carouselMoveSlide("carousel-no-1", "carousel-dots-no-1", -1)">❮</a>
|
|
<a class="carousel-next-button" onclick="carouselMoveSlide("carousel-no-1", "carousel-dots-no-1", 1)">❯</a>
|
|
</div>
|
|
<div class="carousel-dots-container" id="carousel-dots-no-1">
|
|
<span class="carousel-dot carousel-dot-active" onclick="carouselSetSlide("carousel-no-1", "carousel-dots-no-1", 0)"></span>
|
|
<span class="carousel-dot" onclick="carouselSetSlide("carousel-no-1", "carousel-dots-no-1", 1)"></span>
|
|
<span class="carousel-dot" onclick="carouselSetSlide("carousel-no-1", "carousel-dots-no-1", 2)"></span>
|
|
<span class="carousel-dot" onclick="carouselSetSlide("carousel-no-1", "carousel-dots-no-1", 3)"></span>
|
|
</div>
|
|
That carousel was produced by:
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (carousel "Royal Albert Hall, London: King Crimson's 50th Anniversary Concert")</span>
|
|
<span class="plain-syntax"> = (figure rah.jpg)</span>
|
|
<span class="plain-syntax"> = (carousel "Brighton Beach")</span>
|
|
<span class="plain-syntax"> = (figure brighton.jpg)</span>
|
|
<span class="plain-syntax"> = (carousel "Roman Amphitheatre, Pula")</span>
|
|
<span class="plain-syntax"> = (figure pula.jpg)</span>
|
|
<span class="plain-syntax"> = (carousel "St Mark's Basilica, Venice")</span>
|
|
<span class="plain-syntax"> = (figure venice.jpg)</span>
|
|
<span class="plain-syntax"> = (carousel end)</span>
|
|
</pre>
|
|
<p class="commentary">That carousel contained only figures, but almost any material can go into the
|
|
slides, paragraph breaks excepted. For example:
|
|
</p>
|
|
|
|
<div class="carousel-container" id="carousel-no-2">
|
|
<div class="carousel-slide fading-slide" style="display: block;">
|
|
<div class="carousel-caption-above">Stage 1 - Raw tree</div>
|
|
<div class="carousel-number-above">1 / 3</div>
|
|
<div class="carousel-content"><pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">ROOT</span><span class="plain-syntax"> ---> </span><span class="function-syntax">DOCUMENT</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="carousel-slide fading-slide" style="display: none;">
|
|
<div class="carousel-caption-above">Stage 2 - Developed tree</div>
|
|
<div class="carousel-number-above">2 / 3</div>
|
|
<div class="carousel-content"><pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">ROOT</span><span class="plain-syntax"> ---> </span><span class="function-syntax">DOCUMENT</span>
|
|
<span class="plain-syntax"> |</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">NODE</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax"> --- </span><span class="function-syntax">NODE</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> --- </span><span class="function-syntax">NODE</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> --- ...</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<div class="carousel-slide fading-slide" style="display: none;">
|
|
<div class="carousel-caption-above">Stage 3 - Completed tree</div>
|
|
<div class="carousel-number-above">3 / 3</div>
|
|
<div class="carousel-content"><pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="function-syntax">ROOT</span><span class="plain-syntax"> ---> </span><span class="function-syntax">DOCUMENT</span>
|
|
<span class="plain-syntax"> |</span>
|
|
<span class="plain-syntax"> </span><span class="function-syntax">NODE</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax"> --- </span><span class="function-syntax">NODE</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> --- </span><span class="function-syntax">NODE</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> --- ...</span>
|
|
<span class="plain-syntax"> | | |</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">text</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax"> </span><span class="element-syntax">text</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> </span><span class="element-syntax">text</span><span class="plain-syntax"> </span><span class="constant-syntax">3</span><span class="plain-syntax"> ...</span>
|
|
</pre>
|
|
</div>
|
|
</div>
|
|
<a class="carousel-prev-button" onclick="carouselMoveSlide("carousel-no-2", "carousel-dots-no-2", -1)">❮</a>
|
|
<a class="carousel-next-button" onclick="carouselMoveSlide("carousel-no-2", "carousel-dots-no-2", 1)">❯</a>
|
|
</div>
|
|
<div class="carousel-dots-container" id="carousel-dots-no-2">
|
|
<span class="carousel-dot carousel-dot-active" onclick="carouselSetSlide("carousel-no-2", "carousel-dots-no-2", 0)"></span>
|
|
<span class="carousel-dot" onclick="carouselSetSlide("carousel-no-2", "carousel-dots-no-2", 1)"></span>
|
|
<span class="carousel-dot" onclick="carouselSetSlide("carousel-no-2", "carousel-dots-no-2", 2)"></span>
|
|
</div>
|
|
This carousel has differently placed captions, too: that's because the
|
|
slide lines were typed as:
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (carousel "Stage 2 - Developed tree" above)</span>
|
|
</pre>
|
|
<p class="commentary">and the like. By default, a caption overlaps slightly with the content; but
|
|
it can also be <span class="extract"><span class="extract-syntax">above</span></span> or <span class="extract"><span class="extract-syntax">below</span></span>. A slide can also have no caption at all:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (carousel)</span>
|
|
<span class="plain-syntax"> = (figure anonymous.jpg)</span>
|
|
<span class="plain-syntax"> = (carousel)</span>
|
|
<span class="plain-syntax"> = (figure furtive.jpg)</span>
|
|
<span class="plain-syntax"> = (carousel end)</span>
|
|
</pre>
|
|
<p class="commentary firstcommentary"><a id="SP21" class="paragraph-anchor"></a><b>§21. Video and audio. </b>To include audio samples, place them as MP3 files in the subdirectory <span class="extract"><span class="extract-syntax">Audio</span></span>
|
|
of the web. For example, in the present web,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (audio SP014.mp3)</span>
|
|
</pre>
|
|
<p class="commentary">produces Space Patrol episode 14, from 1953: "Brain Bank And Space Binoculars" —
|
|
</p>
|
|
|
|
<p class="center-p"><audio controls>
|
|
<source src="SP014.mp3" type="audio/mpeg">
|
|
Your browser does not support the audio element.
|
|
</audio>
|
|
</p>
|
|
|
|
<p class="commentary">Similarly,
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (video DW014.mp4)</span>
|
|
</pre>
|
|
<p class="commentary">produces Doctor Who episode 14, from 1963: "The Roof of the World". Still, video
|
|
takes up space, so for economy's sake a demonstration is omitted from this manual.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP22" class="paragraph-anchor"></a><b>§22. Embedded video and audio. </b>One way to get around such space limitations is to embed players for video or
|
|
audio hosted on some external service. For example:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (embedded YouTube video GR3aImy7dWw)</span>
|
|
</pre>
|
|
<p class="commentary">With results like so:
|
|
</p>
|
|
|
|
<p class="center-p"><iframe width="720" height="405" src="https://www.youtube.com/embed/GR3aImy7dWw" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
|
|
|
</p>
|
|
|
|
<p class="commentary">The YouTube ID number <span class="extract"><span class="extract-syntax">GR3aImy7dWw</span></span> can be read from its Share URL, which in
|
|
this case was <span class="extract"><span class="extract-syntax">https://youtu.be/GR3aImy7dWw</span></span>.
|
|
</p>
|
|
|
|
<p class="commentary">Similarly for Vimeo:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (embedded Vimeo video 204519)</span>
|
|
</pre>
|
|
<p class="commentary">With results like so:
|
|
</p>
|
|
|
|
<p class="center-p"><iframe src="https://player.vimeo.com/video/204519" width="720" height="405" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
|
|
|
|
</p>
|
|
|
|
<p class="commentary">For audio, you may like to try SoundCloud:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (embedded SoundCloud audio 42803139)</span>
|
|
</pre>
|
|
<p class="commentary">With results like so:
|
|
</p>
|
|
|
|
<p class="center-p"><iframe width="100%" height="405" scrolling="no" frameborder="no" allow="autoplay" src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/42803139&color=%23ff5500&auto_play=false&hide_related=false&show_comments=true&show_user=true&show_reposts=false&show_teaser=true&visual=true"></iframe>
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP23" class="paragraph-anchor"></a><b>§23. </b>Adding width and height is straightforward; by default the dimensions are
|
|
720 by 405.
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (embedded Vimeo video 204519 at 400 by 300)</span>
|
|
<span class="plain-syntax"> = (embedded SoundCloud audio 42803139 at height 200)</span>
|
|
</pre>
|
|
<p class="commentary">The latter sets just the height (of the displayed waveform, that is —
|
|
arguably music has width and not height, but SoundCloud thinks otherwise).
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP24" class="paragraph-anchor"></a><b>§24. Downloads. </b>Occasional small downloads may be useful as a way to present examples to
|
|
try with a program being documented. These are very simple:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> = (download alice.crt "certificate file")</span>
|
|
</pre>
|
|
<p class="commentary">produces:
|
|
</p>
|
|
|
|
<div class="download-container">
|
|
<p>
|
|
<a href="alice.crt" download>
|
|
<button class="download-button">
|
|
<img src="../docs-assets/download.png" alt="download icon" height=16 width=16>
|
|
Download <b>alice.crt</b> (certificate file, 7.2kB)
|
|
</button>
|
|
</a>
|
|
</p>
|
|
</div>
|
|
|
|
|
|
<p class="commentary">The file to download, in this case <span class="extract"><span class="extract-syntax">alice.crt</span></span>, must be placed in a <span class="extract"><span class="extract-syntax">Downloads</span></span>
|
|
subdirectory of the web. The explanatory text — usually just an indication
|
|
of what sort of file this is — is optional.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP25" class="paragraph-anchor"></a><b>§25. Mathematics notation. </b>Literate programming is a good technique to justify code which hangs on
|
|
unobvious pieces of mathematics or computer science, and which must therefore
|
|
be explained carefully. Formulae or equations are a real convenience for that.
|
|
</p>
|
|
|
|
<p class="commentary">For example, it's known that the average running time of Euclid's GCD
|
|
algorithm on \(a\) and numbers coprime to \(a\) is:
|
|
$$ \tau (a)={\frac {12}{\pi ^{2}}}\ln 2\ln a+C+O(a^{-1/6-\varepsilon }) $$
|
|
where \(C\) is Porter's constant,
|
|
$$ C=-{\frac {1}{2}}+{\frac {6\ln 2}{\pi ^{2}}}\left(4\gamma - {\frac {24}{\pi ^{2}}}\zeta'(2)+3\ln 2-2\right)\approx 1.467 $$
|
|
which involves evaluating Euler's constant \(\gamma\) and the first derivative
|
|
of the Riemann zeta function \(\zeta'(z)\) at \(z=2\).
|
|
</p>
|
|
|
|
<p class="commentary">That passage was achieved by typing this as the Inweb source:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> For example, it's known that the average running time of Euclid's GCD</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">algorithm on $a$ and numbers coprime to $a$ is</span><span class="plain-syntax">:</span>
|
|
<span class="plain-syntax"> $$ \tau (a)={\frac {12}{\pi ^{2}}}\ln 2\ln a+C+O(a^{-1/6-\varepsilon }) $$</span>
|
|
<span class="plain-syntax"> where $C$ is Porter's constant,</span>
|
|
<span class="plain-syntax"> $$ C=-{\frac {1}{2}}+{\frac {6\ln 2}{\pi ^{2}}} \left(4\gamma - {\frac {24}{\pi^{2}}}\zeta'(2)+3\ln 2-2\right)\approx 1.467 $$</span>
|
|
<span class="plain-syntax"> which involves evaluating Euler's constant $\gamma$ and the first derivative</span>
|
|
<span class="plain-syntax"> of the Riemann zeta function $\zeta'(z)$ at $z=2$.</span>
|
|
</pre>
|
|
<p class="commentary">Mathematical formulae is typed in TeX notation between dollar signs,
|
|
as usual for TeX formulae. If those notations are inconvenient, they can be
|
|
changed. The defaults are:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="element-syntax">TeX Mathematics Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> $</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">TeX Mathematics Displayed Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> $$</span>
|
|
</pre>
|
|
<p class="commentary">Changing these to <span class="extract"><span class="extract-syntax">None</span></span> causes Inweb to disregard mathematics entirely, and
|
|
treat it as any other text would be treated.
|
|
</p>
|
|
|
|
<p class="commentary firstcommentary"><a id="SP26" class="paragraph-anchor"></a><b>§26. Footnotes. </b>Not everyone likes footnotes,<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup> but sometimes they're a tidy way to make
|
|
references.<sup id="fnref:2"><a href="#fn:2" rel="footnote">2</a></sup>
|
|
</p>
|
|
|
|
<ul class="footnotetexts"><li class="footnote" id="fn:1"><p class="inwebfootnote"><sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup> But see Anthony Grafton, "The Footnote: A Curious History" (Harvard
|
|
University Press, 1999).
|
|
<a href="#fnref:1" title="return to text"> ↩</a></p></li><li class="footnote" id="fn:2"><p class="inwebfootnote"><sup id="fnref:2"><a href="#fn:2" rel="footnote">2</a></sup> For example, to cite Donald Knuth, "Evaluation of Porter's constant",
|
|
Computers & Mathematics with Applications, 2, 137-39 (1976).
|
|
<a href="#fnref:2" title="return to text"> ↩</a></p></li></ul>
|
|
<p class="commentary firstcommentary"><a id="SP27" class="paragraph-anchor"></a><b>§27. </b>The content of that sentence was typed as follows:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> Not everyone likes footnotes,[1] but sometimes they're a tidy way to make</span>
|
|
<span class="plain-syntax"> references.[2]</span>
|
|
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">[1]</span><span class="plain-syntax"> But see Anthony Grafton, "The Footnote: A Curious History" (Harvard</span>
|
|
<span class="plain-syntax"> University Press, 1999).</span>
|
|
<span class="plain-syntax"> </span><span class="identifier-syntax">[2]</span><span class="plain-syntax"> For example, to cite Donald Knuth, "Evaluation of Porter's constant",</span>
|
|
<span class="plain-syntax"> Computers & Mathematics with Applications, 2, 137-39 (1976).</span>
|
|
</pre>
|
|
<p class="commentary">Note that footnotes should be numbered upwards from 1 in each individual
|
|
paragraph; Inweb automatically renumbers them for each woven section, but
|
|
we don't have to worry about that when typing.
|
|
</p>
|
|
|
|
<p class="commentary">If you're reading this as a web page (with Javascript on), then you should
|
|
have seen clickable footnote blobs, which reveal the text. If Javascript is
|
|
off, there's a more conventionally textual presentation.
|
|
</p>
|
|
|
|
<p class="commentary">Once again, notation may be an issue, and so it's controllable. By default,
|
|
we have:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="element-syntax">Footnote Begins Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> [</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">Footnote Ends Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> ]</span>
|
|
</pre>
|
|
<p class="commentary">but if you need squares for something else in your commentary, then perhaps:
|
|
</p>
|
|
|
|
<pre class="displayed-code all-displayed-code code-font">
|
|
<span class="plain-syntax"> </span><span class="element-syntax">Footnote Begins Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> [fn</span>
|
|
<span class="plain-syntax"> </span><span class="element-syntax">Footnote Ends Notation</span><span class="plain-syntax">:</span><span class="string-syntax"> ]</span>
|
|
</pre>
|
|
<p class="commentary">would be sensible. The "cue" between these notations is required to be a
|
|
string of digits; each must occur just once in its section; and each must
|
|
have a text and a cue which match up correctly.
|
|
</p>
|
|
|
|
<nav role="progress"><div class="progresscontainer">
|
|
<ul class="progressbar"><li class="progressprev"><a href="M-wtaw.html">❮</a></li><li class="progresscurrentchapter">M</li><li class="progresssection"><a href="M-iti.html">iti</a></li><li class="progresssection"><a href="M-wtaw.html">wtaw</a></li><li class="progresscurrent">htwaw</li><li class="progresssection"><a href="M-mwiw.html">mwiw</a></li><li class="progresssection"><a href="M-awwp.html">awwp</a></li><li class="progresssection"><a href="M-spl.html">spl</a></li><li class="progresssection"><a href="M-tid.html">tid</a></li><li class="progresssection"><a href="M-rc.html">rc</a></li><li class="progresschapter"><a href="P-htpw.html">P</a></li><li class="progresschapter"><a href="1-bsc.html">1</a></li><li class="progresschapter"><a href="2-tr.html">2</a></li><li class="progresschapter"><a href="3-ta.html">3</a></li><li class="progresschapter"><a href="4-pl.html">4</a></li><li class="progresschapter"><a href="5-wt.html">5</a></li><li class="progresschapter"><a href="6-mkf.html">6</a></li><li class="progressnext"><a href="M-mwiw.html">❯</a></li></ul></div>
|
|
</nav><!--End of weave-->
|
|
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|