615 lines
24 KiB
HTML
615 lines
24 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<head>
|
|
<title>M/wtaw</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="../webs.html">Sources</a></h1>
|
|
<ul>
|
|
<li><a href="../inweb/index.html">inweb</a></li>
|
|
</ul>
|
|
<h2>Foundation</h2>
|
|
<ul>
|
|
<li><a href="../foundation-module/index.html">foundation-module</a></li>
|
|
<li><a href="../foundation-test/index.html">foundation-test</a></li>
|
|
</ul>
|
|
|
|
|
|
</nav>
|
|
<main role="main">
|
|
|
|
<!--Weave of 'M/htwaw' generated by 7-->
|
|
<ul class="crumbs"><li><a href="../webs.html">Source</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><p class="purpose">How to mark up code for literate programming.</p>
|
|
|
|
<ul class="toc"><li><a href="#SP1">§1. The title of a section</a></li><li><a href="#SP2">§2. Paragraphing</a></li><li><a href="#SP6">§6. Conditional compilation</a></li><li><a href="#SP7">§7. Commentary</a></li></ul><hr class="tocbar">
|
|
|
|
<p class="inwebparagraph"><a id="SP1"></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 <code class="display"><span class="extract">@</span></code> character.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The first line should be the title of the section, followed by a full stop.
|
|
For example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">The Sieve of Eratosthenes.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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="inwebparagraph">Optionally, a section heading can also specify its own range abbreviation,
|
|
which must be given in round brackets and followed by a colon:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">(S/sieve): The Sieve of Eratosthenes.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">If this is not done (and usually it is not), Inweb will construct a range
|
|
abbreviation itself: in this case, it comes up with <code class="display"><span class="extract">S/tsoe</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">A fairly fast way to determine if small numbers are prime, given storage.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP2"></a><b>§2. Paragraphing. </b>A standard paragraph is introduced with an <code class="display"><span class="extract">@</span></code> command, which must place
|
|
that magic character in the first column of the line:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@ This is some comment at the start of a new paragraph, which...</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">A fancier paragraph with a subheading attached is introduced using the
|
|
<code class="display"><span class="extract">@h</span></code> or <code class="display"><span class="extract">@heading</span></code> 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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@heading Reflections on the method.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@h Primality.</span>
|
|
<span class="plain">We provide this as a function which determines whether a number</span>
|
|
<span class="plain">is prime:</span>
|
|
|
|
<span class="plain">@d TRUE 1</span>
|
|
<span class="plain">@d FALSE 0</span>
|
|
|
|
<span class="plain">=</span>
|
|
<span class="plain">int isprime(int n) {</span>
|
|
<span class="plain"> if (n <= 1) return FALSE;</span>
|
|
<span class="plain"> for (int m = 2; m*m <= n; m++)</span>
|
|
<span class="plain"> if (n % m == 0)</span>
|
|
<span class="plain"> return FALSE;</span>
|
|
<span class="plain"> return TRUE;</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP3"></a><b>§3. </b>Definitions are made using one of three commands: <code class="display"><span class="extract">@d</span></code> or <code class="display"><span class="extract">@define</span></code>; or
|
|
<code class="display"><span class="extract">@e</span></code> or <code class="display"><span class="extract">@enum</span></code>; or <code class="display"><span class="extract">@default</span></code>, 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 <code class="display"><span class="extract">#define</span></code> directive in C. <code class="display"><span class="extract">@define</span></code> is the simpler form.
|
|
For example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@define ENIGMATIC_NUMBER 90125</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">sets <code class="display"><span class="extract">ENIGMATIC_NUMBER</span></code> to 90125. Unlike in the C preprocessor, multi-line
|
|
definitions are automatically handled, so for example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@ The following macro defines a function:</span>
|
|
<span class="plain">@d EAT_FRUIT(variety)</span>
|
|
<span class="plain"> int consume_by_##variety(variety *frp) {</span>
|
|
<span class="plain"> return frp->eat_by_date;</span>
|
|
<span class="plain"> }</span>
|
|
<span class="plain">=</span>
|
|
<span class="plain">banana my_banana; /* initialised somewhere else, let's suppose */</span>
|
|
<span class="plain">EAT_FRUIT(banana) /* expands with the definition above */</span>
|
|
<span class="plain">void consider_fruit(void) {</span>
|
|
<span class="plain"> printf("The banana has an eat-by date of %d.", consume_by_banana(&my_banana));</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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="inwebparagraph">Enumerations with <code class="display"><span class="extract">@enum</span></code> are a convenience to define enumerated constants.
|
|
For example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@enum JANUARY_MNTH from 0</span>
|
|
<span class="plain">@enum FEBRUARY_MNTH</span>
|
|
<span class="plain">@enum MARCH_MNTH</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">and so on, is equivalent to
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@define JANUARY_MNTH 0</span>
|
|
<span class="plain">@define FEBRUARY_MNTH 1</span>
|
|
<span class="plain">@define MARCH_MNTH 2</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">What happens is that <code class="display"><span class="extract">@enum</span></code> looks at the tail of the name, from the last
|
|
underscore to the end: in this case, <code class="display"><span class="extract">_MNTH</span></code>. The first time an enumerated
|
|
value is asked for with this tail, <code class="display"><span class="extract">from</span></code> is used to specify the lowest
|
|
number to be used - in the above case, months begin counting from 0. With
|
|
each subsequent <code class="display"><span class="extract">_MNTH</span></code> request, <code class="display"><span class="extract">@enum</span></code> allocates the next unused value.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">All symbols defined with <code class="display"><span class="extract">@define</span></code> or <code class="display"><span class="extract">@enum</span></code> 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="inwebparagraph">A symbol defined with <code class="display"><span class="extract">@default</span></code> has the given value only if some other use
|
|
of <code class="display"><span class="extract">@d</span></code> or <code class="display"><span class="extract">@e</span></code> in the web has not already defined it. For example, if the
|
|
web contains:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@default MAX_HEADROOM 100</span>
|
|
<span class="plain">@d MAX_HEADROOM 99</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">or
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@d MAX_HEADROOM 99</span>
|
|
<span class="plain">@default MAX_HEADROOM 100</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">then the value is 99, but if only
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@default MAX_HEADROOM 100</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">then the value is 100.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP4"></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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">=</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@ =</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">This is exactly equivalent to:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@</span>
|
|
|
|
<span class="plain">=</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">= (early code)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">instead of just <code class="display"><span class="extract">=</span></code>. (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 <code class="display"><span class="extract">= (very early code)</span></code> 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="inwebparagraph">We can also tell the tangler to ignore the code completely:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">= (not code)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">That may seem paradoxical: when is code not code? When it's an extract of
|
|
text being displayed for documentation reasons, is the answer. By default,
|
|
this is assumed to be plain text, and is syntax-coloured (or rather, not)
|
|
as such. If in fact it is a sample of code from some language Inweb
|
|
supports, we can instead write, for example:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">= (sample ACME code)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">to say that this is an extract of code in ACME format, and should be
|
|
coloured accordingly. Samples of code are, uniquely, allowed to end
|
|
mid-way in a paragraph (unlike real code): placing a <code class="display"><span class="extract">=</span></code> on the left
|
|
margin allows the commentary to resume. For example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">= (sample ACME code)</span>
|
|
<span class="plain"> BEQ .adjustXRegister</span>
|
|
<span class="plain">=</span>
|
|
<span class="plain">...which is essential in order to restore the state of</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP5"></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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@<Dramatic finale@> =</span>
|
|
<span class="plain"> printf("I'm ruined! Ruined, I say!\n");</span>
|
|
<span class="plain"> exit(1);</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">Notice that the equals sign is still there: it's just that the chunk of code
|
|
is given a name, written inside <code class="display"><span class="extract">@<</span></code> and <code class="display"><span class="extract">@></span></code> "brackets". (This notation
|
|
goes all the way back to Knuth's original WEB.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">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 <code class="display"><span class="extract">@<Dramatic finale@></span></code>
|
|
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 <code class="display"><span class="extract">@<Dramatic finale@></span></code>, but it would
|
|
not be able to see this one.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@<Perform the sieve@> =</span>
|
|
<span class="plain"> @<Start with all numbers from 2 upwards in the sieve@>;</span>
|
|
<span class="plain"> for (int n=2; n*n <= RANGE; n++)</span>
|
|
<span class="plain"> if (still_in_sieve[n])</span>
|
|
<span class="plain"> @<Shake out multiples of n@>;</span>
|
|
<span class="plain"> sieve_performed = TRUE;</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">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="inwebparagraph">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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain"> if (still_in_sieve[n])</span>
|
|
<span class="plain"> @<Shake out multiples of n@>;</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">works safely because <code class="display"><span class="extract">@<Shake out multiples of n@></span></code> is, thanks to being a
|
|
code block, semantically a single statement.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Finally, note that if there are no commentary or definitions attached to
|
|
the paragraph then it's not necessary to type the initial <code class="display"><span class="extract">@</span></code>. That is,
|
|
this:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@</span>
|
|
|
|
<span class="plain">@<Prepare to exit@> =</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">...is not necessary, and it's sufficient to type just:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@<Prepare to exit@> =</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP6"></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 <code class="display"><span class="extract">#ifdef</span></code> clauses or the like.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Inweb can't alter this sad fact of life, but it can make the process tidier.
|
|
If a paragraph has the tag <code class="display"><span class="extract">^"ifdef-SYMBOL"</span></code>, then any material in it will
|
|
be tangled in such a way that it takes effect only if <code class="display"><span class="extract">SYMBOL</span></code> is defined.
|
|
For example, in a C-language web with the paragraph:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">@h Windows stuff. ^"ifdef-PLATFORM_WINDOWS"</span>
|
|
|
|
<span class="plain">@d THREADS_AVAILABLE 12</span>
|
|
<span class="plain">=</span>
|
|
<span class="plain">void start_threads(int n) {</span>
|
|
<span class="plain"> ...</span>
|
|
<span class="plain">}</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">...the definition of <code class="display"><span class="extract">THREADS_AVAILABLE</span></code> and the function <code class="display"><span class="extract">start_threads</span></code>
|
|
would be made only inside a <code class="display"><span class="extract">#ifdef PLATFORM_WINDOWS</span></code> clause; the same would
|
|
happen for any typedefs or <code class="display"><span class="extract">#include</span></code>s made.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">Similarly, tagging a paragraph <code class="display"><span class="extract">^"ifndef-SYMBOL"</span></code> causes it to have effect
|
|
only if <code class="display"><span class="extract">SYMBOL</span></code> 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="inwebparagraph">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="inwebparagraph"><a id="SP7"></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="inwebparagraph"><a id="SP8"></a><b>§8. </b>A doubled hyphen becomes an em-rule; double-quotation marks automatically
|
|
smarten (in TeX format, at least).
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP9"></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>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">(a) Intellectual property has the shelf life of a banana. (Bill Gates)</span>
|
|
<span class="plain">(b) He is the very pineapple of politeness! (Richard Brinsley Sheridan)</span>
|
|
<span class="plain">(c) Harvard takes perfectly good plums as students, and turns them into</span>
|
|
<span class="plain">prunes. (Frank Lloyd Wright)</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">will be typeset thus:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></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="inwebparagraph">A line which begins <code class="display"><span class="extract">(...)</span></code> will be treated as a continuation of indented
|
|
matter (following on from some break-off such as a source quotation).
|
|
A line which begins <code class="display"><span class="extract">(-X)</span></code> will be treated as if it were <code class="display"><span class="extract">(X)</span></code>, but
|
|
indented one tab stop further in, like so:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></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="inwebparagraph"><a id="SP10"></a><b>§10. </b>Text placed between vertical strokes will be set in a fixed-space, code
|
|
style font, <code class="display"><span class="extract">thus</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph">If a series of lines is indented with tab characters and consists entirely
|
|
of courier-type code extracts, it will be set as a running-on series of
|
|
code lines.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP11"></a><b>§11. </b>A line written thus:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">>> The monkey carries the blue scarf.</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">is typeset as an extract of text thus:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<p>The monkey carries the blue scarf.</p>
|
|
|
|
</blockquote>
|
|
|
|
<p class="inwebparagraph">(This is a feature used for Inform 7 "code" samples, those being essentially
|
|
natural language text.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP12"></a><b>§12. </b>Pictures must be in PNG, JPG or PDF format and can be included with lines
|
|
like:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">[[Fig_0_1.pdf]]</span>
|
|
<span class="plain">[[Whatever.jpg width 6cm]]</span>
|
|
<span class="plain">[[Something.pdf height 2cm]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">In the latter examples, we constrain the width or the height of the image
|
|
to be exactly that given: it is scaled accordingly. (They can't both be
|
|
constrained, so you can't change the aspect ratio.)
|
|
</p>
|
|
|
|
<p class="inwebparagraph">The weaver expects that any pictures needed will be stored in a subdirectory of
|
|
the web called <code class="display"><span class="extract">Figures</span></code>: for instance, the weaver would seek <code class="display"><span class="extract">Fig_2_3.pdf</span></code> at
|
|
pathname <code class="display"><span class="extract">Figures/Fig_2_3.pdf</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"><a id="SP13"></a><b>§13. </b>Usually small plain text files can also be incorporated: these are treated
|
|
exactly as Figures, but have the file extension <code class="display"><span class="extract">.txt</span></code>. For example,
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">[[help.txt]]</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph">incorporates a pre-formatted version of the plain text file <code class="display"><span class="extract">Figures/help.txt</span></code>.
|
|
This can be syntax-coloured in any language known to Inweb:
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
|
|
<pre class="display">
|
|
<span class="plain">[[sample.txt]] as C</span>
|
|
</pre>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<p class="inwebparagraph"><a id="SP14"></a><b>§14. </b>Mathematical formulae can be typed in TeX notation between dollar signs,
|
|
as usual for TeX formulae. This can of course only really be rendered if
|
|
the weave is to TeX, but a few very approximate attempts are made by Inweb
|
|
so that the HTML version may also make sense. For example, <code class="display"><span class="extract">$x \leq y$</span></code> would
|
|
be rendered in HTML as <code class="display"><span class="extract">x <= y</span></code>.
|
|
</p>
|
|
|
|
<p class="inwebparagraph"></p>
|
|
|
|
<hr class="tocbar">
|
|
<ul class="toc"><li><a href="M-wtaw.html">Back to 'Webs, Tangling and Weaving'</a></li><li><a href="M-tid.html">Continue with 'The InC Dialect'</a></li></ul><hr class="tocbar">
|
|
<!--End of weave-->
|
|
</main>
|
|
</body>
|
|
</html>
|
|
|