<!--Weave of 'How to Write a Web' generated by Inweb-->
<ulclass="crumbs"><li><ahref="../index.html">Home</a></li><li><ahref="index.html">inweb</a></li><li><ahref="index.html#M">Manual</a></li><li><b>How to Write a Web</b></li></ul><pclass="purpose">How to mark up code for literate programming.</p>
<ulclass="toc"><li><ahref="M-htwaw.html#SP1">§1. The title of a section</a></li><li><ahref="M-htwaw.html#SP2">§2. Paragraphing</a></li><li><ahref="M-htwaw.html#SP6">§6. Conditional compilation</a></li><li><ahref="M-htwaw.html#SP7">§7. Commentary</a></li><li><ahref="M-htwaw.html#SP12">§12. Code samples and other extraneous matter</a></li><li><ahref="M-htwaw.html#SP13">§13. Links</a></li><li><ahref="M-htwaw.html#SP14">§14. Cross-references</a></li><li><ahref="M-htwaw.html#SP18">§18. Figures</a></li><li><ahref="M-htwaw.html#SP19">§19. Embedded video</a></li><li><ahref="M-htwaw.html#SP22">§22. Mathematics notation</a></li><li><ahref="M-htwaw.html#SP23">§23. Footnotes</a></li></ul><hrclass="tocbar">
<pclass="inwebparagraph"><aid="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 <codeclass="display"><spanclass="extract-syntax">@</span></code> character.)
</p>
<pclass="inwebparagraph">The first line should be the title of the section, followed by a full stop.
<spanclass="plain-syntax"> A fairly fast way to determine if small numbers are prime, given storage.</span>
</pre><pclass="inwebparagraph"><aid="SP2"></a><b>§2. Paragraphing. </b>A standard paragraph is introduced with an <codeclass="display"><spanclass="extract-syntax">@</span></code> command, which must place
<spanclass="plain-syntax"></span><spanclass="function-syntax">@</span><spanclass="plain-syntax"> This is some comment at the start of a new paragraph, which...</span>
<pclass="inwebparagraph">A fancier paragraph with a subheading attached is introduced using the
<codeclass="display"><spanclass="extract-syntax">@h</span></code> or <codeclass="display"><spanclass="extract-syntax">@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
<spanclass="plain-syntax"> int isprime(int n) {</span>
<spanclass="plain-syntax"> if (n <= 1) return FALSE;</span>
<spanclass="plain-syntax"> for (int m = 2; m*m <= n; m++)</span>
<spanclass="plain-syntax"> if (n % m == 0)</span>
<spanclass="plain-syntax"> return FALSE;</span>
<spanclass="plain-syntax"> return TRUE;</span>
<spanclass="plain-syntax"> }</span>
</pre><pclass="inwebparagraph"><aid="SP3"></a><b>§3. </b>Definitions are made using one of three commands: <codeclass="display"><spanclass="extract-syntax">@d</span></code> or <codeclass="display"><spanclass="extract-syntax">@define</span></code>; or
<codeclass="display"><spanclass="extract-syntax">@e</span></code> or <codeclass="display"><spanclass="extract-syntax">@enum</span></code>; or <codeclass="display"><spanclass="extract-syntax">@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 <codeclass="display"><spanclass="extract-syntax">#define</span></code> directive in C. <codeclass="display"><spanclass="extract-syntax">@define</span></code> is the simpler form.
<pclass="inwebparagraph">sets <codeclass="display"><spanclass="extract-syntax">ENIGMATIC_NUMBER</span></code> to 90125. Unlike in the C preprocessor, multi-line
definitions are automatically handled, so for example:
<pclass="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>
<pclass="inwebparagraph">Enumerations with <codeclass="display"><spanclass="extract-syntax">@enum</span></code> are a convenience to define enumerated constants.
<pclass="inwebparagraph">What happens is that <codeclass="display"><spanclass="extract-syntax">@enum</span></code> looks at the tail of the name, from the last
underscore to the end: in this case, <codeclass="display"><spanclass="extract-syntax">_MNTH</span></code>. The first time an enumerated
value is asked for with this tail, <codeclass="display"><spanclass="extract-syntax">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 <codeclass="display"><spanclass="extract-syntax">_MNTH</span></code> request, <codeclass="display"><spanclass="extract-syntax">@enum</span></code> allocates the next unused value.
</p>
<pclass="inwebparagraph">All symbols defined with <codeclass="display"><spanclass="extract-syntax">@define</span></code> or <codeclass="display"><spanclass="extract-syntax">@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>
<pclass="inwebparagraph">A symbol defined with <codeclass="display"><spanclass="extract-syntax">@default</span></code> has the given value only if some other use
of <codeclass="display"><spanclass="extract-syntax">@d</span></code> or <codeclass="display"><spanclass="extract-syntax">@e</span></code> in the web has not already defined it. For example, if the
<pclass="inwebparagraph">instead of just <codeclass="display"><spanclass="extract-syntax">=</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 <codeclass="display"><spanclass="extract-syntax">= (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>
<pclass="inwebparagraph"><aid="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
<pclass="inwebparagraph">Notice that the equals sign is still there: it's just that the chunk of code
is given a name, written inside <codeclass="display"><spanclass="extract-syntax">@<</span></code> and <codeclass="display"><spanclass="extract-syntax">@></span></code> "brackets". (This notation
goes all the way back to Knuth's original WEB.)
</p>
<pclass="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 <codeclass="display"><spanclass="extract-syntax">@<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 <codeclass="display"><spanclass="extract-syntax">@<Dramatic finale@></span></code>, but it would
not be able to see this one.
</p>
<pclass="inwebparagraph">Why is this important? One of the points of literate programming is to
subdivide the program on conceptual lines, even within single functions.
<spanclass="plain-syntax"></span><spanclass="function-syntax">@<Perform the sieve@> =</span>
<spanclass="plain-syntax"></span><spanclass="function-syntax">@<Start with all numbers from 2 upwards in the sieve@></span><spanclass="plain-syntax">;</span>
<spanclass="plain-syntax"> for (int n=2; n*n <= RANGE; n++)</span>
<spanclass="plain-syntax"> if (still_in_sieve[n])</span>
<spanclass="plain-syntax"></span><spanclass="function-syntax">@<Shake out multiples of n@></span><spanclass="plain-syntax">;</span>
<pclass="inwebparagraph">works safely because <codeclass="display"><spanclass="extract-syntax">@<Shake out multiples of n@></span></code> is, thanks to being a
code block, semantically a single statement.
</p>
<pclass="inwebparagraph">Finally, note that if there are no commentary or definitions attached to
the paragraph then it's not necessary to type the initial <codeclass="display"><spanclass="extract-syntax">@</span></code>. That is,
<spanclass="plain-syntax"></span><spanclass="function-syntax">@<Prepare to exit@> =</span>
</pre><pclass="inwebparagraph"><aid="SP6"></a><b>§6. Conditional compilation. </b>In some languages, especially C, it's very hard to write a program which will
<pclass="inwebparagraph">...the definition of <codeclass="display"><spanclass="extract-syntax">THREADS_AVAILABLE</span></code> and the function <codeclass="display"><spanclass="extract-syntax">start_threads</span></code>
would be made only inside a <codeclass="display"><spanclass="extract-syntax">#ifdef PLATFORM_WINDOWS</span></code> clause; the same would
happen for any typedefs or <codeclass="display"><spanclass="extract-syntax">#include</span></code>s made.
</p>
<pclass="inwebparagraph">Similarly, tagging a paragraph <codeclass="display"><spanclass="extract-syntax">^"ifndef-SYMBOL"</span></code> causes it to have effect
only if <codeclass="display"><spanclass="extract-syntax">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>
<pclass="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>
<pclass="inwebparagraph"><aid="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>
<pclass="inwebparagraph"><aid="SP8"></a><b>§8. </b>A doubled hyphen becomes an em-rule; double-quotation marks automatically
smarten (in TeX format, at least).
</p>
<pclass="inwebparagraph"><aid="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
</li><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>
<pclass="inwebparagraph">A line which begins <codeclass="display"><spanclass="extract-syntax">(...)</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 <codeclass="display"><spanclass="extract-syntax">(-X)</span></code> will be treated as if it were <codeclass="display"><spanclass="extract-syntax">(X)</span></code>, but
<spanclass="plain-syntax"></span><spanclass="function-syntax">@</span><spanclass="plain-syntax"> Text placed between vertical strokes will be set in a fixed-space, code</span>
<spanclass="plain-syntax"> style font, |thus|. This paragraph appears in the web you are reading thus:</span>
<spanclass="plain-syntax"></span><spanclass="function-syntax">@</span><spanclass="plain-syntax"> Text placed between vertical strokes will be set in a fixed-space, code</span>
<spanclass="plain-syntax"> style font, %%thus%%. This paragraph appears in the web you are reading thus:</span>
</pre><pclass="inwebparagraph"><aid="SP11"></a><b>§11. </b>A line written thus:
<pclass="inwebparagraph">is typeset as an extract of text thus:
</p>
<blockquote>
<p>The monkey carries the blue scarf.</p>
</blockquote>
<pclass="inwebparagraph">(This is a feature used for Inform 7 "code" samples, those being essentially
natural language text.)
</p>
<pclass="inwebparagraph"><aid="SP12"></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:
<pclass="inwebparagraph">For further reading, see: <ahref="https://en.wikipedia.org/wiki/How_to_Avoid_Huge_Ships"class="external">https://en.wikipedia.org/wiki/How_to_Avoid_Huge_Ships</a>
</p>
<pclass="inwebparagraph">Note that URLs are considered to continue to the next white space, so don't
end them with full stops or commas.
</p>
<pclass="inwebparagraph">URLs will also be recognised in any text extract marked as <codeclass="display"><spanclass="extract-syntax">hyperlinked</span></code>.
</pre><pclass="inwebparagraph"><aid="SP14"></a><b>§14. Cross-references. </b>These are like links, but internal. These are normally written within <codeclass="display"><spanclass="extract-syntax">//</span></code>
<pclass="inwebparagraph">To see how cross-references are implemented, see <ahref="5-fm.html"class="internal">5-fm.html</a>,
or more generally the whole of <ahref="5-wt.html"class="internal">5-wt.html</a>; to decipher the text,
Inweb uses code from <ahref="../foundation-module/index.html"class="internal">../foundation-module/index.html</a> at <ahref="../foundation-module/8-wm.html"class="internal">../foundation-module/8-wm.html</a>.
</p>
<pclass="inwebparagraph">What happened in that last sentence is that Inweb noticed the following:
</p>
</li></ul>
<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>
<pclass="inwebparagraph">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>
<pclass="inwebparagraph"><aid="SP15"></a><b>§15. </b>Sometimes we want to make a link without literally showing the destination.
<pclass="inwebparagraph">produces: Individual lines of a web are stored in <ahref="2-lc.html#SP1"class="internal">2-lc.html#SP1</a> structures,
and mostly created by <ahref="2-tr.html#SP6"class="internal">2-tr.html#SP6</a>. And that should link to the
structure definition and function of these names inside the Inweb program.
</p>
<pclass="inwebparagraph">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 <ahref="M-mwiw.html"class="internal">M-mwiw.html</a>.
</p>
<pclass="inwebparagraph"><aid="SP17"></a><b>§17. </b>Cross-references also work inside text extracts marked as <codeclass="display"><spanclass="extract-syntax">hyperlinked</span></code>.
<pclass="inwebparagraph">This notation may be inconvenient if you need <codeclass="display"><spanclass="extract-syntax">//</span></code> for something else, but it
can be configured in the Contents page of a web, say like so:
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 <codeclass="display"><spanclass="extract-syntax">Figures</span></code>: for instance,
the weaver would seek <codeclass="display"><spanclass="extract-syntax">Fig_2_3.pdf</span></code> at pathname <codeclass="display"><spanclass="extract-syntax">Figures/Fig_2_3.pdf</span></code>.
</p>
<pclass="inwebparagraph">To embed an image, we write like so:
<pclass="inwebparagraph">The YouTube ID number <codeclass="display"><spanclass="extract-syntax">GR3aImy7dWw</span></code> can be read from its Share URL, which in
this case was <codeclass="display"><spanclass="extract-syntax">https://youtu.be/GR3aImy7dWw</span></code>.
<pclass="inwebparagraph">The latter sets just the height (of the displayed waveform, that is —
arguably music has width and not height, but SoundCloud thinks otherwise).
</p>
<pclass="inwebparagraph"><aid="SP21"></a><b>§21. </b>It's easy to add services. These are all handled by using prototype code
for a suitable HTML <codeclass="display"><spanclass="extract-syntax"><iframe></span></code>, and those prototypes are stored in the
<codeclass="display"><spanclass="extract-syntax">Embedding</span></code> subdirectory of the Inweb installation. But you can use your
own prototypes instead, by creating an <codeclass="display"><spanclass="extract-syntax">Embedding</span></code> subdirectory of your own
web; this overrides the ones built in. If your service is, say, <codeclass="display"><spanclass="extract-syntax">WebTubeo</span></code>,
then the file would be <codeclass="display"><spanclass="extract-syntax">W/Embedding/WebTubeo.html</span></code>.
</p>
<pclass="inwebparagraph"><aid="SP22"></a><b>§22. 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>
<pclass="inwebparagraph">For example, it's known that the average running time of Euclid's GCD
algorithm on \(a\) and numbers coprime to \(a\) is:
<pclass="inwebparagraph">(This is always <codeclass="display"><spanclass="extract-syntax">On</span></code>, the default, or <codeclass="display"><spanclass="extract-syntax">Off</span></code>.)
</p>
<pclass="inwebparagraph"><aid="SP23"></a><b>§23. Footnotes. </b>Not everyone likes footnotes,<supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup> but sometimes they're a tidy way to make
<ulclass="footnotetexts"><liclass="footnote"id="fn:1"><pclass="inwebfootnote"><supid="fnref:1"><ahref="#fn:1"rel="footnote">1</a></sup> But see Anthony Grafton, "The Footnote: A Curious History" (Harvard
University Press, 1999).
<ahref="#fnref:1"title="return to text">↩</a></p></li><liclass="footnote"id="fn:2"><pclass="inwebfootnote"><supid="fnref:2"><ahref="#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).
<ahref="#fnref:2"title="return to text">↩</a></p></li></ul><pclass="inwebparagraph"><aid="SP24"></a><b>§24. </b>The content of that sentence was typed as follows:
<spanclass="plain-syntax"></span><spanclass="identifier-syntax">[1]</span><spanclass="plain-syntax"> But see Anthony Grafton, "The Footnote: A Curious History" (Harvard</span>
<spanclass="plain-syntax"> University Press, 1999).</span>
<spanclass="plain-syntax"></span><spanclass="identifier-syntax">[2]</span><spanclass="plain-syntax"> For example, to cite Donald Knuth, "Evaluation of Porter's constant",</span>
<spanclass="plain-syntax"> Computers & Mathematics with Applications, 2, 137-39 (1976).</span>
<pclass="inwebparagraph">Footnotes are otherwise rendered by the <codeclass="display"><spanclass="extract-syntax">Bigfoot</span></code> plugin, which is the default
value of this; its big feet unfortunately tread on the <codeclass="display"><spanclass="extract-syntax">MathJax3</span></code> plugin, so
right now it's not possible to have mathematics in a footnote when <codeclass="display"><spanclass="extract-syntax">Bigfoot</span></code>
is in use.
</p>
<pclass="inwebparagraph"><aid="SP25"></a><b>§25. </b>Once again, notation may be an issue, and so it's controllable. By default,
<pclass="inwebparagraph">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>
<hrclass="tocbar">
<ulclass="toc"><li><ahref="M-wtaw.html">Back to 'Webs, Tangling and Weaving'</a></li><li><ahref="M-mwiw.html">Continue with 'Making Weaves into Websites'</a></li></ul><hrclass="tocbar">